Send secondary postbacks with a custom integration

Send post-install event data to Unity Ads using custom server-to-server postbacks by constructing requests with required user, campaign, game, event, and attribution parameters for each app event.

Read time 4 minutes

Last updated 6 months ago

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

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

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

User identification

You must include the following user identification parameters in your secondary postback URL:

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`

Ad tracking setting

You must include the following ad tracking parameter in your secondary postback URL:

Parameter	Description	Example	Notes
`tracking_enabled=` `tracking_limited=`	A flag indicating whether the user has Limited Ad Tracking enabled	`tracking_enabled=1` `tracking_limited=0`

Campaign identification

You must include the following campaign identification parameter in your secondary postback URL:

Parameter	Description	Example	Notes
`campaign_id`	Unity Ads campaign identifier	`546b9257365339e0031572bd`	You can retrieve your Campaign ID from the Campaigns page of the User Acquisition dashboard.

Game identification

You must include the following game identification parameters in your secondary postback URL:

Base game identification

Include the following Game ID parameter in your URL:

Parameter	Description	Example	Notes
`game_id`	Unity Ads advertiser 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 identification

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

Parameter	Description	Example	Notes
`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.

Parameter

Description

Example

Notes

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 timestamp

You must include the following timestamp parameter in your secondary postback URL:

Parameter	Description	Example	Notes
`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

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

Parameter	Description	Example	Notes
`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

You must include the following conversion attribution parameter in your secondary postback URL:

Parameter	Description	Example	Notes
`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

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

Session event

Use these references as examples of postback strings for passing 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


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

Purchase event

Use these references as examples of postback strings for passing 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


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

Ad revenue event

Use these references as examples of postback strings for passing 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


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