Track installs with a server-to-server integration

To help launch install campaigns in Unity Ads, developers can send install tracking information by using a server-to-server integration. This ensures that 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.

Note: Activating unattributed installs can help to improve Acquire data models and campaign performance.

Mobile measurement partners

To correctly run Unity ad campaigns, you must have a third-party or in-house attribution service provider (also known as a mobile measurement partner or MMP). The following links provide information about some common providers:

Note: Branch acquired Tune in 2019.

If you already use an MMP, you need to configure attribution tracking links to notify them of views or clicks, then configure a Unity Ads postback URL to notify Unity Ads about the install conversions.

Tracking URLs

Use the Growth dashboard to define custom tracking URLs 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 uses this information to attribute any subsequent installs to the correct ad network and then make a callback to that network with the proper user details.

URL requirements

Your tracking URLs must comply with the following requirements:

  • The URL and any redirection uses HTTPS.

  • The URL contains the {ifa} dynamic custom token (see below).

  • HTTP Redirections are executed by usingHTTP 3XX codes, not HTML or Javascript.

  • The URL does not redirect to the Apple App Store or the Google Play Store.

If your MMP does not support HTTPS, contact Unity for assistance.

Dynamic custom tracking URL tokens

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

Token Description Example
{ifa} (iOS) The iOS Identifier for Advertising (IDFA) in plain text in its original uppercase form. 1234ABCD-1234-5678-ABCD-1A2B3C4D5E6F
{ifa} (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} (iOS) The iOS Identifier for Advertising (IDFA) MD5-hashed from its original uppercase form. 1234567890ABCDEFGHIJK123456ABCDEF
{ifa_md5} (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 end-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. 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 the gamer ID 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}

Important: This field is deprecated as of May 11, 2020. This has been replaced by source_app_id.

7654321
{os} The operating system of the end-user's device.
  • 9.2.1 (iOS)
  • 4.4.0 (Android)
{device_type} The end-user's device type.
  • iPad4,1
  • motorola XT1254
  • samsung SM-G900F
{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 end-user's device language. en-GB
{user_agent} The end-user's device user agent.
  • 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} The end-user's device make.
  • Apple (iOS)
  • samsung (Android)
{device_model} The end-user's device model.
  • iPhone7,2 (iOS)
  • SM-G900F (Android)
{cpi} For CPI campaigns, this value is the cost to the advertiser if this impression results in an attributed install. For CPM campaigns, this value represents the target cost per install, or tCPI. For more information, see documentation on bidding for install campaigns. 2.85
{cost_type} The campaign's billing type. cpi or cpm. Currently, for iOS, this is always cpm.
{cost_amount} The cost per install. For impression tracking URLs, this must be greater than 0.

Note: For CPM campaigns, divide this value by 1000 to calculate the actual spend accrual.

4.9537
{cost_currency} The cost currency is always in US dollars (USD). USD
{is_skadnetwork_supported} The SKAdNetwork support status.

Note: This field is only available for iOS devices.

true or empty.
{video_orientation} The orientation of the creative shown in the ad.
  • portrait
  • landscape
{screen_size} The screen size based on device targeting.

Note: This field is only available for Android devices.

  • small
  • normal
  • large
  • xlarge
{screen_density} The screen density based on device targeting.

Note: This field is only available for Android devices.

  • ldpi
  • mdpi
  • hdpi
  • xhdpi
  • xxhdpi
  • xxxhdpi

Server responses to impressions or clicks

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.

Important: Do not use a destination URL when generating the tracking URL from the third-party attribution provider dashboard. The URL should not redirect to the Apple App Store or Google Play Store. 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 loads the respective store page in an app sheet to avoid directing the player outside of the game.

Postback URL requests

Converted users who install the advertised game as a result of the campaign are reported by using a postback URL. You can retrieve this reporting with HTTP GET requests.

For iOS, use the following URL:

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

For Android, use the following URL:

Copy
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 signing in to the Growth 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, we recommend that you migrate to the new domain.

Postback URL parameters

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 because 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 that don't have a Google Advertising ID.

androidId The Android ID in MD5 hashed form.

Note: This is not recommended because 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 that don't have a Google Advertising ID.

attributed A flag indicating 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: Only use this parameter if you send event data for all installs, as opposed to only sending installs attributed to Unity.

  • attributed=1
  • attributed=0

Postback URL response format

If the message was successfully received, the Unity Ads install tracking server responds with a 200 OK status code without a response body.

If the message cannot be processed, the server responds with a 4XX/5XX status code, and any available errors appear in the response body in JSON format.

Note: The status code does not indicate if this postback call was actually recorded as a chargeable install. It only states that the message was successfully received and processed.

Next steps: Activate unattributed installs.