Passing post-install events to Unity
Secondary conversion endpoint integration
Event parameters help refine Unity’s machine learning algorithm and improve campaign performance. Audience Pinpointer campaigns require session event data for retention optimization campaigns, and purchase event data for revenue optimization campaigns (for more information, see the Required Audience Pinpointer event parameters section below). Implement these post-install event callbacks through your third-party attribution partner.
Required Audience Pinpointer event parameters
You must include the following components with your event query for Audience Pinpointer campaigns.
Note: All parameters are case-sensitive.
Component | Parameter |
---|---|
Base URL | https://ads-secondary-conversion.unityads.unity3d.com/v1/events |
User identification | Mandatory identifier:
Note: Unity recommends passing ifa or aid to help diagnose potential issues with the incoming data. Passing gamer_id is required for running Audience Pinpointer campaigns, except in the case of limited tracking (LAT) users. |
Ad tracking setting | tracking_enabled={1|0} or tracking_limited={1|0} |
Campaign ID | campaign_id={Unity Ads campaign ID} |
Game identification | game_id={Unity Ads Game ID} (required; locate this on the main page of the advertising dashboard, listed under your game’s title) Plus one of the following:
ios , itunes , iOS , and iTunes . Accepted values for Android include android , google , Android , Google , gplay , and GooglePlay . |
Original install timestamp | install_ts={unix time in seconds or milliseconds} Note: The same parameter and value should be passed to Unity with the install attribution postback. |
Event identification | Identify which event was triggered by the user: event={event name} , where the event name is one of the following:
|
Original conversion attributed? | Indicate whether the original conversion of this user has been attributed to this network or not: was_conversion_attributed=1 |
Optional event parameters
Include the following optional components with your event query to help improve campaign performance.
Component | Parameter |
---|---|
Timestamp | ts={unix time in seconds or milliseconds} When the event happened. By default, the event happened at (or near) the time it was fired to the endpoint. |
Event identification | If the event is not a session or purchase event: event={event name} , where the event name is one of the following:
|
Test mode | test=1 This is a test event being fired to the service. It does not count as a real event from end users. |
Tracking partner | tracking_partner={tracking service name or other string to identify attribution provider} |
App name | app_name=Game+Name |
Advertiser name | advertiser_name=Advertiser+Name+In+Here |
Original impression timestamp | impression_ts=1234567890 Formatted as a Unix timestamp. |
Original click timestamp | click_ts=1234567890 Formatted as a Unix timestamp. |
IP address | ip=123.456.78.90 |
Ad network | ad_network=UnityAds |
Country | country=GB |
App version | app_version=1.2.3 |
Device type | Device model string: device_type=iPhone6,2 or device_type=samsung+GT-S7582 |
OS version | os_version=9.3.4 |
Language | language=en_US or language=en |
Session event example iOS
ios - https://ads-secondary-conversion.unityads.unity3d.com/v1/events?ifa=AE06DF78-CA5A-46C3-BD44-1D3B6AA4D6E9&tracking_enabled=1&campaign_id=546b9257365339e0031572bd&game_id=UNITY_ADS_GAME_ID&platform=ios&store_id=123456789&event=session&ts=1466637860812&install_ts=1466637800175&was_conversion_attributed=1&gamer_id=88b48a1c94822c47b3458da3dd7aa42e9d0138a9d7036f05986fe9f763784d6887a215b69a83ca45e7b007399db6ccef20fe910b3758dd23d1cb318029d636e76428b0296d3f046f098eea964a4a711a1ce9559bcd159de21182d9f3
Session event example android
https://ads-secondary-conversion.unityads.unity3d.com/v1/events?ifa=ae06df78-ca5a-46c3-bd44-1d3b6aa4d6e9&tracking_enabled=1&campaign_id=546b9257365339e0031572bd&game_id=UNITY_ADS_GAME_ID&platform=android&store_id=com.example.store&event=session&ts=1466637860812&install_ts=1466637800175&was_conversion_attributed=1&gamer_id=88b48a1c94822c47b3458da3dd7aa42e9d0138a9d7036f05986fe9f763784d6887a215b69a83ca45e7b007399db6ccef20fe910b3758dd23d1cb318029d636e76428b0296d3f046f098eea964a4a711a1ce9559bcd159de21182d9f3
Purchase event example iOS
https://ads-secondary-conversion.unityads.unity3d.com/v1/events?ifa=AE06DF78-CA5A-46C3-BD44-1D3B6AA4D6E9&tracking_enabled=1&campaign_id=546b9257365339e0031572bd&game_id=UNITY_ADS_GAME_ID&platform=ios&store_id=123456789&event=purchase&value=1.0¤cy=USD&ts=1466637860812&install_ts=1466637800175&was_conversion_attributed=1&gamer_id=88b48a1c94822c47b3458da3dd7aa42e9d0138a9d7036f05986fe9f763784d6887a215b69a83ca45e7b007399db6ccef20fe910b3758dd23d1cb318029d636e76428b0296d3f046f098eea964a4a711a1ce9559bcd159de21182d9f3
Purchase event example android
https://ads-secondary-conversion.unityads.unity3d.com/v1/events?ifa=ae06df78-ca5a-46c3-bd44-1d3b6aa4d6e9&tracking_enabled=1&campaign_id=546b9257365339e0031572bd&game_id=UNITY_ADS_GAME_ID&platform=android&store_id=com.example.store&event=purchase&value=1.0¤cy=USD&ts=1466637860812&install_ts=1466637800175&was_conversion_attributed=1&gamer_id=88b48a1c94822c47b3458da3dd7aa42e9d0138a9d7036f05986fe9f763784d6887a215b69a83ca45e7b007399db6ccef20fe910b3758dd23d1cb318029d636e76428b0296d3f046f098eea964a4a711a1ce9559bcd159de21182d9f3
SKAdNetwork postback integration for MMPs
This section describes the process Unity will use for the SKAdNetwork postback integration for Mobile Measurement Partners (MMP), if the MMP partner has registered their endpoint with us.
Upon receiving the postback from a device, this is the postback integration process for the SKAdNetwork:
- Unity will ensure that the signature is valid, then translate the SKAdNetwork
campaign-id
field back to our internal campaign id. - Unity will then send a JSON document to the respective MMP in a POST HTTP request, with the fields referenced in the table below.
JSON field name | Type | Description |
---|---|---|
ip | String | The IP address of the device sending the postback. iPv4 and IPv6 addresses possible. Example: "ip":"198.51.100.1" |
version | String | SKAdNetwork version. Example: "version":"2.0" |
app-id | Integer | Target app ID |
ad-network-id | String | Ad network ID. Example: "ad-network-id":"1232" |
campaign-id | Integer | SKAdNetwork campaign ID. Example: "campaign-id":23 |
ad-network-campaign-id | String | Unity’s internal campaign ID |
ad-network-campaign-name | String | Unity’s internal campaign name |
ad-network-id | String | Ad network ID. Example: "ad-network-id":"1232" |
ad-network-source-app-id | String | Unity's internal Source App ID. Only available if source-app-id is available in the original postback based on the privacy threshold. |
source-app-id | Integer | Source App Id (publisher). This field might not be present if the privacy threshold was not met. |
transaction-id | String | SKAdNetwork postback transaction ID |
attribution-signature | String | Attribution signature |
redownload | Boolean | When redownload is true, it means the user downloaded the app from the app store again. |
conversion-value | Integer | Conversion value set in the target app. This field might not be present if the privacy threshold was not met. |
timestamp | String | Time SKAdNetwork postback is received. 10-digit UNIX timestamp. Example: August 4, 2020, 07:25 UTC translates to "timestamp": "1596525944" |
ad-network-source-app-id | String | Unity’s internal Source App ID. Only available if source-app-id is available in the original postback based on the privacy threshold. |
Here is an example HTTP request being sent for an MMP registered with “https://mmp.example.com/skadnetwork-postback” as their endpoint:
POST /skadnetwork-postback HTTP/1.1
Host: mmp.example.com
Content-Type: application/json
{
"version":"2.0",
"app-id": 123456789,
"ip": "1.1.1.1",
"ad-network-campaign-name": "skadnetwork_campaign_1",
"ad-network-source-app-id": "h4sH3d",
"ad-network-id": "example123.skadnetwork",
"source-app-id": 525463029",
"transaction-id": "868eb3d91-15f5-44ee-9267-25c7655c20b6",
"redownload": false,
"attribution-signature": "MDYCGQCsQ4y8d4BlYU9b8Qb9BPWPi+ixk/OiRysCGQDZZ8fpJnuqs9my8iSQVbJO/oU1AXUROYU=",
"timestamp": "1597156649200",
"ad-network-campaign-id": "222222",
"conversion-value": 23,
"campaign-id": 99
}