Measuring Clicks

The standard way for our TUNE links for clicks to be used is as a redirect. User clicks on ad, ad redirects to our TUNE link, our Measurement API redirects user to app store. While this is the simplest implementation, it doesn't provide the best user experience. Instead, our TUNE links can be called asynchronously client-side or even server-side. By notifying our TUNE links in this manner, the user can then be directed from ad click directly to app store without the third-party redirect that our TUNE link typically requires.

Server-side-click-notification-New-Page

TUNE Link Construction & Requirements

Required SLA for Attribution

When implementing our TUNE links for clients in the default manner as a client-side redirect, we measure the click in real-time.

If you plan to notify us of clicks asynchronously client-side or even server-side, then you must notify our Measurement API of the click within 5 seconds. If you fail to notify us within the 5-second window, and the open or install or event happens immediately thereafter, then the click is not used for attribution because the install or event will already be processed. We do delay full attribution of opens, installs, and events by 5 seconds to ensure that slight delays won’t negatively affect attribution.

Base URL

The base domain for the Measurement API:

https://YOUR_PUBLISHER_ID.api-01.com/serve

YOUR_PUBLISHER_ID should be replaced with the ID of the publisher account that you're using (as defined by TUNE).

Required Click Parameters

The basic URL to measure clicks will include:

  1. action=click
  2. publisher_id – ID of publisher created by TUNE and provided by advertiser
  3. site_id – ID of the mobile app created by TUNE and provided by advertiser

Advertisers may specify these parameters as well:

  • campaign_id – ID of the mobile app created by TUNE and provided by advertiser

Additional Required parameters

Since you'll be notifying us of clicks to this Measurement API likely server-side or asynchronously client-side, you will need to add these additional parameters to all TUNE links for clicks:

  1. device_ip – IP address of the user device recorded on conversion. You can find the device IP in the header of the request that you receive from the user device.
  2. response_format=json – Notifies TUNE that server-side attribution is being used and returns a server-friendly JSON response.

If you can't include the device IP, please set our country code.

  • country_code – The ISO ALPHA-2 or ISO ALPHA-3 value of the country. For a complete list of ISO-compliant country codes, please visit Country Codes.

Required Cost parameters

Our Measurement API supports two required parameters to collect cost data dynamically so we can provide cost reconciliation and ROI analysis:

  1. cost_model – predefined values of one of these supported models when measuring clicks that you use to bill clients for their marketing campaigns:
    • cpc – Cost per Click
    • cpi – Cost per Install
    • cpa – Cost per Action
    • cpo– Cost per Open
  2. cost – Amount of cost formatted as float. Supports 5 decimal places. Must be in USD.

Learn more about how we support Collecting Cost Data Dynamically.

Your Optimization Parameters

You can also include sub parameters to allow clients to gain more valuable insight into their advertising campaign performance.

  • sub_publisher – Name or ID of the down-stream publisher.
  • sub_site – Name or ID of the site or mobile app the campaign is in/on.
  • sub_campaign – Name or ID of the campaign on in partner's platform.
  • sub_adgroup – Name or ID of the ad group in campaign on partner's platform.
  • sub_ad – Name or ID of an ad in campaign on partner's platform.
  • sub_keyword – Name or ID of the keyword specific to Google AdWords integration and other search campaigns.
  • sub_placement – Name or ID of an ad placement (position of ad on a web site or in an app).

Your Reconciliation Parameters

If you have your own click ID that you need for us to pass back to you in server postback notifications, use our ref_id parameter.

  • ref_id – Internal reference ID parameter that you can use for your own ID values (such as impression, click, session, or tracking ID). This reference ID is typically used by publishers for reconciliation with their own third-party system.

We also support five additional sub parameters. These additional parameters are available in the Log and Server Postback reports, and typically store unique information.

  • sub1 – String of additional information specified by you.
  • sub2 – String of additional information specified by you.
  • sub3 – String of additional information specified by you.
  • sub4 – String of additional information specified by you.
  • sub5 – String of additional information specified by you.

Methods & Requirements for Click-through Attribution

After you have the above down, based on your type of traffic you’ll need to include parameters in the TUNE link for clicks to ensure we are able to do attribution:

Using Device Identifiers

To use unique identifier matching for attribution, TUNE requires you to append the following parameters to your tracking links:

  • google_aid – The Google Advertising Identifier or the Android ID (Android only).
  • ios_ifa – The Apple Identifier for Advertisers value (iOS only). *See NOTE below if using iOS10.
  • windows_aid – The Windows Advertising Identifier (Windows only).

To collect these values from an SDK, use the appropriate platform code snippets found at Settings for Device Identifiers.

Note: The TUNE SDK sends the device's advertising identifier (e.g. IFA) in a lower-case format and our system stores it in this format. As such, hashes will be completed on the lower-case format and not the upper-case format which results in a different hashed value. For example, the upper-cased string "TUNE" returns an MD5 hash of "05069c0e15b79590b44ff985487037b7", whereas the lower-cased string "tune" returns an MD5 hash of "7ce1689483acd43d5bc46598b11bd139". Please always use the lower-cased format of the device's advertising identifiers when hashing to ensure a 1:1 match with your TUNE data.

Example TUNE link for Click:

https://11648.api-01.com/serve?action=click&publisher_id=11648&site_id=2962&device_ip=123.123.123.123&ios_ifa=550e8400-e29b-41d4-a716-446655440000&response_format=json

Results:

{
    "success": true,
    "url": "http://itunes.apple.com/us/app/atomic-dodge-ball-lite/id550854415",
    "invoke_url": "myapp://specificpage?mat_click_id=9452cbd386069ba774-20140626-877",
    "tracking_id": "4e0146e109345e5b1955415f0472a743",
    "log_id": "a56f2647ef00c3a-20130203-877"
}

The "url" value can be used to determine where to redirect the user to if they are a new user and need to download the app.

The "invoke_url" value is the deep link URL which is used to redirect users with the app already installed (existing user) to open the app. If the advertiser doesn't have a deep link set up in Attribution Analytics, then the field won't be returned.

For information about what data TUNE collects and how TUNE protects the privacy of its clients' data, please visit our Privacy Policy.

_________________________________________________________________________________________________________________________

*NOTE: With the release of the iOS 10 public beta, Apple has updated iOS to redact Advertising Identifier (IDFA) for users with the 'Limit Ad Tracking' setting enabled on their device. In these cases – as in any case where the device IDFA is not available – TUNE Attribution Analytics still attributes new and re-engaged installs.

In the absence of a valid IDFA, AA automatically falls back to device fingerprinting to perform attribution (see next section), and automatically assigns its own install-level identifier for future tracking of these installs. This is existing behavior, however it does require that partners pass the Device IP and User Agent to be used for Device Fingerprinting.

TUNE is continuing to explore additional options to perform deterministic attribution for these users (who reflect 17% of the total iOS user base), and remains committed to providing the most accurate attribution possible for mobile app installs across every platform and operating system.

_________________________________________________________________________________________________________________________

 

Using Fingerprinting

To use fingerprint matching for attribution, first determine if the traffic to be measured is mobile web traffic (through a mobile browser instead of a mobile app), or mobile app traffic.

IMPORTANT: To support attribution for Apple mobile apps running on iOS 10 (no IDFA available), it is required that you pass the following parameters to ensure we can attribute conversions via Device Fingerprinting. See *NOTE above for more information.

1. If the traffic is mobile web, then include the following parameters in the server-side click notifications:

  • device_ip – IP address of the user device recorded on conversion. You can find the device IP in the header of the request that you receive from the user device.
  • user_agent – The user-agent string (specifying the make and version of the mobile browser, among other browser properties) for the device that started the session.

When the traffic is mobile web and you have the user agent, then TUNE uses ScientiaMobile Wurfl to determine the device brand, device model, and OS version from the user agent.

 

2. If traffic is mobile app traffic (inside an app), then include the following parameters in the server-side click notifications:

  • device_ip – IP address of the user device recorded on conversion. You can find the device IP in the header of the request that you receive from the user device.
  • device_brand – Brand or maker of the user device (such as "Apple" or "Samsung"). Learn how to collect Device Brand in-app.
  • device_model – Model of the user device recorded on conversion (such as "iPhone5,2" or "GT-i9300"). Learn how to collect Device Model in-app.
  • os_version – Version of the operating system (such as iOS or Android) on the user device. Learn how to collect OS Version in-app.

Any clicks for which we do not have a valid device brand, device model, and OS version, we cannot include in attribution via device fingerprint matching. The following URL example shows a tracking link for mobile web traffic. As you can see device_ip and user_agent parameters are set.

https://11648.api-01.com/serve?action=click&publisher_id=11648&site_id=2962&device_ip=123.123.123.123&user_agent=Mozilla%2F5.0%20(iPhone%3B%20U%3B%20CPU%20iPhone%20OS%204_0%20like%20Mac%20OS%20X%3B%20en-us)%20AppleWebKit%2F532.9%20(KHTML%2C%20like%20Gecko)%20Version%2F4.0.5%20Mobile%2F8A293%20Safari%2F6531.22.7&os_version=7.1&response_format=json

The following URL example shows a tracking link for in-app traffic. As you can see device_ip, device_brand, device_model and os_version parameters are set.

https://11648.api-01.com/serve?action=click&publisher_id=11648&site_id=2962&device_ip=123.123.123.123&device_brand=apple&device_model=iphone&os_version=7.1&response_format=json

 

Using a Third Party Tracking ID

Instead of relying on a Tracking ID (or MAT click ID) that our Measurement API generates, you can use a third-party Tracking ID by passing your own value into our tracking_id parameter. If you then pass the same tracking_id value into the Google Play install referrer it can be used for install attribution of apps on Google Play or in the open URL (deep link) for apps on any platform it can be used for event attribution.

Using a third-party Tracking ID for attribution requires two steps:

  1. Notify us of the Click with your Tracking ID
  2. Including Tracking ID in client redirect

Using a third-party Tracking ID (such as your own Click ID value) into our tracking_id parameter for attribution has many advantages if you then include that value appropriately in the Google Play install referrer or the open URL (deep link).

Note: For this method of third-party, server-side attribution, clients need to use the TUNE SDK version 3.0 or higher.

1. Notification of Click with your Tracking ID

The first step is notify TUNE of an ad click with your own Tracking ID.

  • tracking_id – Value specified by you, the Advertising Partner.

Without a unique identifier, you set our Tracking ID parameter to the value that you use for reconciliation (such as Google using their gclid, or Google Click ID).

The following URL example shows the tracking_id parameter set to the Google gclid value.

https://11648.api-01.com/serve?action=click&publisher_id=11648&site_id=2962&device_ip=123.123.123.123&response_format=json&tracking_id=CNDXn5-borwCFYVDMgodHE0AjQ

The following example shows the response that TUNE returns.

"success": true,
"url": "https://itunes.apple.com/app/atomic-dodge-ball-lite/id550854415",
"invoke_url": "atomictilt://hs?mat_tracking_id=cndxn5-borwcfyvdmgodhe0ajq"
"tracking_id": "cndxn5-borwcfyvdmgodhe0ajq",
"log_id": "7f3eec5212b73cd1e5-20140204-877"

Note how the tracking_id value is the value specified in the click notification (and included in the Invoke URL as themat_tracking_id value). TUNE uses lower-case Tracking ID values for consistency.

When you (the Advertising Partner) direct the user to install the app from the appropriate app store, include your third-party Tracking ID value so TUNE can use it for attribution.

2a. Tracking ID in Google Play install referrer

As the advertising partner, you notify TUNE of the click server-side with the tracking_id value set, and then redirect to the Google Play store and set the mat_tracking_id value in the Google Install Referrer. Our tracking links only accept tracking_id while we require mat_tracking_id in the Google Play Install Referrer to ensure parameter name uniqueness.

The following URL example shows a tracking link to the Google Play store that includes the third-party Tracking ID:

https://play.google.com/store/apps/details?id=com.hellochatty&referrer=mat_tracking_id%3DTRACKING-ID-HERE

The following URL example shows another tracking link to the Google Play store, but with the mat_tracking_id value set to their gclid value:

https://play.google.com/store/apps/details?id=com.hellochatty&referrer=mat_tracking_id%3Dcndxn5-borwcfyvdmgodhe0ajq

Then when our Android SDK measures the install, we can collect the value of the Google Play Install Referrer (which has the mat_tracking_id value set).

Because the Google Play Install Referrer includes our mat_tracking_id value, we can use this value to attribute the install to the actual click.

2b. Tracking ID in Deep link

On Android and iOS, we can use the Deep link (open URL) to attribute "app open" events and subsequent events back to an ad click. You cannot use this "Open" Invoke URL for view-through attributions because the user is redirected on ad click and not on view.

As the advertising partner, you notify us of the click server-side with the tracking_id value set and then redirect the user to open the app (with the mat_tracking_id value in the open URL).

The following example shows an "Open" Invoke URL.

app://details?action=newchat?mat_tracking_id=TRACKING-ID-HERE

Using the same Google example above, they set the mat_tracking_id value to their gclid value, as shown in the following example.

app://details?action=newchat?mat_tracking_id=cndxn5-borwcfyvdmgodhe0ajq

Then when our Android SDK measures an "app open" event, TUNE can collect the URL that caused the app to open. The Open Invoke URL has the mat_tracking_id value set. Then TUNE parses out the mat_tracking_id value from the URL and uses it to attribute the open event (and subsequent events) to the actual click.

Have a Question? Please contact support@tune.com for technical support.