Custom integration postback request reference

Send server-to-server postback requests to Unity Ads to report installs and post-install events for accurate attribution in a custom integration.

Read time 5 minutes

Last updated 6 months ago

Review the following parameters to ensure you format your custom integration postback request correctly.

Required attribution postback parameters

You must relay the following identification parameters in your custom integration postback request:

Parameter	Description	Example	Notes
`advertisingTrackingId` (iOS)	The Identifier for Advertising (IDFA) in uppercase form.	`1A2B3C4D-5E6F-7G8H-9I10-J9K8L7M65N4P`	The IDFA is compulsory for all installs. You can use the raw or hashed form of the ID.
`advertisingTrackingIdMD5` (iOS)	The Identifier for Advertising (IDFA) in hashed, lowercase form.	`fce1e02f2ca0498021ec67f2f22dfcea`	The IDFA is compulsory for all installs. You can use the raw or hashed form of the ID.
`advertisingTrackingId` (Android)	The Google Advertising ID in lowercase form.	`a1b2-c3d4-e5f6-g7h8`	The Advertising ID is compulsory for all installs. You can use the raw or hashed form of the ID.
`advertisingTrackingIdMD5` (Android)	The Google Advertising ID in MD5 hashed, lowercase form.	`6fbff11856d5f0200d473af3cabd346d`	The Advertising ID is compulsory for all installs. You can use the raw or hashed form of the ID.
`gamerId`	The unique Unity Ads identifier that is mandatory for attributing users that have Limited Ad Tracking (LAT) on.	`00000000-0000-0000-0000-000000000000`	The value of the `gamer_id` parameter should be taken from starts, views, or clicks sent for attribution. If the `gamerID` is not formatted correctly, a `malformed` error will appear, with response code 400: `Malformed or missing input data` .
`installTimeEpoch`	Install time in seconds since epoch.	`1615973128`	This parameter is mandatory for some campaign goals.
`rawAndroidId`	The Android ID in its original lowercase form.	`3f4a92b6c1d8e90f`	The `rawAndroidID` parameter isn't recommended because it's not required if the Android device has correctly integrated Google Play Services and has Google Play installed. It is, however, compulsory for all Android installs that don't have a Google Advertising ID.
`androidId`	The Android ID in MD5 hashed form.	`4a969d593d2a3e1d602fefe8e75a4d80`	This isn't recommended because it's not required if the Android device has correctly integrated Google Play Services and has Google Play installed. It is, however, compulsory for all Android installs that don't have a Google Advertising ID.
`attributed`	A flag indicating whether this install is attributed to Unity Ads and can be charged.	`attributed=1` `attributed=0`	The default value ( `attributed=1` ) indicates that the condition is true. If the condition is false ( `attributed=0` ), the install is unattributed and won't be charged. Only use this parameter if you send event data for all installs, as opposed to only sending installs attributed to Unity.

Required post-install event postback parameters

Relay the following identification parameters in your custom integration postback request:

Parameter	Description	Example	Notes
`gamer_id=`	The Unity Ads unique Gamer ID for the installing user	`gamer_id=00000000-0000-0000-0000-000000000000`
`ifa=` (iOS) `idfa=`	Apple advertising identifier (IDFA) for a device in uppercase form.	`ifa=1A2B3C4D-5E6F-7G8H-9I10-J9K8L7M65N4P`	The IDFA is compulsory for all installs. You can use the raw or hashed form of the ID.
`aid=` (Android)	Google Play Advertising ID in lowercase form	`aid=ae06df78-ca5a-46c3-bd44-1d3b6aa4d6e9`
`android_id_md5=` (Android)	MD5 hash of the Google Advertising ID in lowercase form	`android_id_md5=6fbff11856d5f0200d473af3cabd346d`
`tracking_enabled=` `tracking_limited=`	A flag indicating whether the user has Limited Ad Tracking enabled	`tracking_enabled=1` `tracking_limited=0`
`campaign_id=`	Unity Ads campaign identifier	`campaign_id=546b9257365339e0031572bd`	You can retrieve your Campaign ID from the Campaigns page of the User Acquisition dashboard.
`game_id=`	Unity Ads Game ID	`game_id=500009999`	Ensure that you retrieve your advertiser Game ID from the User Acquisition dashboard. Don't use the publisher Game ID used in SDK integration from the Monetization dashboard.
`platform={ios or android}&store_id={itunes id or googleplay id}`	Platform + Store ID	`platform=ios&store_id=123456789` `platform=android&store_id=com.example.store`	You can use the following values for iOS: `ios` `itunes` `iOS` `iTunes`
`platform={ios or android}&bundle_id={bundle id}`	Platform + Bundle ID	`platform=ios&bundle_id=com.example.myapp`	You can use the following values for Android: `android` `google` `Android` `Google` `gplay` `GooglePlay`
`platform={ios or android}&project_id={Unity Project ID}`	Platform + Unity Project ID	`platform=android&project_id=2ff453g1-8d49-2p06-n22f-9m833592113f2`	You can retrieve your Project ID from the Settings tab of any of your Projects in the Unity Dashboard.
`install_ts={unix time in seconds or milliseconds}`	Original install timestamp in unix format	`install_ts=1466637800175`	Milliseconds are the recommended best practice for timestamps.
`event=session`	Session event flag indicating the user started a gameplay session	`event=session`
`event=purchase&value{amount}&currency={currency}`	Purchase event flag indicating that the user completed an in-app purchase + the transaction amount	`event=purchase&value=1.0&currency=USD`	The recommended best practice is to use USD for currency.
`event=ad_revenue&value{amount}&currency={currency}`	Ad revenue event flag indicating that the user generated ad revenue + the revenue amount	`event=ad_revenue&value=1.23&currency=EUR` `event=ad_revenue&revenue_usd=1.23`	Format revenue values as a decimal. For example: `1.05` . If you use USD for currency, you can send `revenue_usd={amount}` instead of `value{amount}&currency={currency}`
`was_conversion_attributed=`	Flag indicating whether the original install was attributed to Unity	`was_conversion_attributed=1`	Use `1` to indicate that the original install was attributed to Unity. Use `0` to indicate that the original install was unattributed (not attributed to Unity).

Optional secondary postback parameters

The following post-install event parameters are not required. Use these parameters in your GET request to retrieve additional information about your app's post-install events.

Parameter	Description	Example	Notes
`ts=`	Timestamp of post-install event in Unix format	`ts=1466637800123`	Use Unix formatting for all timestamps. The recommended best practice is milliseconds, but Unity also supports timestamps in seconds.
`ip=`	User's IP address	`ip=123.456.78.90`
`ad_network=`	Ad network name	`ad_network=UnityAds`
`country=`	User's ISO 3166-1 alpha-2 country code	`country=US`
`app_version=`	App version number	`app_version=1.2.3`
`device_type=`	Device model name	`device_type=iPhone6,2 device_type=samsung+GT-S7582`
`os_version=`	Device OS version	`os_version=14.4.2`
`language=`	User's ISO 639-1 language code	`language=en_US`
`ad_format=`	Type of ad shown. For example: interstitial, rewarded, playable, or banner	`ad_format=interstitial`	This parameter is only relevant for `ad_revenue` events and describes the format of the ad shown. These are some of the most common ad formats: `interstitial` `rewarded` `playable` `video banner`
`event=`	Event name for post-install events other than `session` , `purchase` , or `ad_revenue`	`event=ad_view` `event=registration` `event=spent_credits` `event=invite` `event=share` `event=level_complete` `event=tutorial_complete` `event=achievement_unlocked` `event=custom_event`	Use one of the following supported event names with `event={event name}` : `registration` : The user registered to the app. `spent_credits` : The user spent virtual currency to buy in-game items. You can also specify these optional `spent_credits` parameters: `value={how many credits}` `type={what type credits}` `invite` : The user invited friends to the game. `share` : The user shared the game with friends. `level_complete` : The user completed a level. You can also specify this optional `level complete` parameter: `value={level name}` `tutorial_complete` : The user completed a tutorial. `achievement_unlocked` : The user unlocked an achievement. `custom` : A custom event occurred. You can also specify these optional `custom` event parameters: `custom_event={custom_event_name}` `value={value}&type={type}`
`tracking_partner=`	Name of the tracking service or Mobile Measurement Partner (MMP)	`tracking_partner=AppsFlyer`
`app_name=`	App name	`app_name=Game+Name`
`advertiser_name=`	Name of the advertiser	`advertiser_name=Advertiser+Name+In+Here`
`impression_ts=`	Timestamp of when the ad impression occurred in Unix format	`impression_ts=1466637800123`	Use Unix formatting for all timestamps. The recommended best practice is milliseconds, but Unity also supports timestamps in seconds.
`click_ts=`	Timestamp of when the ad click occurred in Unix format	`click_ts=1466637800456`	Use Unix formatting for all timestamps. The recommended best practice is milliseconds, but Unity also supports timestamps in seconds.
`test=`	A test postback from the server that doesn't count as a real event from end users	`test=1`

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Unity Ads User Acquisition

Advertising Management API

Advertising Statistics API

Unity Ads User Acquisition

Custom integration postback request reference

Required attribution postback parameters

Parameter

Description

Example

Notes

Required post-install event postback parameters

Parameter

Description

Example

Notes

Optional secondary postback parameters

Parameter

Description

Example

Notes