Knowledge base

Server-to-Server (S2S) Install Tracking

To help launch CPI campaigns in Unity Ads, we 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 instructs you to integrate a third party install tracking service or your own application servers to notify Unity Ads of new installs in your iOS and Android games.

There are two main ways to perform a external install tracking in Unity Ads:

  • Winner-only Transmission – only those installs that originated from Unity Ads are reported back – the attribution is usually performed by a third party install tracking service.
  • Blanket Transmission – every new install is reported to Unity Ads and Unity Ads determines which installs are attributed to the Unity Ads campaigns based on if the user viewed or clicked the campaign within lookback window.

Winner-only Transmission Install Tracking

If you already use an external mobile install tracking service, such as AppsFlyer, Adjust, Mobile App Tracking by Tune, Kochava, etc. the Winner-only Transmission is your choice of install tracking methodology. You can easily configure a Tracking URL in Unity Ads to notify your install tracking service the views (or clicks) and then configure an Unity Ads Postback URL in your install tracking service to notify Unity Ads about the install conversions.

Tracking URL

The Unity Ads Admin Panel lets you define a Custom Tracking URL for your campaigns. This URL reports the user’s identification at impressions (or clicks) of the campaign to your install tracking service. This information is then used by the service to attribute any subsequent installs to the correct ad network and make a callback to that network with the proper user details.

Dynamic Custom Tracking URL Tokens

The following dynamically replaced tokens are available in the Tracking URL:

Token Description
{ifa} (on iOS) iOS Identifier for Advertising (IDFA) in plain text in its original (upper case) form: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX".
{ifa} (on Android) Google Advertising ID in its original (lower case) form: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx". This will replace the Android ID as the primary identification method on Android. During the transition phase, both identifiers need to be run in parallel.
{ifa_md5} (on iOS) iOS Identifier for Advertising (IDFA) in md5 hashed form, hashed from upper case form: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX".
{ifa_md5} (on Android) Google Advertising ID in md5 hashed form, hashed from (lower case) form: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".
{android_id_md5} MD5 hashed Android ID of the Android devices. This should only be used when the Google Advertising ID {ifa} is not available (when Google Play Services is not installed on the Android device). Only in MD5 hashed. For example: MD5 ("dc57ba135d7521d8") = "5e0572516f9657268ae0a7ef4f7a5bd1"
{ip} IP number of the user in the format “123.123.123.123″. This is provided as informational purposes only – not suitable for user identification in install tracking.
{country_code} User’s ISO 3166-1 alpha-2 country code in lower case (note: gb for the United Kingdom of Great Britain and Northern Ireland.)
{campaign_id} Unity Ads campaign ID, for example "546b9257365339e0031572bd"
{campaign_name} Unity Ads campaign name
{game_id} Unity Ads gameId for of the advertised game, for example "11004"
{source_game_id} Unity Ads gameId for of the publisher game where the user is seeing the ad, for example "11017"
{os} Operating system of the device, for example: "9.2.1" (iOS), "4.4.0" (Android)
{device_type} Device type, for example: "iPad4,1", "motorola XT1254", "samsung SM-G900F"
{creative_pack} Name of the creative pack, for example "Video Creatives Pack - EN - 15s"
{language} Device language, for example: "en-GB"
{user_agent} Device user agent, for example: "Mozilla/5.0 (iPhone; CPU iPhone OS 9_3_5 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Mobile/13G36" (iOS), "Mozilla/5.0 (Linux; Android 6.0.1; SM-G920V Build/MMB29K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/52.0.2743.98 Mobile Safari/537.36" (Android)
{device_make} Device maker, for example: "Apple" (iOS), "samsung" (Android)
{device_model} Device model, for example: "iPhone7,2" (iOS), "SM-G900F" (Android)
{cpi} Cost per install in $US for example: 2.85

IMPORTANT

Make sure ALL your tracking URLs comply with the following requirements, otherwise the attribution will not work correctly:

  • URL and any redirection uses HTTPS
  • URL contains at least the {ifa} dynamic custom token
  • HTTP Redirections should be done via HTTP 3XX codes and not via HTML/Javascript
  • URL does not redirect to the App Store or Google Play

If you are using a tracking provider that does not support HTTPS, please contact us in adops@unity3d.com and we will help you.

For example for an AppsFlyer Tracking URL:

https://app.appsflyer.com/id1063631875?idfa={ifa}&c={campaign_name}&af_sub2={source_game_id}&redirect=false

will be appear as:

https://app.appsflyer.com/id1063631875?idfa=9C528B70-E96D-4590-8766-2A40ED2B3573&c=Unity_Android_USA_Target&af_sub2=33333&redirect=false

Server responses to Impressions or Clicks

The Tracking URL can be fired either from an impression (i.e. when the user watched the campaign) or a click (when the user clicks the download link at the end screen after the video has ended). In both cases the URL should not redirect to the Apple App Store or Google play and the server should respond with an HTTP 200 OK. UnityAds SDK will load the respective store page in an app sheet to avoid directing the player outside of the game currently being player.

Postback URL Request

Reporting the converted users, i.e. the new installs of the campaign is done via a Postback URL. The installs can be reported with HTTP GET requests. The URL iOS is:

https://postback.unityads.unity3d.com/games/[GAME_ID]/install?advertisingTrackingId=[YOUR_MACRO_FOR_IDFA]

and in Android:

https://postback.unityads.unity3d.com/games/[GAME_ID]/install?advertisingTrackingId=[YOUR_MACRO_FOR_GOOGLE_AD_ID]

where GAME_ID is your Unity Ads Game ID. You can find this ID by logging into the Unity Ads Admin Panel and selecting Campaigns under ACQUIRE menu and looking at the Game list on the page. Note that, the iTunes ID or Google Play ID of your game should not be used in the place of the Unity Ads Game ID currently.

Note: For existing users, the legacy impact.applifier.com domain will continue working in parallel with the new postback.unityads.unity3d.com domain, but we encourage you to migrate to the new one.

Postback URL Parameters

The following identification parameters must be relayed in the Postback URL request. The supported parameters are:

Key Description
advertisingTrackingId (on iOS) Identifier for Advertising (IDFA) in the UPPERCASE form: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX". Compulsory for all installs (either raw form or md5 must be used).
advertisingTrackingIdMD5 (on iOS) Identifier for Advertising (IDFA) in md5 hashed form, hashed from UPPERCASE form: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX". Compulsory for all installs (either raw form or md5 must be used).
advertisingTrackingId (on Android) Google Advertising ID in the lowercase form: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx". Compulsory for all installs whenever available (either raw form or md5 must be used).
advertisingTrackingIdMD5 (on Android) Google Advertising ID in md5 hashed form, hashed from lowercase form: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx". Compulsory for all installs whenever available (either raw form or md5 must be used).
rawAndroidId Android ID (from its original lower case form). Not recommended. This parameter is not needed if the Android device has correctly integrated Google Play Services and has Google Play installed. It is compulsory for all Android installs which don't have Google Advertising ID (Devices that don't have Google Play Services and related integrated)
AndroidId Android ID (an MD5 hash from its original form). Not recommended. This parameter is not needed if the Android device has correctly integrated Google Play Services and has Google Play installed. It is compulsory for all Android installs which don't have Google Advertising ID (Devices that don't have Google Play Services and related integrated)
attributed Flag (1 or 0) denoting whether this install is attributed to Unity Ads and can be charged. The default is attributed=1. With attributed=0, the install will only be marked to the player and will not be charged. Note: this parameter should only used if using Blanket Transmission, i.e. all installs are sent instead of just attributed.

Postback URL Response Format

Responses from Unity Ads' install tracking server are output as JSON. If the message was received successfully, the server will respond with a status field, with the value of ok. The server also always outputs it’s HTTP response code.

The response includes a parameter "install":true if the postback initiated a successful conversion, i.e. a chargeable install. If this was not a valid conversion, for instance, the user had already installed the game or the lookback window has passed, the response will read "install":false.

In addition, in case the conversion was successful the source game id is displayed in a sourceGame parameter. Advertiser can use this parameter to block certain source games or publishers based on the quality of traffic they produce. If the conversion was not successful, the sourceGame parameter is omitted.

Example:

{"install":true,"sourceGame":"11007","responseCode":200,"status":"ok"}

If the status field is not present, any available errors are available in the field error.

Note: the status code does not indicate whether this postback call was actually recorded as a chargeable install in the Unity Ads. It onlys states that the message was successfully received and processed. For the chargeable install, use the "install":true instead.

Instructions for 3rd party install tracking services

AppsFlyer

AppsFlyer provide really good documentation on their official support site:

Adjust

Adjust provide really good documentation on their official support site:

MobileAppTracking by Tune (previously HasOffers)

MAT provide really good documentation on their official support site:

Kochava

To configure Unity Ads campaign tracking via Kochava, please repeat the following steps:

Tracking URL:

  1. For iOS, insert
&device_id={ifa_md5}&site_id=1&device_hash_method=MD5&device_id_is_hashed=true&device_id_type=idfa

and for Android

&device_id={android_id_md5}&site_id=1&device_hash_method=md5&device_id_is_hashed=true&device_id_type=android_id&adid={ifa}&pbr=1

after your tracking URL without the device identification, for example:

https://control.kochava.com/v1/cpi/click?campaign_id=YOUR_KOCHAVA_CAMPAIGN_ID&network_id=KOCHAVA_NETWORK_ID&creative_id=1&device_id={ifa_md5}&site_id=1&device_id_hash_method=MD5&device_id_is_hashed=true&device_id_type=idfa&mac_md5={mac_address_md5}

to the Custom Tracking URL field.

  1. Request Kochava to turn off the redirection from your Tracking URL
  2. Uncheck the box: This URL redirects to AppStore / Google Play Store
Postback URL:
  1. Request Kochava to add your Unity Ads Game ID in their system
  2. Select Applifier from the list of integration partners in the Postback Conversion report

Blanket Transmission Install Tracking Explained

If you do not use any third party install tracking services already, a good alternative for the Winner-only Transmission is the Blanket Transmission install tracking method. In this, you will report all of your new installs to the Unity Ads postback URL and let Unity Ads to determine which Install came through Unity Ads. Specifically, a user, who has never installed your application before, watched an Unity Ads campaign video and installed and started up your game within 72 hours from the video view, will be counted as a chargeable install for your campaign.

To be able to use server-to-server install tracking, your game must already be sending the Identifier for Advertising address to your own servers. Whenever your system gets a new user, that user’s advertising ID must be sent from your servers to Unity Ads servers. Unity Ads then compares these identifiers to those that have seen ads promoting your application. If a match is found, that user is counted as an install via Unity Ads.

The install tracking is performed by sending the Identifier for Advertising on iOS and Google Advertising ID and/or Android ID on Android .

Note: Install tracking only works for iOS6 and onwards. iOS5 devices are no longer supported.

The installed users are reported identically than in the Winner-only transmission. See the Postback URL Request section above for details.

Still need help? Get in touch!
Last updated on 24th Feb 2017