Measuring Installs, Opens and Updates

Note: If you are an advertiser and would like to use the Measurement API as an SDK-less solution, please contact your account manager for details.

A session happens each time the app is opened and we automatically handle the logic for measuring app installs, opens, and updates within the session. Depending on the data, when measuring the session, the Measurement API creates the following logs:

  • Install – The first "app open" event that the Measurement API records for the user, regardless if the user is new or existing.
  • Open – The opening of the app and app resume (when the app becomes active again).
  • Update – The "app open" event when the app version or SDK version for the user changes from one open to the next.

Learn how Installs, Updates, and Opens are combined with the measure session endpoint.

Base URL

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve

YOUR_ADVERTISER_ID should be replaced with your advertiser ID defined by TUNE.

Required Parameters

  • action=session
  • advertiser_id – ID of your advertiser defined by TUNE.
  • site_id – ID of your app defined by TUNE.
  • sdk=server – Notifies TUNE that the measurement request is originating from a server (rather than the typical mobile SDK).
  • response_format=json – Returns a server-friendly json response.

Required Identifier(s)

Specify as many advertising identifiers for attribution as you have available. Based on the identifiers you've implemented for measuring sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning to run re-marketing/re-targeting campaigns.

Android:

  • google_aid – The Google AID formatted as uppercase with hyphens. AAAAAA-BBBB-CCCC-11111-2222222222222
  • google_ad_tracking_disabled – If the google_aid parameter is going to be used, then the google_ad_tracking_disabled parameter must be specified to indicate whether the end user has enabled limited ad tracking (with 1 being enabled/limited).

iOS:

  • ios_ifa – Apple’s new Advertiser Identifier with iOS 6.0+. Also, referred to as IFA or IDFA.
  • ios_ad_tracking_disabled – If the ios_ifa parameter is going to be used, then the ios_ad_tracking_disabled parameter must be specified to indicate whether the end user has enabled limited ad tracking (with 1 being enabled/limited).
  • ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

  • device_id – The Windows Hardware ID.
  • windows_aid – The Windows advertising identifier (AID) is a unique, user and device-specific, and resettable ID for advertising represented as an alphanumeric string formatted as upper case without colons (for example, "AAAAAABBBBCCCC111122222222222"). When the advertising ID feature is disabled, this value is an empty string.

Additional Required Strings for Attribution

When measuring sessions its important to also include values to enable attribution of installs of Android apps on Google Play via the Google Play install referrer and attribution of opens for re-engagement via a click ID in the open URL.

  • referral_url
    • For Android and its first app open, include the Google Play install referrer.
    • For all other opens on Android and iOS, include the URL that caused the open (deep link).

If you set a deep link URL as the referral_url, then you must keep setting the deep link URL as the referral_url until the app is closed. Otherwise, attribution of subsequent re-engagement in-app events will fail because the unique identifier (the deep link URL in this case) cannot be matched.

In addition to supporting the two attribution methods above, in order for attributing by fingerprint matching the following parameters will need to be included with each request as well.

  • 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.

These recommended parameters allow us to provide more granular insight on the user’s and their devices. This data can then be used to segment and filter on in your reporting.

  • os_version – Version of the operating system (such as iOS or Android) on the user device. Learn how to collect OS Version in-app.
  • device_carrier – Carrier of the device if supports cellular (such as AT&T).
  • language – Language of the device from local settings.
  • country_code – The ISO ALPHA-2 or ISO ALPHA-3 value of the country. For a complete list of ISO-compliant country codes, visit Country Codes.
  • app_version – Version of the app on the user device (this parameter helps TUNE distinguish between new app installs and existing app updates). For more information about this parameter, visit Installs, Updates, Opens combined.

It’s also recommended to set your own user id value or user value for reconciliation. These values can also be used for cross-device attribution:

  • user_id – The ID of the user defined by the advertiser. Example value: 12345
  • user_email – The email of the user defined by the advertiser. Example value: tom@hotmail.com
  • user_name – The username of the user defined by the advertiser. Example value: tom12345

Optional Reconciliation Parameters

  • created – Value as UNIX timestamp. If created timestamp is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 10 seconds in the future else we will use current timestamp.
  • advertiser_ref_id – Reference ID specified by advertiser to reconcile with their own or third-party system.

You can also implement iOS install validation with this measure session endpoint. Learn how to include the iOS receipt data with API call to measure session with this SDK-less solution.

Required HTTP Headers for Authentication

All requests for measure session must include Authentication Method for SDK-less use of Measurement API in order to validate the authenticity of the request as your own.

The authentication method requires a public key (Consumer Key) and signature seeded with a private key. These two keys are associated to a single user.

  • Private Key – This is the Private key that will be used to generate the signature on both the client and server but will not be included in the request.
  • Consumer Key – This is the public key that will be included with each request so the Private Key used to create the signature can be identified.

A Signature will then be generated by hashing the Private Key with URL parameters.

The Consumer Key, Signature and created values need to included need to be included as HTTP headers in the request. With Curl in PHP they would be set with curl_setopt.

Accordingly, these three values need to be set in the HTTP header of each request.

  • mat-consumer-key: 'consumer key'
  • mat-signature: 'signature'
  • mat-timestamp: 'timestamp'

Example Measure Session URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=session&advertiser_id=877&sdk=server&site_id=2960&ios_ifa=AAAAAA-BBBB-CCCC-11111-2222222222222&ios_ad_tracking_disabled=0&ios_ifv=ZZZZZZ-BBBB-CCCC-11111-2222222222222&user_id=10000000001&device_ip=123.123.123.123&device_brand=Apple&device_model=iPhone5,2&device_carrier=Verizon&country_code=US&response_format=json

Example Measure Session URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=session&advertiser_id=877&sdk=server&site_id=2385&google_aid=AAAAAA-BBBB-CCCC-11111-2222222222222&google_ad_tracking=1&user_id=10000000001&device_ip=123.123.123.123&device_brand=Samsung&device_model=Galaxy&device_carrier=Verizon&country_code=US&response_format=json
Have a Question? Please contact support@tune.com for technical support.