s2s install tracking - Unity-Technologies/unity-ads GitHub Wiki
/*
Title: Configuring attribution links install tracking
Sort: 7
*/
To help launch CPI campaigns in Unity Ads, Unity allow developers to send install tracking information via a server-to-server integration, so the advertised applications do not need to be updated to include install tracking specifically for Unity Ads. This document explains how to integrate a third-party install tracking service or your own application servers in order to notify Unity Ads of new installs in your iOS and Android games.
A third party or in-house attribution service provider is needed to correctly run campaigns in Unity Ads. The following links refer to some common providers:
Branch (acquired Tune 2019)
If you already use a third party install tracking service provider such as the above, it's easy to configure attribution tracking links in Unity Ads to notify your install tracking service of views (or clicks), then configure a Unity Ads postback URL in your install tracking service to notify Unity Ads about the install conversions.
The Acquire dashboard lets you define a custom tracking URL for your campaigns. This URL reports the user’s identification at the time of impressions (or clicks) from the campaign to your install tracking service. The service then uses this information to attribute any subsequent installs to the correct ad network and make a callback to that network with the proper user details.
Make sure all your tracking URLs comply with the following requirements, otherwise the attribution will not work correctly.
- The URL and any redirection uses HTTPS.
- The URL contains the
{ifa}dynamic custom token (see below). - HTTP Redirections are executed via HTTP 3XX codes, not HTML or Javascript.
- The URL does not redirect to the Apple Store or Google Play.
If you use a tracking provider that does not support HTTPS, please contact us for assistance.
The following dynamically replaced tokens are available in the Tracking URL.
**Note: ** Costs are always reported in U.S. dollars.
| Token | Description | Example |
|---|---|---|
{ifa} (on iOS) |
The iOS Identifier for Advertising (IDFA) in plain text in its original uppercase form. | 1234ABCD-1234-5678-ABCD-1A2B3C4D5E6F |
{ifa} (on Android) |
The Google Advertising ID in its original lowercase form. This will replace the Android ID as the primary identification method on Android. During the transition phase, both identifiers need to run in parallel. | 1234ABCD-1234-5678-ABCD-1A2B3C4D5E6F |
{ifa_md5} (on iOS) |
The iOS Identifier for Advertising (IDFA) MD5-hashed from its original uppercase form. | 1234567890ABCDEFGHIJK123456ABCDEF |
{ifa_md5} (on Android) |
The Google Advertising ID MD5-hashed from its original lowercase form. | 1234567890ABCDEFGHIJK123456ABCDEF |
{android_id_md5} |
The MD5 hashed Android ID of the Android devices, in MD5 hashed form. This should only be used when the Google Advertising ID {ifa} is not available, such as instances when Google Play Services is not installed on the Android device. |
MD5 12345678ABCDEFGH = 123ABC456DEF789GHI012JKL345MNO67890
|
{ip} |
The IP address of the user. This is provided for informational purposes only, and is not suitable for user identification in install tracking. | 123.123.123.123 |
{country_code} |
The user’s ISO 3166-1 alpha-2 country code in upper case. Note: "GB" indicates the United Kingdom of Great Britain and Northern Ireland. |
GB |
{campaign_id} |
The Unity Ads campaign ID. | 12345678abcdefgh9012ijkl |
{campaign_name} |
The Unity Ads campaign name. | my_ad_campaign |
{game_id} |
The Unity Ads Game ID of the advertised game (the game being advertised). | 1234567 |
{gamer_id} |
The unique Unity Ads identifier mandatory for attributing users that have Limited Ad Tracking (LAT) on, where the value of the advertising identifier is 00000000-0000-0000-0000-000000000000. If gamerID is not found in this case, you will see a malformed error, response code 400. |
Malformed or missing input data |
{source_app_id} |
The universal source identifier of the app showing the ad. This is a case-sensitive alphanumeric string. Prior to migration in May 2020, this was represented by source_game_id. |
9g74cAw7WM1L |
{source_game_id} |
Deprecated as of May 11,2020. This is the Unity Ads Game ID of the game showing the ad. This has been replaced by source_app_id. |
7654321 |
{os} |
The operating system of the device. |
|
{device_type} |
The device type. |
|
{creative_pack} |
The name of the creative pack used in the ad. | Video Creatives Pack - EN - 15s |
{creative_pack_id} |
The unique identifier for the creative pack used in the ad. | 5beafbce74ed83001acb258c |
{language} |
The device language. | en-GB |
{user_agent} |
The device user agent. |
|
{device_make} |
The device maker. |
|
{device_model} |
The device model. |
|
{cpi} |
The cost per install that will be charged if this impression/view/click results in an install in CPI-billed campaigns. For CPM billed campaigns, the value represents the target cost per install, the tCPI. | 2.85 |
{cost_type} |
The billing type of the Unity Ads campaign. |
cpi or cpm. Currently, for iOS, this is always cpm
|
{cost_amount} |
The CPI in Unity Ads campaigns with CPI billing type. Or, the CPM for Unity Ads campaigns with CPM billing type. For impression tracking URLs this is greater than 0. |
4.9537. Divide by 1000 for actual spend accrual in CPM Unity Ads campaign. |
{cost_currency} |
The cost currency is always in US Dollars (USD). | USD |
{is_skadnetwork_supported} |
The status of the SKAdNetwork support. Note: Only available for iOS devices. |
true or empty. |
{video_orientation} |
The orientation of the creative shown in the ad. |
|
{screen_size} |
The screen size based on the targeting available in the Acquire dashboard. Note: Screen size is only available for Android devices. |
|
{screen_density} |
Only available on Android devices. The screen density based on the targeting available in the Acquire dashboard. Note: Screen density is only available for Android devices. |
|
As an example, the following AppsFlyer tracking URL:
https://app.appsflyer.com/id1234567890?idfa={ifa}&c={campaign_name}&af_sub2={source_app_id}&redirect=false
might appear as:
https://app.appsflyer.com/id1234567890?idfa=1234ABCD-1234-5678-ABCD-1A2B3C4D5E6F&c=Unity_Android_USA_Target&af_sub2=9g74cAw7WM1L&redirect=false
Note: The identifier Source (source_id) has been deprecated. It was replaced with SourceAppID (source_App_Id). The corresponding token has also been replaced, as shown in the table above.
The tracking URL can fire from an impression (when the user watches an ad) or a click (when the user clicks the download link from the ad). The server should respond with an HTTP 200 OK message
WARNING: Do not use a destination URL when generating the tracking URL from the 3rd-party attribution provider dashboard; the URL should not redirect to the Apple App Store or Google play. The tracking URL is only intended to track the ad impression on the click event. If the tracking URL redirects to the store, tracking will fail.
Unity Ads will load the respective store page in an app sheet to avoid directing the player outside of the game.
Converted users who install the advertised game as a result of the campaign are reported via a Postback URL. You can retrieve this reporting with HTTP GET requests.
For iOS, use the following URL:
https://postback.unityads.unity3d.com/games/[GAME_ID]/install?advertisingTrackingId=[YOUR_MACRO_FOR_IDFA]
For Android, use the following URL:
https://postback.unityads.unity3d.com/games/[GAME_ID]/install?advertisingTrackingId=[YOUR_MACRO_FOR_GOOGLE_AD_ID]
The GAME_ID parameter is your Unity Ads Game ID. You can find this ID by logging into the Acquire dashboard and selecting Campaigns.
Note: For existing users, the legacy impact.applifier.com domain will continue working in parallel with the new postback.unityads.unity3d.com domain. However, Unity encourages you to migrate to the new one.
The following identification parameters must be relayed in the Postback URL request:
| Parameter | Description | Example |
|---|---|---|
advertisingTrackingId (iOS) |
The Identifier for Advertising (IDFA) in uppercase form. This is compulsory for all installs (either raw form or MD5 hashed form). | XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |
advertisingTrackingIdMD5 (iOS) |
The Identifier for Advertising (IDFA) in MD5 hashed, lowercase form. This is compulsory for all installs (either raw form or MD5 hashed form). | |
advertisingTrackingId (Android) |
The Google Advertising ID in lowercase form. This is compulsory for all installs (either raw form or MD5 hashed form). | XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |
advertisingTrackingIdMD5 (Android) |
The Google Advertising ID in MD5 hashed, lowercase form. This is compulsory for all installs (either raw form or MD5 hashed form). | |
gamerId |
The unique Unity Ads identifier that is mandatory for attributing users that have Limited Ad Tracking (LAT) on, where the value of the advertising identifier is 00000000-0000-0000-0000-000000000000. If gamerID is not found in this case, you will see a malformed error, response code 400. Malformed or missing input data
|
58c116080dbe250047a2a398 |
installTimeEpoch |
Install time in seconds since epoch. This is mandatory for certain campaign types. | 1615973128 |
rawAndroidId |
The Android ID in its original lowercase form. Note: This is not recommended, as it is 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 which don't have a Google Advertising ID. |
|
androidId |
The Android ID in MD5 hashed form. Note: This is not recommended, as it is 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 which don't have a Google Advertising ID. |
|
attributed |
A flag denoting whether this install is attributed to Unity Ads and can be charged. The default value (attributed=1) indicates that the condition is true. If the condition is false (attributed=0), the install will only be marked to the player, and will not be charged.Note: this parameter should only used if all installs are sent instead of just attributed to Unity. |
|
Responses from Unity Ads' install tracking server are output as JSON files. If the message was received successfully, the server responds with a status field, with a value of ok. The server also always outputs its HTTP response code.
The response includes a parameter "install":true if the postback initiated the successful conversion of a chargeable install. If this was not a valid conversion (for example, if the user had already installed the game or the lookback window has passed), the response reads "install":false.
If the status field is not present, any available errors are available in the error field.
Note: The status code does not indicate whether this postback call was actually recorded as a chargeable install. It onlys states that the message was successfully received and processed. For the chargeable install, use the "install":true field instead.
This troubleshooting guideline goes through the most common problems related to mobile measurement partner (MMP) integrations. Please start troubleshooting by carefully going through your MMP's help documents.
Q. Why don't I see installs on Unity’s dashboard?
A. If you see installs appearing on your MMP's dashboard, but not on the Unity dashboard, this indicates that Unity is not receiving the correct install postbacks for your campaign. There can be several reasons for this:
- You may have entered the wrong game ID into your MMP dashboard. Double check that this is correct.
- The MMP is either not sending the postback, or it contains an error. Check with them that they are following this guide when sending the postbacks.
Q. Why don't I see installs on the MMP’s dashboard?
A. If the MMP has no install data, but your campaign is receiving traffic, check if:
- Your app integrated the MMP SDK correctly, or there is something blocking the SDK from sending the correct events. Your MMP will be able to help resolve this.
- Your tracking URLs are not be providing the information that your MMP requires. This guide contains information on how to use our tracking URL system.
Q. I fixed my MMP integration but now I'm not getting traffic. What can I do?
A. If a campaign launches with a broken integration, our data models will have an inaccurate estimate of the campaign's conversion rate, since we were not being notified about installs that were happening. This will need to be compensated for. The easiest way to do this is for you to temporarily boost your campaign's bid amount by 2-3x (or potentially more) to force our systems to deliver traffic again. Once we start receiving install data, you can lower the bid amount back down to a level you are happy with.
Q. Why does my install postback receive "install: false" in the response?
A. This may indicate an error in your postback parameters, but valid postbacks can sometimes also return this. We return an install status of false if the user has already been attributed (to avoid repeat charges for a single user), or if we were not able to attribute the user to a campaign view. If you would like us to investigate this, please contact support with the exact postback URL used along with the timestamp of when it was sent, and we can query the exact resolution of that postback.