s2s install tracking - unity-cn/unityads-help-cn GitHub Wiki

/*
Title: Server-to-Server (S2S) Install Tracking
Sort: 21
*/

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.

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.

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.

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

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 [email protected] 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

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.

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.

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

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.

AppsFlyer provide really good documentation on their official support site:

• AppsFlyer support
• UnityAds (former Applifier) integration

Adjust provide really good documentation on their official support site:

• Adjust tracker generation
• UnityAds integration

To configure your Unity Ads campaign tracking via MobileAppTracking by Tune:

1. Select Unity Ads from the available Ad Networks list from the HasOffers panel
2. Select the offer from your offer’s list. Leave the destination at Default
3. Hit Generate Link button
4. Hit the Copy button to copy the link to your clipboard
5. Paste the link to the Unity Ads Tracking URL field
6. Enable sending the postback call to Unity Ads’s Postback URL

The MobileAppTracking postback URL will be configured automatically and your game ID is sent with the link automatically to MobileAppTracking. You just need to enable sending the postback call.

Note: If you edit the tracking URL, DO NOT edit or remove the existing parameters.

The following images show how the Tracking Link is generated from the MobileAppTracking panel:

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

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

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.