Send secondary postbacks with a custom integration

Read time 5 minutes

To pass post-install event data to Unity using a custom server-to-server integration, use server requests to generate postbacks. Refer to this article for example postbacks that you can retrieve from your server.

Base URL
Base URL

Use the following base URL to send post-install even postbacks to Unity:

https://ads-secondary-conversion.unityads.unity3d.com/v1/events

Required event parameters
Required event parameters

Include the following components in your event query to pass post-install event data to Unity.

User identification
User identification

The following user identification parameters are required in your secondary postback URL:

ParameterDescriptionExampleNotes
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

Ad tracking setting
Ad tracking setting

The following ad tracking parameter is required in your secondary postback URL:

ParameterDescriptionExampleNotes
  • tracking_enabled=
  • tracking_limited=
A flag indicating whether the user has Limited Ad Tracking enabled
  • tracking_enabled=1
  • tracking_limited=0

Campaign identification
Campaign identification

The following campaign identification parameter is required in your secondary postback URL:

ParameterDescriptionExampleNotes
campaign_id
Unity Ads campaign identifier
546b9257365339e0031572bd
You can retrieve your Campaign ID from the Campaigns page of the User Acquisition dashboard.

Game identification
Game identification

The following game identification parameters are required in your secondary postback URL:

Base game identification
Base game identification

Include the following Game ID parameter in your URL:

ParameterDescriptionExampleNotes
gameId
Unity Ads Game ID
500009999
You can retrieve your Game ID from the Apps page for the User Acquisition dashboard

Platform identification
Platform identification

Include one of the following platform parameters with the Game ID in your URL:

ParameterDescriptionExampleNotes
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 Cloud dashboard.

Install timestamp
Install timestamp

The following timestamp parameter is required in your secondary postback URL:

ParameterDescriptionExampleNotes
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 identification
Event identification

Include one of the following event parameters in your secondary postback URL:

ParameterDescriptionExampleNotes
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}

Conversion attribution
Conversion attribution

The following conversion attribution parameter is required in your secondary postback URL:

ParameterDescriptionExampleNotes
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).

Example queries
Example queries

Refer to the following example secondary postback strings for sending post-install event data to Unity.

iOS session event
iOS session event

Use this reference as an example of a postback string for passing iOS session event data.

https://ads-secondary-conversion.unityads.unity3d.com/v1/events?ifa=AE06DF78-CA5A-46C3-BD44-1D3B6AA4D6E9&tracking_enabled=1&campaign_id=546b9257365339e0031572bd&game_id=500009999&platform=ios&store_id=123456789&event=session&ts=1466637860812&install_ts=1466637800175&was_conversion_attributed=1&gamer_id=88b48a1c94822c47b3458da3dd7aa42e9d0138a9d7036f05986fe9f763784d6887a215b69a83ca45e7b007399db6ccef20fe910b3758dd23d1cb318029d636e76428b0296d3f046f098eea964a4a711a1ce9559bcd159de21182d9f3

Android session event
Android session event

Use this reference as an example of a postback string for passing Android session event data.

https://ads-secondary-conversion.unityads.unity3d.com/v1/events?aid=ae06df78-ca5a-46c3-bd44-1d3b6aa4d6e9&tracking_enabled=1&campaign_id=546b9257365339e0031572bd&game_id=500009999&platform=android&store_id=com.example.store&event=session&ts=1466637860812&install_ts=1466637800175&was_conversion_attributed=1&gamer_id=88b48a1c94822c47b3458da3dd7aa42e9d0138a9d7036f05986fe9f763784d6887a215b69a83ca45e7b007399db6ccef20fe910b3758dd23d1cb318029d636e76428b0296d3f046f098eea964a4a711a1ce9559bcd159de21182d9f3

iOS purchase event
iOS purchase event

Use this reference as an example of a postback string for passing iOS purchase event data.

https://ads-secondary-conversion.unityads.unity3d.com/v1/events?ifa=AE06DF78-CA5A-46C3-BD44-1D3B6AA4D6E9&tracking_enabled=1&campaign_id=546b9257365339e0031572bd&game_id=500009999&platform=ios&store_id=123456789&event=purchase&value=1.0&currency=USD&ts=1466637860812&install_ts=1466637800175&was_conversion_attributed=1&gamer_id=88b48a1c94822c47b3458da3dd7aa42e9d0138a9d7036f05986fe9f763784d6887a215b69a83ca45e7b007399db6ccef20fe910b3758dd23d1cb318029d636e76428b0296d3f046f098eea964a4a711a1ce9559bcd159de21182d9f3

Android purchase event
Android purchase event

Use this reference as an example of a postback string for passing Android purchase event data.

https://ads-secondary-conversion.unityads.unity3d.com/v1/events?aid=ae06df78-ca5a-46c3-bd44-1d3b6aa4d6e9&tracking_enabled=1&campaign_id=546b9257365339e0031572bd&game_id=500009999&platform=android&store_id=com.example.store&event=purchase&value=1.0&currency=USD&ts=1466637860812&install_ts=1466637800175&was_conversion_attributed=1&gamer_id=88b48a1c94822c47b3458da3dd7aa42e9d0138a9d7036f05986fe9f763784d6887a215b69a83ca45e7b007399db6ccef20fe910b3758dd23d1cb318029d636e76428b0296d3f046f098eea964a4a711a1ce9559bcd159de21182d9f3

iOS ad revenue event
iOS ad revenue event

Use this reference as an example of a postback string for passing iOS ad revenue data.

https://ads-secondary-conversion.unityads.unity3d.com/v1/events?ifa=AE06DF78-CA5A-46C3-BD44-1D3B6AA4D6E9&tracking_enabled=1&campaign_id=546b9257365339e0031572bd&game_id=500009999&platform=ios&store_id=123456789&event=ad_revenue&revenue_usd=1.23&ts=1466637860812&install_ts=1466637800175&was_conversion_attributed=1&gamer_id=88b48a1c94822c47b3458da3dd7aa42e9d0138a9d7036f05986fe9f763784d6887a215b69a83ca45e7b007399db6ccef20fe910b3758dd23d1cb318029d636e76428b0296d3f046f098eea964a4a711a1ce9559bcd159de21182d9f3

Android ad revenue event
Android ad revenue event

Use this reference as an example of a postback string for passing Android ad revenue data.

https://ads-secondary-conversion.unityads.unity3d.com/v1/events?aid=ae06df78-ca5a-46c3-bd44-1d3b6aa4d6e9&tracking_enabled=1&campaign_id=546b9257365339e0031572bd&game_id=500009999&platform=android&store_id=com.example.store&event=ad_revenue&value=1.23&currency=USD&ts=1466637860812&install_ts=1466637800175&was_conversion_attributed=1&gamer_id=88b48a1c94822c47b3458da3dd7aa42e9d0138a9d7036f05986fe9f763784d6887a215b69a83ca45e7b007399db6ccef20fe910b3758dd23d1cb318029d636e76428b0296d3f046f098eea964a4a711a1ce9559bcd159de21182d9f3