Measurement API in Action

See common and detailed ways clients have used the Measurement API to accomplish their goals.

Measuring Ads

By default, Attribution Analytics generates TUNE links for measuring clicks and impressions for basic client-side implementation. When a standard TUNE link for measuring clicks is used, the URL will do a 301 redirect to either the Destination URL for new users (usually the appropriate App Store URL) or a deep link URL for existing users (a specific page within the app).

Dynamic Cost Data with Measuring Ads

The TUNE Measurement API supports two required parameters when measuring ads to collect cost data dynamically. Working with us to collect cost data is a requirement by our clients. Cost data enables us to provide cost reconciliation and return-on-investment (ROI) analysis.

Collecting Cost Data when Measuring Clicks

When measuring clicks, these are the required parameters that need to be included:

1. cost_model – predefined values of one of these supported models 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.

Example Measurement URL for a Click when you charge client on CPC basis at a rate (bid won) of $0.01 per click:

http://publisher_id.api-01.com/serve?action=click&publisher_id=19228&site_id=15284&cost_model=cpc&cost=0.01

Collecting Cost Data when Measuring Impressions

When measuring impressions, these are the required parameters that need to be included:

1. cost_model – predefined values of one these supported models you use to bill clients for their marketing campaigns:
   • cpv – Cost per View (Impression)
   • cpm – Cost per 1000 Impressions
   • 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.

Example Measurement URL for an Impression when you charge client on CPM basis at rate (bid won) of $0.15 per 1000 impressions:

http://publisher_id.api-01.com/serve?action=impression&publisher_id=19228&site_id=15284&cost_model=cpm&cost=0.15

Macros for Dynamic Insertion or Manually Set

The values of the cost_model and cost parameters can both by set dynamically using macros. If you platform doesn't support macros, then you can manually set the parameters.

For example, your platform supports the macro %cost_model% for our cost_model parameter and %cost% for the amount of the cost. Our platform would generate a measurement URL for clicks mapping your macros to our parameters:

http://publisher_id.api-01.com/serve?action=click&publisher_id=19228&site_id=15284&cost_model=%cost_model%&cost=%cost%

If the cost model was CPC and the amount you charged client for click was $0.01 then you'd actually notify the URL with your macros replaced:

http://publisher_id.api-01.com/serve?action=click&publisher_id=19228&site_id=15284&cost_model=cpc&cost=0.01

If you don't have a macro for the cost model and you only have one model for all clients you work with, then you can manually set the value as part of the integration.

For example, if you only work on a CPI basis, then our cost_model parameter could be hardcoded to cost_model=cpi while the cost amount could still be set dynamically with your macro:

http://YOUR_PUBLISHER_ID.api-01.com/serve?action=click&publisher_id=19228&site_id=15284&cost_model=cpi&cost=%cost%

Costing Scenarios

To provide further insight on how we calculate cost based on the values set with cost_model and cost, consider the following scenarios.

Case 1

If the Measurement API responded to the following requests:

The Measurement API calculates cost accordingly:

Case 2

If the Measurement API responded to the following requests:

The Measurement API calculates cost accordingly:

Case 3

Publisher setting of Impression Attribution View Percentage of 50%. If the Measurement API responded to the following requests:

Since the view_percent of 75% is greater than equal to 50%, the Measurement API calculates cost accordingly:

Case 4

Publisher setting of Impression Attribution View Percentage of 50%. If the Measurement API responded to the following requests:

Since the view_percent of 25% is less than equal to 50%, the Measurement API calculates cost accordingly:

No cost since user didn't reach impression attribution view percentage.

Case 5

If the Measurement API responded to the following requests:

The Measurement API calculates cost accordingly:

Case 6

If the Measurement API responded to the following requests:

The Measurement API calculates cost accordingly since cost from click applied to install due to click-through conversion:

Case 7

If the Measurement API responded to the following requests:

Since CPA functions the same as CPI, the Measurement API calculates cost accordingly:

Case 8

If the Measurement API responded to the following requests:

The Measurement API calculates cost accordingly since cost from impression applied to install due to view-through conversion:

Case 9

If the Measurement API responded to the following requests:

The Measurement API calculates cost accordingly since cost from click applied to open due to click-through conversion:

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.

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 World Atlas.

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.

📘

iOS 10 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 iOS 10 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
   • Tracking ID in Google Play install referrer for install attribution (user acquisition campaigns)
   • Tracking ID in Deep link of Android, iOS or Windows app for event attribution (re-engagement campaigns)

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.

Measuring Impressions

The Measurement API can be used to measure views of ads as impressions. If you are measuring impressions with us, the data can be used for view-through attributions by Identifier Matching. We don't support view-through attributions by any other attribution method. If you don't have any device identifiers for attribution by Identifier Matching, you can still measure impressions with us.

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 MAT).

Required Impression Parameters

The basic URL to measure impressions will also include:

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

Advertisers may specify these parameters as well:

1. • campaign_id – ID of the mobile app created by MAT and provided by advertiser

Additional Required parameters

Since you'll be notifying us of clicks to this Measurement API likely server-side or asynchronously click-side, you will need to add these additional parameters to all Measurement URLS 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 the MAT platform 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 World Atlas.

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 these supported models when measuring impressions you use to bill clients for their marketing campaigns:
   • cpv – Cost per View (Impression)
   • cpm – Cost per 1000 Impressions
   • 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 in Measurement URLs.

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 impression ID that you need for us to pass back to you in server postback notifications, please use our ref_id parameter.

• ref_id – Internal reference ID parameter that you can use for your own ID values (such as impression or session 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 for View-through Attribution

Our Measurement API only supports view-through attribution by device identifiers. If you don't have any device identifiers for attribution, we can still measure impressions but won't use those impressions to conduct view-through attribution.

Using Device Identifiers

To use unique identifier matching for attribution, we require you to append the following three parameters to Measurement URLS for impressions:

• google_aid – The Google Advertising Identifier or the Android ID (Android only).
• ios_ifa – The Apple Identifier for Advertisers value (iOS only).
• 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.

Example Measurement URL for Impression:

https://1.api-01.com/serve?action=impression&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": null,
    "tracking_id": "2b3b22ec446a5042d0575551fd2f95e9",
    "log_id": "0a0313df7a5044591d-20140626-877",
}

Retrieve Deferred Deep Links from API

If you append parameters (such as referral codes, campaign IDs, and publisher-specific parameters) to your deferred deep links, then you can make server-to-server API calls to the TUNE API to programmatically retrieve the actual deep link URL that MAT persists in its internal deep link database/registry. This retrieval can be useful for double-checking the parameters appended to the deep link URL, or simply for testing and debugging purposes to see the specific deep link URL that MAT will serve at run-time (ad click).

All requests to the deferred deep link API must be authenticated as described at Authentication Method for SDK-less use of Measurement API. Instead of making API calls from your server, you can also retrieve deferred deep links using the MAT SDK (integrated with your app code), as described in Reading Server Responses.

To retrieve a deferred deep link from API:

Generate an HTTPS request to the following service endpoint:

https://deeplink.mobileapptracking.com/p1/link

Include your authentication signature and other required parameters in the request header:

Append your other query parameters to the request:

Now URL encode all of the query parameters.

The following example shows a URL-encoded API request:

$ curl -X GET -h "Mat-Consumer-Key: aaaabbbbccccddddeeeeffff" -h "Mat-Timestamp: 1430951160" -h "Mat-Signature: xxxxxxxxxxxxxxxxxxxxxxxx" "https://deeplink.mobileapptracking.com/p1/link?advertiser_id=&platform=ios&package_name=my.ios.app&device_ad_id=AAAAAAAAA-BBBB-CCCC-1111-222222220000"

Sending this URL-encoded API request generates the following sample response from the deep linker service:

{
    "link": "myapp://page?mat_click_id=1111222233334444-20150427-877"
}

The possible response values are:

Things to Keep in Mind

• NEVER pass personally identifiable information (PII) through a deferred deep link because it poses a security risk.
• In Web-to-App scenarios, TUNE uses device fingerprint matching to lookup deferred deep links because presumably, the original click did not have a device identifier. TUNE imposes a lookback window of 2 hours (instead of the default 24-hour attribution window for device fingerprint matching) to reduce the likelihood of false matches. Because device fingerprint matching is not always 100% accurate, you should NOT pass PII through a deferred deep link (else it's remotely possible that users may receive targeted information unintended for them).
• If TUNE cannot match the user/device to a deferred deep link through device fingerprint matching, then TUNE does not redirect the user through the deferred deep link. Be aware of the potential for drop-off.

For more information about deep linking, please visit Deep Linking to Your Mobile App from Your Website.

Measuring In-App Events

Beyond measuring the session, the Measurement API empowers you to measure additional events. Measuring events enables you to:

• determine the value of newly acquired users
• measure the success of re-engagement with re-marketing / re-targeting campaigns

While you can immediately measure in-app events by implementing our SDKs, you can also measure these events server-side (directly with our Measurement API).

We have created 17 pre-defined events to help you easily implement measurement of applicable events. Based on the type of your mobile app and your marketing team's advertising goals, it's recommended that you measure as many of our measure events as possible in order to get the most granular insight possible from TUNE reporting.

Measuring Other Custom Events

TUNE has 17 pre-defined app events. These pre-defined events make the process more streamlined to share data with your advertising partners. If you want to measure a custom event that doesn't align with a pre-defined event you can specifically set an event to use either by its ID created by Attribution Analytics (site_event_id) or a reference string provided by you (site_event_name).

For example, to define a custom event (not a standard, predefined event in Attribution Analytics), use the following format:

action=conversion&site_event_name=

or

action=conversion&site_event_id=

To use an Event ID, you need to first create the event in the platform and then use the corresponding ID that MAT creates for the event. The event type for these events will be "event" but can be set in Attribution Analytics by editing the event to a type of one of the pre-defined event types.

As an alternative and more streamlined manner, the Measurement API allows you to specify the event name dynamically. This eliminates the need to create the event in the Attribution Analytics platform first. You can dynamically insert a value for the event name. If the site_event_name does not exist, a new event is automatically created in the platform.

The site_event_name value sent to the Measurement API is lower-cased and non-alphanumeric characters removed. The value is then stored with the event as both the "reference" (ref) value and the "name" value with the URL encoding removed.

The name can then be edited in the Attribution Analytics platform and will display in reports accordingly without causing measurement to break.

Base URL

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

YOUR_ADVERTISER_ID should be replaced with your advertiser ID defined by Attribution Analytics.

Required Parameters

• action=conversion
• advertiser_id – ID of your advertiser defined by Attribution Analytics.
• one of the following application identifiers:
  • site_id – ID of the mobile app defined by Attribution Analytics.
  • package_name – Package name for Android or Bundle ID for iOS.
• sdk=server
• response_format=json – Notifies the Attribution Analytics platform that server-side attribution is being used and returns a server-friendly json response.

You will then need to include the site_event_name or site_event_id value:

• site_event_name – Name or string that you reference the event by.

OR

• site_event_id – ID of the event defined by Attribution Analytics.

Required Identifier(s)

First it's required to include your own user ID value that you use to identify the user in your system. This value should not be a device or advertising identifier, including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication. If the user_id is 1234 and then you set user_id to 5678 for the same user, a new install and user will be created.

• user_id – Unique user ID of user defined by advertiser. Example value: 10000000001

Second, after specifying your user_id, then you'll need to specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

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

• user_id – * already a required identifier parameter
• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.
• attribute_sub1 – String custom event attribute for your optional use.
• attribute_sub2 – String custom event attribute for your optional use.
• attribute_sub3 – String custom event attribute for your optional use.
• attribute_sub4 – String custom event attribute for your optional use.
• attribute_sub5 – String custom event attribute for your optional use.
• currency_code – 3 letter code for revenue using ISO 4217 currency codes.
• content_id – ID (SKU) of the content or product.
• content_type – Category that the content is in.
• site_event_items – Array of items the event. Fields for each item defined below.

The items in the json array for site_event_items field can include the fields below. Only the "name" field is required and all others are optional but recommended when applicable.

• name – Name or ID of the content or product. SKU. Required.
• unit price – Value (revenue) of a single item.
• quantity – Number of the units per item.
• value – Total value of items. Unit price x quantity
• attribute_sub1 – String custom item attribute for your optional use.
• attribute_sub2 – String custom item attribute for your optional use.
• attribute_sub3 – String custom item attribute for your optional use.
• attribute_sub4 – String custom item attribute for your optional use.
• attribute_sub5 – String custom item attribute for your optional use.

To build a payload for the site_event_items parameter, you would need to create a json array with the above format. You can have multiple items by defining a new sub array.

Here's an example where the items of an event include apples and oranges. The apples has name, quantity, unit_price and value defined. The oranges only has name, quantity and revenue.

[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]

If quantity and value are only defined, then unit_price will be determined with value divided by quantity. If unit price and quantity are only defined, then value will be determined by multiple unit price by quantity.

Then you would append the above on to the site_event_items parameter.

&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]

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 is then be generated by hashing the Private Key with URL parameters.

The Consumer Key, Signature and timestamp 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 Custom Event URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=conversion&site_event_name=eventx&advertiser_id=877&sdk=server&site_id=1234&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&currency_code=USD&content_id=abc123&content_type=shoes&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]&response_format=json

Example Measure Custom Event URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=conversion&site_event_name=eventx&advertiser_id=877&sdk=server&site_id=1357&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&currency_code=USD&content_id=abc123&content_type=shoes&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]&response_format=json

Measuring and Merging External (Non-App) Events

Mobile is an exciting time for retailers as mobile devices afford brands additional channels through which they can engage their users. Without a user having to take a single step into a retail store, brands can engage their users not only through tailored mobile apps, but the mobile web experience as well.

With so many diverse avenues for user engagement, the challenge becomes how to gain insights on the complete value of your users as they generate value across all of your channels. You may first acquire a user via your mobile app, but they may continue to engage with your brand via your website as well as visit your actual retail store. The Measuring and Merging External (Non-App) Events API can help you understand the true value of each user although they may be generating value in entirely different spaces.

Based on your goals and resources, you have two options to combine these data sources as a MobileAppTracking client.

1. Send non-mobile app data from external BI system to MAT and MAT will use the data to provide insights on value of mobile app installs.
2. Send mobile app data from MAT to external BI system and external BI system will fuse the data to provide insights on value of mobile app installs.

This document addresses #1. If you'd like to ingest MAT data into your own BI system and fuse it there with #2 then please refer to Exporting Reporting Logs and Fusing Data.

Measuring Internal App Events via the MAT SDK

As a MobileAppTracking client you'll have our SDKs implemented in your mobile apps to measure end-user sessions in your app. We measure the first app-open event as an Install, while subsequent session calls are measured as opens. Opens that include a change in app version are recorded as Updates.

measureSession()

When measure session is called with the SDK, depending on the platform, the following mobile identifiers will be associated with the install and/or open request.

Android apps on Google Play

• Google Ad ID – google_aid

Android Apps on Kindle or other stores

• Android ID – android_id

iOS apps

• Apple Identifier for Advertising – ios_ifa
• Apple Identifier for Vendor – ios_ifv

Windows 8.1 apps

• Windows Ad ID – windows_aid

Windows 8.0 Apps

• Windows Hardware ID

While the mobile device identifiers above are used for attribution, the SDK must also be implemented to collect a User ID value (your internal identifier for the end user) because this is the only value that MAT uses to link data generated by a user in-app with data generated by a user outside of an app. The device identifiers listed above refer to the device, while the User ID refers to the actual user (and a single user may have multiple devices).

It is required for you to implement the SDK to collect:

• User ID – user_id

The following code can be used to set the User ID value when measuring an event with our SDK.

iOS:

MobileAppTracker setUserId:@"custom_user_id"];

Android:

mobileAppTracker.setUserId("custom_user_id");

For many apps, your internal User ID value is not available on first app open. For example, it may be created and available after a user registration or login event. When MAT measures one of these events and it includes a new user identifier, it uses the device identifiers to associate the event to the install, at which point the install can then be referenced by the user identifiers going forward.

The benefit of MAT updating the install record with a user identifier is that this enables events to be measured from outside the app experience only using the user identifier – without any device-specific identifiers – and then matched to app events made by that same user. However we can only do so when we have access to that User ID, so out-of-app events can only be measured after the USER ID has been passed into MAT.

For more information about user ID configuration, please visit SDK Settings for User IDs.

Measuring External Events via the MAT Measurement API

After the SDK has been implemented to measure sessions that collect mobile device identifiers (and possibly other in-app events with user identifiers), you can then implement a process to send events to our Measurement API, which empowers clients to measure additional events that are generated or processed by a third-party system.

Once an in-app event is measured with the User ID, you can measure events directly with the Measurement API (which uses the User ID to search for the install and link the event to the install).The most common events that retailers measure directly with our Measurement API outside the SDK implementation are:

• Add to Cart
• Checkout Initiated
• Purchase

The Measurement API requires that a user_id is always specified to measure events. Thus, the user_id needs to be included in the request so MAT can link the user data generated outside the app with the data inside the mobile app.

Consider the following GET request example to measure a purchase event with the Measurement API:

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=purchase&advertiser_id=877&sdk=server&package_name=app.atomic.dodgeball&user_id=10000000001&currency_code=USD&response_format=json

The Measurement API takes the user_id value, finds the install with the matching user_id, and then links the event to the install. This linking enables MAT to provide you with insights on the value of the user, including lifetime value (LTV) analysis.

Validating Apple iTunes In-App Purchases

The revenue reporting features in Attribution Analytics (AA) contain advanced receipt validation mechanisms that, when implemented, independently validate every in-app purchase. This eliminates revenue from fraudulent purchases and ensures that the revenue number you see in our dashboard is the most accurate.

To implement receipt validation, you must first send AA the iTunes purchase receipt data, which we then check against the iTunes API as well.

📘

Note

If you are using the TUNE SDK and want to learn how the in-app purchase validation process can be implemented using our SDK, please read In-App Purchase Verification in our SDK section.

Validation Process

The validation process is a separate and independent process that happens after the event is measured and attributed. Due to this, the validation process will never lag / delay the measuring and attribution processes.

When the platform measures the event with a receipt ID, the event's purchase validation status is set to "Pending". 60 minutes after the event is measured, it is queued in the validation process. The validation process takes the receipt data and queries the Apple iTunes API to see if the purchase was successful or not.

If the purchase was successful, then the event's purchase validation status is set to "Verified" and aggregated revenue is incremented accordingly. If the purchase was not successful, then the event's purchase validation status is set to "Failed" and no revenue is incremented. This process will also check for and block duplicate purchases being sent based on receipt ID.

Collecting Your App's Receipt Data

Unlike our SDKs that collect the receipt data for you, when using our API you will need to collect the receipt data yourself. Refer to Apple's documentation to learn how to collect the purchase receipt data for your iOS app.

Handling Auto-Renewable Digital Subscriptions

If you offer auto-renewable digital subscriptions in your iOS app, you need to provide your iTunes Connect Shared Secret in the AA platform to enable AA to do validation. Auto-renewable subscriptions allow users to purchase in-app content, and the purchase is automatically renewed at the end of the period unless the user chooses to cancel the subscription.

Notifying AA via API

After you collect the purchase receipt data for your iOS app, you can send it to AA to verify your in-app purchases by posting it to your measurement URL for the purchase event.

Sample Measurement URL:

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=purchase&advertiser_id=877&sdk=server&package_name=app.atomic.dodgeball&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&currency_code=USD

POST (JSON)

• data[]
  • For measuring the item that was purchased. Passed in the same way as a site event item.
• store_receipt
  • Pass the base64 encoded receipt data in this field

Example POST

{
"data": [
{
"attribute_sub4": "attr4",
"attribute_sub2": "attr2",
"item": "Barrel Full o' Shiny",
"attribute_sub5": "attr5",
"quantity": "1",
"attribute_sub3": "attr3",
"revenue": "109.989998",
"attribute_sub1": "attr1",
"unit_price": "109.989998"
}
],
"store_receipt":"ewoJInNpZ25hdHVyZSIgPSAiQXBkeEpkdE53UFUyckE1L2NuM2tJTzFPVGsyN..."
}

When we do validation on the in-app purchase for iOS, verified purchases have a purchase validation code of 0. If the purchase is not validated, however, the validation could will be different depending on a variety of reasons (as seen in the table below).

Measuring Pre-Defined Events

We have created 17 pre-defined events to help you easily implement measurement of applicable events. Based on the type of your mobile app and your marketing team's advertising goals, it's recommended that you measure as many of our measure events as possible in order to get the most granular insight possible from TUNE reporting.

Things to keep in mind:

• Only the "Reservation" and "Purchase" events measure revenue. If you want to measure revenue for other events, you need to enable Revenue Aggregation.
• Because TUNE's pricing plan involves billing charges for each event attributed, please consult with your user acquisition/marketing manager prior to implementing events. It may not be cost effective to measure every event possible, so you should focus on implementing only the events that really matter to you.

Achievement Unlocked

Base URL

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

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

Required Parameters

• action=achievement_unlocked
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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

Important "Achievement Unlocked" Event Parameters

These are additional values that can be included that are specific to this pre-defined event. These additional values can then be passed to our advertising partners via server postbacks so they can use them for optimization and re-marketing / re-targeting.

• content_id – Name or ID of achievement.

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 timestamp 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 Achievement Unlocked URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=achievement_unlocked&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&content_id=Bronze1&response_format=json

Example Measure Achievement Unlocked URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=achievement_unlocked&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=Samsunge&device_model=Galaxy&device_carrier=Verizon&country_code=US&content_id=Bronze1&response_format=json

Add to Cart

When a user adds a product (item) to their cart, measure this event with the specific product added as one event item.

Base URL

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

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

Required Parameters

• action=add_to_cart
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.

Important "Add to Cart" Event Parameters

These are additional values that can be included that are specific to this pre-defined event. These additional values can then be passed to our advertising partners via server postbacks so they can use them for optimization and re-marketing / re-targeting. None of the parameters below are required but recommended.

• revenue – Amount of revenue for the purchase. Value should be be a float value and include the currency_code parameter as outlined below. Example value: 10.10
• currency_code – 3 letter code for revenue using ISO 4217 currency codes.
• site_event_items – Array of one or more items for an event. Fields for each item defined below.

The items in the json array for site_event_items field can include the fields below. Only the "name" field is required and all others are optional but recommended when applicable.

• name – Name or ID of the content or product. Required.
• unit price – Value (revenue) of a single item.
• quantity – Number of the units per item.
• value – Total value of items. Unit price x quantity
• attribute_sub1 – String custom item attribute for your optional use.
• attribute_sub2 – String custom item attribute for your optional use.
• attribute_sub3 – String custom item attribute for your optional use.
• attribute_sub4 – String custom item attribute for your optional use.
• attribute_sub5 – String custom item attribute for your optional use.

To build a payload for the site_event_items parameter, you would need to create a json array with the above format. You can have multiple items by defining a new sub array.

Here's an example where the items of an event include apples and oranges. The apples has name, quantity, unit_price and value defined. The oranges only has name, quantity and revenue.

[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]

If quantity and value are only defined, then unit_price will be determined with value divided by quantity. If unit price and quantity are only defined, then value will be determined by multiple unit price by quantity.

Then put the above array in a JSON object under a key called "data", before sending it as a POST request.

{
  "data": [
    {
      "name": "apples",
      "quantity": "3",
      "unit_price": ".5"
    },
    {
      "name": "oranges",
      "quantity": "4",
      "value": "8"
    }
  ]
}

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 timestamp 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 Add to Cart URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=add_to_cart&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&currency_code=USD&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]response_format=json

Example Measure Add to Cart URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=add_to_cart&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&currency_code=USD&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]&response_format=json

Add to Wishlist

Similar to the Add to Cart event, but instead of the user intending to buy the product now, they are saving the product to a list to buy in the future.

Base URL

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

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

Required Parameters

• action=add_to_wishlist
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

TUNE recommends that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.

Important "Add to Wishlist" Event Parameters

These are additional values that can be included that are specific to this pre-defined event. These additional values can then be passed to our advertising partners via server postbacks so they can use them for optimization and re-marketing / re-targeting. None of the parameters below are required but recommended.

• revenue – Amount of revenue for the purchase. Value should be be a float value and include the currency_code parameter as outlined below. Example value: 10.10
• currency_code – 3 letter code for revenue using ISO 4217 currency codes.
• site_event_items – Array of one or more items for an event. Fields for each item defined below.

The items in the JSON array for site_event_items field can include the fields below. Only the "name" field is required and all others are optional but recommended when applicable.

• name – Name or ID of the content or product. Required.
• unit price – Value (revenue) of a single item.
• quantity – Number of the units per item.
• value – Total value of items. Unit price x quantity
• attribute_sub1 – String custom item attribute for your optional use.
• attribute_sub2 – String custom item attribute for your optional use.
• attribute_sub3 – String custom item attribute for your optional use.
• attribute_sub4 – String custom item attribute for your optional use.
• attribute_sub5 – String custom item attribute for your optional use.

To build a payload for the site_event_items parameter, you would need to create a JSON array with the above format. You can have multiple items by defining a new sub array.

Here's an example where the items of an event include apples and oranges. The apples has name, quantity, unit_price and value defined. The oranges only has name, quantity and revenue.

[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]

If quantity and value are only defined, then unit_price will be determined with value divided by quantity. If unit price and quantity are only defined, then value will be determined by multiple unit price by quantity.

Then put the above array in a JSON object under a key called "data", before sending it as a POST request.

{
  "data": [
    {
      "name": "apples",
      "quantity": "3",
      "unit_price": ".5"
    },
    {
      "name": "oranges",
      "quantity": "4",
      "value": "8"
    }
  ]
}

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 timestamp 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 Add to Wishlist URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=add_to_wishlist&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&currency_code=USD&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]&response_format=json

Example Measure Add to Wishlist URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=add_to_wishlist&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&currency_code=USD&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]&response_format=json

Added Payment Info

After a user successfully added payment info to their account, implement a call to our Measurement API to log this event.

Base URL

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

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

Required Parameters

• action=added_payment_info
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• crated – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.

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 timestamp 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 Added Payment Info URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=added_payment_info&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&age=18&gender=m&response_format=json

Example Measure Added Payment Info URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=added_payment_info&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&age=18&gender=m&response_format=json

Checkout Initiated

Similar to the Purchase event, but measure this event immediately after the desired items (products) are defined and the user initiates the checkout process. You can use this "checkout initiated" event to determine which products a client did not complete purchasing (the items that they abandoned). You can use this abandoned product data to re-market to the user and encourage them to complete their purchase.

Base URL

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

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

Required Parameters

• action=checkout_initiated
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.

Important "Checkout Initiated" Event Parameters

These are additional values that can be included that are specific to this pre-defined event. These additional values can then be passed to our advertising partners via server postbacks so they can use them for optimization and re-marketing / re-targeting. None of the parameters below are required but recommended.

• revenue – Amount of revenue for the purchase. Value should be be a float value and include the currency_code parameter as outlined below. Example value: 10.10
• currency_code – 3 letter code for revenue using ISO 4217 currency codes.
• site_event_items – Array of one or more items that were are in the shopping cart at the time the checkout process is initiated. Fields for each item defined below.

The items in the json array for site_event_items field can include the fields below. Only the "name" field is required and all others are optional but recommended when applicable.

• name – Name or ID of the content or product. Required.
• unit price – Value (revenue) of a single item.
• quantity – Number of the units per item.
• value – Total value of items. Unit price x quantity
• attribute_sub1 – String custom item attribute for your optional use.
• attribute_sub2 – String custom item attribute for your optional use.
• attribute_sub3 – String custom item attribute for your optional use.
• attribute_sub4 – String custom item attribute for your optional use.
• attribute_sub5 – String custom item attribute for your optional use.

To build a payload for the site_event_items parameter, you would need to create a json array with the above format. You can have multiple items by defining a new sub array.

Here's an example where the items of an event include apples and oranges. The apples has name, quantity, unit_price and value defined. The oranges only has name, quantity and revenue.

[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]

If quantity and value are only defined, then unit_price will be determined with value divided by quantity. If unit price and quantity are only defined, then value will be determined by multiple unit price by quantity.

Then put the above array in a JSON object under a key called "data", before sending it as a POST request.

{
  "data": [
    {
      "name": "apples",
      "quantity": "3",
      "unit_price": ".5"
    },
    {
      "name": "oranges",
      "quantity": "4",
      "value": "8"
    }
  ]
}

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 timestamp 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 Checkout Initiated for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=checkout_initiated&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&currency_code=USD&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]&response_format=json

Example Measure Checkout Initiated for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=checkout_initiated&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&currency_code=USD&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]&response_format=json

Content View

The "content view" event occurs when a user views a specific piece of content or product. If it is a product and not just content, then set the event items payload with one item.

Base URL

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

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

Required Parameters

• action=content_view
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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 o in your reporting.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.

Important "Content View" Event Parameters

These are additional values that can be included that are specific to this pre-defined event. These additional values can then be passed to our advertising partners via server postbacks so they can use them for optimization and re-marketing / re-targeting. None of the parameters below are required but recommended.

• currency_code – 3 letter code for revenue using ISO 4217 currency codes.
• content_id – ID (SKU) of the content or product.
• content_type – Category that the content is in.
• site_event_items – Array of one items that was viewed. Fields for each item defined below.

The items in the json array for site_event_items field can include the fields below. Only the "name" field is required and all others are optional but recommended when applicable.

• name – Name or ID of the content or product. Required.
• unit price – Value (revenue) of a single item.
• quantity – Number of the units per item.
• value – Total value of items. Unit price x quantity
• attribute_sub1 – String custom item attribute for your optional use.
• attribute_sub2 – String custom item attribute for your optional use.
• attribute_sub3 – String custom item attribute for your optional use.
• attribute_sub4 – String custom item attribute for your optional use.
• attribute_sub5 – String custom item attribute for your optional use.

To build a payload for the site_event_items parameter, you would need to create a json array with the above format. You can have multiple items by defining a new sub array.

Here's an example where the items of an event include apples and oranges. The apples has name, quantity, unit_price and value defined. The oranges only has name, quantity and revenue.

[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]

If only quantity and value are defined, then unit_price will be determined with value divided by quantity. If only unit price and quantity are defined, then value will be determined by multiple unit price by quantity.

Then put the above array in a JSON object under a key called "data", before sending it as a POST request.

{
  "data": [
    {
      "name": "apples",
      "quantity": "3",
      "unit_price": ".5"
    },
    {
      "name": "oranges",
      "quantity": "4",
      "value": "8"
    }
  ]
}

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 timestamp 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 Content View URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=content_view&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&currency_code=USD&content_id=abc123&content_type=shoes&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"}],[{"name":"oranges","quantity":"4","value":"8"}]&response_format=json

Example Measure Content View URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=content_view&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&currency_code=USD&content_id=abc123&content_type=shoes&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"}],[{"name":"oranges","quantity":"4","value":"8"}]&response_format=json

Invite

The Invite event occurs when a user invites their friends to join your service and/or install your mobile app. Log this invite after the user completes the invite process (which may invite their friends to join via SMS, email, or another form of communication).

Base URL

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

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

Required Parameters

• action=invite
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.

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 timestamp 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 Invite URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=invite&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 Invite URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=invite&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

Level Achieved

The level achieved event occurs when a user completes one level and proceeds to the next (typically, in a gaming mobile app). This event shows the user engagement and can identify the skill level of the user in the game. Use the level parameter with the event to store the value of the achieved level.

After a user successfully completes a level, implement a call to our Measurement API to log this event.

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

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

Required Parameters

• action=level_achieved
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.

Important "Level Achieved" Event Parameters

These are additional values that can be included that are specific to this pre-defined event. These additional values can then be passed to our advertising partners via server postbacks so they can use them for optimization and re-marketing / re-targeting.

• level – Name of ID of level achieved.

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 timestamp 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 Level Achieved URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=level_achieved&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&level=10&response_format=json

Example Measure Level Achieved URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=level_achieved&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&level=10&response_format=json

Login

After a successful login by the user, implement a call to our Measurement API to log this event.

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=login
• 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 – Notifies TUNE that server-side attribution is being used and returns a server-friendly JSON response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.

iOS:

• ios_ifa – Apple's 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS, or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.
• advertiser_sub1 – String custom event attribute for your optional use.
• advertiser_sub2 – String custom event attribute for your optional use.
• advertiser_sub3 – String custom event attribute for your optional use.
• advertiser_sub4 – String custom event attribute for your optional use.
• advertiser_sub5 – String custom event attribute for your optional use.

Important "Login" Event Parameters

These are additional values that can be included that are specific to this pre-defined event. These additional values can then be passed to our advertising partners via server postbacks so they can use them for optimization and re-marketing/re-targeting.

• age – Age of user set as an integer. Example value: 18
• gender – Gender of user. Values for male: male, m or 0. Values for female: female, f or 1.

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 timestamp 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 Login URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=login&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&age=18&gender=m&response_format=json

Example Measure Login URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=login&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&age=18&gender=m&response_format=json

Purchase

The purchase event occurs when a user completes the checkout process. If these purchase events are for in-app purchases, then use our in-app purchase verification with this event as well. Each SKU or line item in the shopping cart should have its own event item.

Base URL

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

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

Required Parameters

• action=purchase
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required User Identifier(s)

Specify as many advertising identifiers as possible for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_id's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.

Important "Purchase" Event Parameters

These are additional values that can be included that are specific to this pre-defined event. These additional values can then be passed to our advertising partners via server postbacks so they can use them for optimization and re-marketing / re-targeting. None of the parameters below are required but recommended.

• revenue – Amount of revenue for the purchase. Value should be a float value and include the currency_code parameter as outlined below. Example value: 10.10

📘

Note

You can also pass a negative purchase value to reflect transactions like refunds. This negative value will also be included in the Sum total in reporting.

• currency_code – 3 letter code for revenue using ISO 4217 currency codes.

• site_event_items – Array of one or more items that were in the shopping cart that the user purchased. Fields for each item defined below.

The items in the json array for site_event_items field can include the fields below. Only the "name" field is required and all others are optional but recommended when applicable.

• • name – Name or ID of the content or product. Required.
  • unit price – Value (revenue) of a single item; may also be a negative revenue value.
  • quantity – Number of the units per item.
  • value – Total value of items. Unit price x quantity
  • attribute_sub1 – String custom item attribute for your optional use.
  • attribute_sub2 – String custom item attribute for your optional use.
  • attribute_sub3 – String custom item attribute for your optional use.
  • attribute_sub4 – String custom item attribute for your optional use.
  • attribute_sub5 – String custom item attribute for your optional use.

To build a payload for the site_event_items parameter, you would need to create a json array with the above format. You can have multiple items by defining a new sub array.

Here's an example where the items of an event include apples and oranges. The apples has name, quantity, unit_price and value defined. The oranges only has name, quantity and revenue.

[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]

If quantity and value are only defined, then unit_price will be determined with value divided by quantity. If unit price and quantity are only defined, then value will be determined by multiple unit price by quantity.

Then put the above array in a JSON object under a key called "data", before sending it as a POST request.

{
  "data": [
    {
      "name": "apples",
      "quantity": "3",
      "unit_price": ".5"
    },
    {
      "name": "oranges",
      "quantity": "4",
      "value": "8"
    }
  ]
}

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 timestamp 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 Purchase URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=purchase&site_event_name=purchase&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&currency_code=USD&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]&response_format=json

Example Measure Purchase URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=purchase&site_event_name=purchase&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&currency_code=USD&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]&response_format=json

Rated

Implement this to measure if a user rated your app with an app store or use this event to measure if a user rates content like a product in your app.

Base URL

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

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

Required Parameters

• action=rated
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly JSON response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.

Important "Rated" Event Parameters

These are additional values that can be included that are specific to this pre-defined event. These additional values can then be passed to our advertising partners via server postbacks so they can use them for optimization and re-marketing / re-targeting.

• rating – Value of rating as an integer. Example value: 3
• content_id – Name or ID of content if content (product) is being rated.

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 timestamp 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 Rated URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=rated&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&rating=3&content_id=abc123&response_format=json

Example Measure Rated URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=rated&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&rating=3&content_id=abc123&response_format=json

Registration

After a successful registration by the user, implement a call to our Measurement API to log this event.

Base URL

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

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

Required Parameters

• action=registration
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.
• attribute_sub1 – String custom event attribute for your optional use.
• attribute_sub2 – String custom event attribute for your optional use.
• attribute_sub3 – String custom event attribute for your optional use.
• attribute_sub4 – String custom event attribute for your optional use.
• attribute_sub5 – String custom event attribute for your optional use.

Important "Registration" Event Parameters

These are additional values that can be included that are specific to this pre-defined event. These additional values can then be passed to our advertising partners via server postbacks so they can use them for optimization and re-marketing / re-targeting.

• age – Age of user set as an integer. Example value: 18
• gender – Gender of user. Values for male: male, m or 0. Values for female: female, f or 1.

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 timestamp 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 Registration URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=registration&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&age=18&gender=m&response_format=json

Example Measure Registration URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=registration&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&age=18&gender=m&response_format=json

Reservation

Use the reservation event for travel and entertainment-related mobile apps.

You can use the data1 parameter for a check in (reservation date), date2 for multi-day reservations, and quantity for the number of guests count.

Use the Advertiser Reference ID parameter for the reservation number or Order ID.

You can also set revenue and currency_code attributes to help determine the value of your advertising partners.

Base URL

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

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

Required Parameters

• action=reservation
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.

Important "Reservation" Event Parameters

These are additional values that can be included that are specific to this pre-defined event. These additional values can then be passed to our advertising partners via server postbacks so they can use them for optimization and re-marketing / re-targeting.

• date1 – Time of Check In. Recommend date time format of yyyy-mm-dd hh:mm:ss.
• date2 – If multi-date event, time of Check Out. Recommend date time format of yyyy-mm-dd hh:mm:ss.
• quantity – Count of Guests as integer.
• revenue – Amount of revenue for the purchase. Value should be be a float value and include the currency_code parameter as outlined below. Example value: 10.10
• currency_code – 3 letter code for revenue using ISO 4217 currency codes.
• advertiser_ref_id – Reservation Number.

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 timestamp 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 Reservation URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=registration&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&date1=2014-06-01 01:01:01&quantity=2&revenue=10.10&currency_code=USD&advertiser_ref_id=xxxxxxxxx1&response_format=json

Example Measure Reservation URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=registration&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&date1=2014-06-01 01:01:01&quantity=2&revenue=10.10&currency_code=USD&advertiser_ref_id=xxxxxxxxx1&response_format=json

Search

The Search event occurs when a user completes a search in your app. Collect the keywords they used and pass in the top search results as event items.

Base URL

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

Required Parameters

• action=search
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.

Important "Search" Event Parameters

These are additional values that can be included that are specific to this pre-defined event. These additional values can then be passed to our advertising partners via server postbacks so they can use them for optimization and re-marketing / re-targeting. None of the parameters below are required but recommended.

• search_string – Search term or search keywords
• date1 – Start date if searching for results for specific date.
• date2 – End date if multi-day search.
• quantity – Count of Guests.
• currency_code – 3 letter code for revenue using ISO 4217 currency codes.
• site_event_items – Array of one or more items that were returned in the search results. Fields for each item defined below.

The items in the json array for site_event_items field can include the fields below. Only the "name" field is required and all others are optional but recommended when applicable.

• name – Name or ID of the content or product. Required.
• unit price – Value (revenue) of a single item.
• quantity – Number of the units per item.
• value – Total value of items. Unit price x quantity
• attribute_sub1 – String custom item attribute for your optional use.
• attribute_sub2 – String custom item attribute for your optional use.
• attribute_sub3 – String custom item attribute for your optional use.
• attribute_sub4 – String custom item attribute for your optional use.
• attribute_sub5 – String custom item attribute for your optional use.

To build a payload for the site_event_items parameter, you would need to create a json array with the above format. You can have multiple items by defining a new sub array.

Here's an example where the items of an event include apples and oranges. The apples has name, quantity, unit_price and value defined. The oranges only has name, quantity and revenue.

[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]

If quantity and value are only defined, then unit_price will be determined with value divided by quantity. If unit price and quantity are only defined, then value will be determined by multiple unit price by quantity.

Then put the above array in a JSON object under a key called "data", before sending it as a POST request.

{
  "data": [
    {
      "name": "apples",
      "quantity": "3",
      "unit_price": ".5"
    },
    {
      "name": "oranges",
      "quantity": "4",
      "value": "8"
    }
  ]
}

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 timestamp 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 Search URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=search&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&currency_code=USD&search_string=Hotel%20Vegas&date1=2014-06-01 01:01:01&quantity=3&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]&response_format=json

Example Measure Search URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=search&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&currency_code=USD&search_string=Hotel%20Vegas&date1=2014-06-01 01:01:01&quantity=3&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]&response_format=json

Share

The Share event occurs when a user shares content (for example, a user shares a product with their friends via email or their social network). Measure this event after the user completes the sharing action. This Share event can help you determine which of your users are loyal and point to the user engagement with your app.

Base URL

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

OUR_ADVERTISER_ID should be replaced with your advertiser ID defined by MAT.

Required Parameters

• action=share
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.

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 timestamp 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 Share URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=share&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 Share URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=registration&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

Spent Credits

After a user successfully spends credits, implement a call to our Measurement API to log this event.

Base URL

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

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

Required Parameters

• action=spent_credits
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.

Important "Spent Credits" Event Parameters

These are additional values that can be included that are specific to this pre-defined event. These additional values can then be passed to our advertising partners via server postbacks so they can use them for optimization and re-marketing / re-targeting.

• quantity – Number of credits spent as an integer. Example value: 100

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 timestamp 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 Spent Credits URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=spent_credits&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&quantity=100&response_format=json

Example Measure Spent Credits URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=spent_credits&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&quantity=100&response_format=json

Tutorial Complete

After a user completes registration, most apps offer a tutorial to show the user how the app works. You can use this event to help assess the quality of users from an advertising partner. An advertising partner who generates installs that result in only a few tutorial completions likely has lower-quality users (because users who do not complete the tutorial have less intent to actually use the app on a repeated basis).

After user successfully completes a tutorial, implement a call to our Measurement API to log this event.

Base URL

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

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

Required Parameters

• action=tutorial_complete
• advertiser_id – ID of your advertiser defined by MAT.
• site_id – ID of your app defined by MAT.
• sdk=server – Notifies MAT that the measurement request is originating from a server (rather than the typical mobile SDK).
• response_format=json – Notifies the MAT platform that server-side attribution is being used and returns a server-friendly json response.

Required User Identifier(s)

Specify as many advertising identifiers for attribution. Based on the identifiers you've implemented for measure sessions, you'll want to include the same identifiers for any event especially if your marketing team is planning on doing 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 google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being 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 ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
• ios_ifv – Apple's new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

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

It's also recommended to set your own user id value that you use to uniquely identify the user in your system. This value should not be a device or advertising identifier including any listed for Android, iOS or Windows. This value needs to be the value you've given the user in your own system and is used for de-duplication and cross-device attribution. If the user_id is 1234 and then you set user_id to 5678 for the same user, then we'll create a new install and user because the user_ID's are different (our system considers it as a new/different user).

• user_id – Unique user ID (defined by advertiser) of user. Example value: 10001

Similarly, we recommend that you set your own user values that can also be used for cross-device attribution:

• user_email – The email of the user defined by the advertiser. Example value: [email protected]
• user_name – The username of the user defined by the advertiser. Example value: tom12345

Recommended Device Parameters

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.

• 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.
• device_carrier – Carrier of the device if supports cellular like 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, please visit World Atlas.

Optional Reconciliation Parameters

• created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day 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.

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 timestamp 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 Tutorial Complete URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=tutorial_complete&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 Tutorial Complete URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=tutorial_complete&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

Measuring Sessions

Measure session is a single endpoint that allows us to measure and attribute installs, opens and updates in a single call. Since data integrity is extremely important to us, using the measure session endpoint as an SDK-less solution requires commitments by you. As noted above, you'll need to contact your account manager for further details. The measure session endpoint should be notified on ALL app opens and app resumes. Each time we are notified of a session we will measure an open. Based on the data we have on the user, an install or update may be created as well.

For all users we measure the install which is the first app open we see for the user. Installs can be flagged as existing users and by default we don't attribute installs by existing users since they installed the app at an earlier point and we are just learning about them. If the user's app or device information changes between one measure session and another, the Measurement API automatically creates an update log.

Apple Search Ads Attribution with Measure Session

Using the TUNE SDK for iOS 3.2+, we attribute installs with Apple Search Ads (previously iAd). In order for our Measurement API to be able to attribute installs to Apple Search Ads with measure session (SDK-less implementation), it requires that:

1. Your apps collect the iAd attribution value along with the iAd impression timestamp and send it to your servers, and
2. Your servers include the iAd attribution value when notifying TUNE to measure the install.

When the request to measure a session for a new user includes the iAd attribution value, our Measurement API will use the value during the attribution process accordingly.

Collecting the Search Ads Attribution Value

To enable your app for Search Ads attribution, follow these three steps:

1. 1. Add the iAd framework to the Xcode project file for your app.
   2. Import the iAd headers in the file containing your attribution code.

#import <iAd/iAd.h>

1. 1. Check for iAd attribution, and use the result in your campaign reporting.

if( [UIApplication sharedApplication] && [ADClient class] ) {
    // for devices >= 7.1
    ADClient *adClient = [ADClient sharedClient];

#ifdef __IPHONE_9_0
    if( [adClient respondsToSelector:@selector(requestAttributionDetailsWithBlock:)] ) {
        [adClient requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {
            NSDictionary *iAdCampaignInfo = attributionDetails[@"Version3.1"];

            if( error.code == ADClientErrorLimitAdTracking ) {
                // iAd attribution info not available
            } else if( error ) {
                // iAd attribution info not available
            } else {
                // iOS 7.1
                BOOL appInstallationWasAttributedToiAd = iAdCampaignInfo[@"iad-attribution"] != nil && [iAdCampaignInfo[@"iad-attribution"] boolValue];
                if(appInstallationWasAttributedToiAd) {
                    NSDateFormatter *formatter = [NSDateFormatter new];
                    formatter.dateFormat = @"yyyy-MM-dd'T'HH:mm:ssZ";

                    // iOS 8
                    NSString *strImpressionDate = nil;
                    if( iAdCampaignInfo[@"iad-impression-date"] ) {
                        NSDate *iAdImpressionDate = [formatter dateFromString: iAdCampaignInfo[@"iad-impression-date"]];
                        // string representation of iAd impression date double value
                        strImpressionDate = [NSString stringWithFormat:@"%ld", (long)round([iAdImpressionDate timeIntervalSince1970])];
                    }

                    // iOS 9
                    if( iAdCampaignInfo[@"iad-campaign-id"] ) {
                        // TODO: include campaign id -- Partner Campaign -- publisher_sub_campaign_ref
                    }
                    if( iAdCampaignInfo[@"iad-campaign-name"] ) {
                        // TODO: include campaign name -- Partner Campaign -- publisher_sub_campaign_name
                    }
                    if( iAdCampaignInfo[@"iad-org-name"] ) {
                        // TODO: include org name -- Partner Publisher -- publisher_sub_publisher_ref
                    }
                    if( iAdCampaignInfo[@"iad-lineitem-id"] ) {
                        // TODO: include line item id -- Partner Ad -- publisher_sub_ad_ref
                    }
                    if( iAdCampaignInfo[@"iad-lineitem-name"] ) {
                        // TODO: include line item name -- Partner Ad -- publisher_sub_ad_name
                    }
                    if( iAdCampaignInfo[@"iad-creativeset-id"] ) {
                        // TODO: include creative id -- Partner Placement -- publisher_sub_placement_ref
                    }
                    if( iAdCampaignInfo[@"iad-creativeset-name"] ) {
                        // TODO: include creative name -- Partner Placement -- publisher_sub_placement_name
                    }
                    NSString *strClickDate = nil;
                    if( iAdCampaignInfo[@"iad-click-date"] ) {
                        NSDate *iAdClickDate = [formatter dateFromString: iAdCampaignInfo[@"iad-click-date"]];
                        // string representation of iAd click date double value
                        strClickDate = [NSString stringWithFormat:@"%ld", (long)round([iAdClickDate timeIntervalSince1970])];

                        // TODO: include click date -- iad_click_date
                    }
                    NSString *strConversionDate = nil;
                    if( iAdCampaignInfo[@"iad-conversion-date"] ) {
                        NSDate *iAdConversionDate = [formatter dateFromString: iAdCampaignInfo[@"iad-conversion-date"]];
                        // string representation of iAd conversion date double value
                        strConversionDate = [NSString stringWithFormat:@"%ld", (long)round([iAdConversionDate timeIntervalSince1970])];

                        // TODO: include conversion date -- iad_conversion_date
                    }

                    // iOS 10
                    if( iAdCampaignInfo[@"iad-keyword"] ) {
                        // TODO: include search keyword -- Partner Keyword -- publisher_sub_keyword_ref
                    }
                    if( iAdCampaignInfo[@"iad-adgroup-id"] ) {
                        // TODO: include adgroup id -- Partner Ad Group -- publisher_sub_adgroup_ref
                    }
                    if( iAdCampaignInfo[@"iad-adgroup-name"] ) {
                        // TODO: include adgroup name -- Partner Ad Group -- publisher_sub_adgroup_name
                    }

                    // iOS 11
                    if( iAdCampaignInfo[@"iad-conversion-type"] ) {
                        // TODO: include conversion type -- Event Type -- event_type_ref
                    }
                    if( iAdCampaignInfo[@"iad-keyword-matchtype"] ) {
                        // TODO: include keyword matchtype -- Partner Matchtype -- publisher_sub_match_type_ref
                    }

                    // inform your server that:
                    // 1) iad_attribution = 1
                    // 2) impression_datetime = strImpressionDate
                    // 3) any additional iAd params as may be available in iAdCampaignInfo dictionary
                }
            }
        }];
    } else
#endif
    if( [adClient respondsToSelector:@selector(lookupAdConversionDetails:)] ) {
        // device is iOS 8.0
        [[ADClient sharedClient] lookupAdConversionDetails:^(NSDate *appPurchaseDate, NSDate *iAdImpressionDate) {
            BOOL appInstallationWasAttributedToiAd = (iAdImpressionDate != nil);
            if(appInstallationWasAttributedToiAd) {
                // string representation of iAd impression date double value
                NSString *strImpressionDate = [NSString stringWithFormat:@"%ld", (long)round( [iAdImpressionDate timeIntervalSince1970])];

                // inform your server that:
                // 1) iad_attribution = 1
                // 2) impression_datetime = strImpressionDate
            }
        }];
    } else {
        // device is iOS 7.1
        [adClient determineAppInstallationAttributionWithCompletionHandler:^(BOOL appInstallationWasAttributedToiAd) {
            if(appInstallationWasAttributedToiAd) {
                // inform your server that: iad_attribution = 1
            }
        }];
    }
}

Including Search Ads Attribution with Measure Session

Include the Search Ads attribution data dictionary as part of the post data json using the key "iad" sent with:

• the very first session request, if available before the request has been fired.

📘

Note

The old way for firing a "GET" request does not support newer params available in the Search Ads info, so we recommend that "POST" requests should be used.

Request URL with SearchAds Info Example

Very First Session Request:

https://001.engine.mobileapptracking.com/serve?&action=session&advertiser_id=011&package_name=edu.self.AtomicDodgeBallLite&response_format=json&sdk=ios&...

Request POST data JSON with SearchAds Attribution Info Example

{
  "iad": {
    "Version3.1": {
      "iad-lineitem-id": "32132132",
      "iad-keyword": "atomic dodge",
      "iad-keyword-matchtype": "broad",
      "iad-org-name": "TUNE, Inc.",
      "iad-conversion-date": "2012-11-09T23:21:27Z",
      "iad-attribution": "true",
      "iad-conversion-type": "download",
      "iad-adgroup-name": "my_adgroup_1",
      "iad-creativeset-name": "my_creativeset_1",
      "iad-campaign-id": "22334455",
      "iad-adgroup-id": "12345678",
      "iad-lineitem-name": "my_lineitem_1",
      "iad-campaign-name": "my_ad_campaign_1",
      "iad-click-date": "2016-10-31T19:42:04Z"
    }
  }
}

Search Ads attribution data dictionary

Combining Installs, Updates and Opens

Previously, our Measurement API supported two actions: install and update, which in turn created separate install and update logs.

With the release of the TUNE SDK v3.0, we updated the Measurement API to support measure session to automatically handle the logic for app installs, updates, and opens. With measure session, we create the following logs:

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

When an install or update occurs, we persist two logs: the open log and the install or update log. This persistence allows us to make the (correct) assumption that every "app open" event has an open log, and gives us the ability to then determine if the action was an install or an update when processing the request.
Combining the multiple actions (install, update, open) into a single "session" action:

• Simplifies implementing the logging of installs and opens
• Enables 1:1 reconciling of installs and first app opens
• Allows for simpler debugging and reconciliation with third parties/app stores
• Measures opens used for retention analysis

Handle Existing Users

With the implementation of the measure session, you no longer need to make a different request to measure the update. But if your app already has existing users prior to implementing our SDK, what happens when you start notifying measure session for these existing users? (will existing users be counted as new installs?)

To handle existing users prior to implementing our SDK, you'll need to use this parameter:

• existing_user – Set to 1 (true) for users that are existing users; else set to 0. The default is 0 (false).

Setting existing_user=1 for existing users of your app prevents us from attributing those existing users to publishers and including them as newly acquired users in your reports.
Example measure session with existing user flag set:

//YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=session&advertiser_id=877&sdk=server&package_name=app.atomic.dodgeball&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&existing_user=1&response_format=json

To lean more, refer to how to handle existing users prior to SDK implementation.

Measure Session Use Cases

To learn how the measure session handles installs, updates, and opens, review the following use cases.

Case 1

If this event is the first "app open" event that the Measurement API has seen for the user, then the Measurement API creates an open and install log.

1. User clicks on ad and installs mobile app.
2. User opens app for the first time.
3. Client's SDK / third-party code measures the open.
4. Client notifies us of open via Measure Session endpoint.
   1. We create an install log because we don't have a previous record of the user.
   2. We creates an open log.
   3. We attribute the install and open to the publisher of the click in Step 1.

Case 2

If this event is the first "app open" event that the Measurement API has seen for the user and existing_user is true, then the Measurement API creates an open and install log. Because we don't have a previous install or update log, it cannot determine if the sdk_version or other parameters have changed required to create an update. The install is not attributed since by default existing users are not attributed.

1. User clicks on ad and installs mobile app.
2. User opens app for the first time.
3. Client's SDK / third-party code measures the open.
4. Client notifies us of open via Measure Session endpoint with existing_user=1.
   1. We create an install log with existing_user=1 since it does not have a previous record of the user.
   2. We creates an open log.

Case 3

If the App Version, SDK Version, OS Version or Package Name changes from one "app open" to the next, then the Measurement API creates an update log.

1. User clicks on an ad and installs mobile app.
2. User opens app for the first time.
3. Client's SDK / third-party code measures the open.
4. Client notifies us of open via Measure Session endpoint with app_version=1.1.
   1. We create an install log because we don't not have a previous record of the user.
   2. We create an open log.
   3. We attribute the install and open to the publisher of the click in Step 1.
5. User opens app several days later.
6. Client's SDK / third-party code measures the open.
7. Client notifies us of open via Measure Session endpoint with app_version=1.2.
   1. Since the app version is different, we create an update log.
   2. We create an open log.

If we have a previous update log, then the Measurement API uses that log to compare the previous app_version and sdk_version to the current request, otherwise it uses the previous open log. If the app_version or sdk_version changes from the last update or open, then the Measurement API creates an update log.

Google Play Referrer Attribution with Measure Session

Using the TUNE SDK for Android 4.15.1, we attribute installs via the Google Play App Install Referrer API.

In order for our Measurement API to be able to attribute installs to Google Play with measure session (SDK-less implementation), it requires that:

1. Your apps collect the Google Play App Install Referrer attribution information and send it to your servers.
2. Your servers include the Google Play App Install Referrer attribution information when notifying TUNE to measure the install.

When the request to measure a session for a new user includes the Google Play App Install Referrer attribution information, our Measurement API will use the value during the attribution process accordingly.

Collecting Google Play App Install Referrer Attribution

Please follow Google's Google Play Install Referrer Guide to ensure you are securely retrieving referral content from Google Play.

Google Play App Install Referrer Response Data

Including Google Play App Install Referrer Attribution with Measure Session

Include the Google Play App Install Referrer attribution data with the very first session request.

Request URL with Google Play App Install Referrer Info Example

Very First Session Request:

 https://0000.measure.mobileapptracking.com/serve?&action=session&site_id=0000&sdk=server&response_format=json&referral_url=ABC&click_timestamp=123&download_date=123

Mapping Response Data to TUNE Fields

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.

Recommended Parameters

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 World Atlas.
• 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: [email protected]
• 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

iOS 7 Install Validation SDK-less

Using our iOS SDK 3.1.3 or greater, installs from the iTunes app store on iOS 7 are now verified with Apple.

In order for you to take advantage of the Apple install validation information with the measure session endpoint, it requires that:

• Your app collects the receipt data and sends it to your servers.
• Your servers include the receipt data with measure session.

Collecting the Receipt Data

Please use the following method to detect whether the appStoreReceiptURL selector as is available per Apple's docs.

if (floor(NSFoundationVersionNumber) <= NSFoundationVersionNumber_iOS_6_1) {
    // Load resources for iOS 6.1 or earlier
    return nil;
} else {
    // Load resources for iOS 7 or later
    NSURL *appStoreReceiptURL = [[NSBundle mainBundle] appStoreReceiptURL];
    NSData *receiptData = [NSData dataWithContentsOfURL:appStoreReceiptURL];
    return receiptData;
}

Receipt in the below context is the returned receiptData from above:

// Base64 encode the IAP receipt data
NSString *strReceipt =nil;
if (receipt.length > 0)
   strReceipt = [MATUtils MATbase64EncodedStringFromData:receipt];

Apple Install Receipt with Measure Session

Once you've collected the receipt data and base64-encoded it as a string, you can send include it with the call measure session. You can form the necessary POST body by placing the receipt you collect in a JSON object named "apple_receipt". This is taken and POSTed to the measurement URL.

POST Body format:

{ "apple_receipt":"INSERT_YOUR_STRING_RECEIPT_HERE"}

Example Measure Session URL:

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=session&advertiser_id=877&sdk=ios&package_name=app.atomic.dodgeball&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&os_version=11.2.2&device_brand=Apple&device_model=iPhone5,2&device_carrier=Verizon&country_code=US&response_format=json

📘

Note

Please ensure you have included the following parameters:

• os_version="YOUR_CURRENT_OS_VSERION"
• sdk=ios (Replace sdk=server with sdk=ios)

If these parameters are not included, our system does not read the app as an iOS app and will throw out the Apple Receipt.

POST body for example above:

{ "apple_receipt":"MIISfAYJKoZIhvcNAQcCoIISbTCCEmkCAQExCz...=" }

Upon the Measurement API responding to the request, we will take the receipt and verify with Apple that the install was valid. Keep in mind it's important to pass the package name of your app in the request URL to ensure validation is successful.

iOS Install Validation Results

When we do the validation on in-app purchases for iOS, successfully verified purchases have a purchase validation code of 0. If the purchase is not validated, however, there can be many reasons as to why as shown in the table below. Install validation uses the same as in-app purchase validation.

You can view the results of the iOS install validation in the log reports.