post install events - Unity-Technologies/unity-ads GitHub Wiki
/*
Title: Passing post-install events to Unity
Sort: 8
*/
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.
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
|
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
|
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
https://ads-secondary-conversion.unityads.unity3d.com/v1/events?aid=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
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
https://ads-secondary-conversion.unityads.unity3d.com/v1/events?aid=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
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 |
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" |
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
}
With SKAdNetwork postbacks, the primary measure for your campaign performance is the conversion value. This is an integer from 0 to 63.
Assign the conversion value based on the user’s in-game behaviour to evaluate your campaign performance across different ad networks and source apps. There is a 24-hour postback timer that resets with each conversion value update - the longer the tracking window, the more difficult it will be to act swiftly regarding campaign performance.
Most MMPs provide templates and tools for mapping in-game events or revenue to the conversion value. User acquisition with Unity does not require adhering to a specific conversion model, and there is no one-size-fits-all-advertisers solution. However, for advertisers in search of guidance Unity recommends the following best practices.
Events associated with each conversion value should be ordered from lowest to highest according to some key metric. For example, if tracking player value, then a player who makes an in-app purchase is usually associated with a higher average value than a player who watches a rewarded ad.
Limit conversion value updates to the 48-hour period after install
The measurement period should be fairly brief, with the last update to conversion value occurring within 48 hours of install. Typically by this time your retention curve is already flattening, and 50-70% of your paying users have made their first purchase. This should be enough time for you to rank ad network and campaign performance, and to identify the most valuable sources.
More granular measurement is not necessarily better.
The SKAdNetwork privacy threshold means that source app IDs and conversion values will only be provided when they cannot be used to identify individual users.
This means you must have enough users with each source app ID and conversion value combination in order to receive these two fields in the SKAdNetwork postbacks. Therefore, tracking events that your users are unlikely to perform will be difficult, unless you have very high volumes of installs. Unity recommends that your conversion value mapping tracks relatively common events that split your user base approximately into groupings of the top 10%-20%, the next 20-40%, and so on.
As far as SKAdNetwork and Apple’s AppTrackingTransparency framework are concerned, the industry is still in a transition and learning phase. We believe that the best way forward is to start with something simple and follow an experimental, iterative approach along the following steps:
At first, advertisers will start using the conversion value for reporting, alongside more traditional and granular metrics. Users who give their permission for tracking will provide a reliable benchmark for the conversion value based reporting. With the basics in place, advertisers will experiment to find the best way to set the conversion value to optimize their user acquisition budgets based on user value and return on investment. Ad networks will build on the initial learnings and start using the conversion values to encode source app quality into their automated optimization algorithms.
If you don’t have a preference or you’re unsure about where to start with the conversion value, Unity recommends the following example baseline setup using the conversion value to track the number of sessions within the first 48 hours.
Event | Conversion value | Session# | Share of installs |
---|---|---|---|
Install | 0 | 1 | 33% |
Second Session | 1 | 2 | 23% |
Third Session | 1 | 3 | 13% |
Fourth & Fifth session | 3 | 4 and 5 | 15% |
Six+ session | 4 | 6 | 16% |
Notes about this table:
- Events are within 48 hours of install
- At Install, the app calls
registerApforAdNetworkAttribution
- For the second and additional sessions, the app calls
updateConversionValue
Higher numbers of sessions in the first 48 hours are correlated with higher retention and LTV, so this is a good starting point for you to track the quality of installs you are receiving. Of course, you can continue to experiment and build on this to find a conversion value setup that is optimal for you.
Please also see the ios14 Advertiser Guide to learn how to set SKAdNetwork conversion values.