Resource Authentication

Using this Measurement API requires authorization from TUNE for measuring installs and/or events. Once authorized, TUNE will enable you to measure sessions and events with the Measurement API. All requests to measure sessions and events need to be authenticated. Authentication with the Measurement API is documented below.
While partners and advertisers can both use the Measurement API for Ads, measuring the Sessions and Events by advertisers directly with the Measurement API requires a commitment in order to ensure data integrity. If you are an advertiser and would like to use the Measurement API as SDK-less solution, please contact your client success manager for details.
Below outlines how authentication is required by the Measurement API to measure sessions and events in order to verify the requests.

measurement-API-security-New-Page1

Keys and Parameters

Each request to measure installs and/or events must be authenticated. The authentication method requires a public key (Consumer Key) and signature seeded with a Private Key. These two keys are associated with a user’s single API Key.

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

To obtain a Private Key, please read Obtaining Your Private API Key.
To obtain a Consumer Key, please contact your TUNE Client Success Manager and they will provide these values.
Accordingly, the requests to measure installs and/or events will need to include these two parameters as headers based on the above keys:

  • consumer_key – Consumer Key
  • signature – Signature generated by hashing the Private Key with the URL encoded parameters.

When the Measurement API receives requests, it will use the Consumer Key and Private Key to re-generate the hash and determine if the signature provided with the request matches the re-generated signature. Invalid requests will be rejected.

 

Make a Request with Authentication

Required Values

A request to measure a session or event must include these values:

  • Advertiser ID – The ID of your advertiser account we’ve defined for you.
  • Private Key
  • Consumer Key
  • Method – GET or POST depending on HTTP method used.
  • Host – Your Advertiser ID as the sub sub domain at measure.mobileapptracking.com
  • Timestamp – Unix GMT timestamp (in seconds)
  • Additional Parameters – * discussed below

All requests must be sent via SSL, so use HTTPS.

Measurement Parameters

First you will need to generate a list of parameters for the request. If this were a standard GET request, it would be the query string of the URL.

If your parameters are formatted as a query string, then simply convert them to an array.

action=session&advertiser=877
&site_id=2960
&ios_ifa=aaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Example array of parameters using query string above:

$params = array(
    action => 'session',
    advertiser_id => 877,
    site_id => '2960',
    ios_ifa => 'aaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
);

The param array then needs to be converted to a URL-encoded string. Each key-value pair should start with a “&” including the first one.

%26action%3Dsession%26advertiser%3D877%26site_id%3D2960%26ios_ifa%3Daaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee%0A

Required HTTP Headers

The consumer_key, signature, and timestamp values need to be included as HTTP headers in the request rather than being included in the parameters (query string of URL). 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’

Generate Signature

The signature is generated with hmac using encryption algorithm SHA256. It is generated with five strings:

  • Private Key
  • Method – GET or POST depending on HTTP method used.
  • Host – Domain name
  • URL – The path of the page including query string.
  • Timestamp – Unix GMT timestamp (in seconds)
  • * URL encoded Params – If doing POST instead of GET need to include URL encoded params. Not set in signatures for GET requests.

Python, PHP, Go & Java Examples

 

Request Responses

The Measurement API returns response in JSON format. Important parameters in the response are:

  • success - Indicates if request was successful or not.
  • log_id - The ID of the log. If event type was install then it would be the Log Install ID
  • message - Array of errors if request was unsucessful.

 

Success Response

A successful request will return response like:

{
    "success": true,
    "site_event_type": "install",
    "tracking_id": "3c225547069f297b3a0ed4264aac36b3",
    "advertiser_ref_id": null,
    "log_id": "b2f3ce90d42e12e895-20140709-877",
    "message": [ ],
    "log_action": true
}

 

Unsuccessful Response

A bad / invalid request will return the success parameter as false and there will be an array string in the errors parameter. One of these unsuccessful response will be like:

{
    "success": false,
    "site_event_type": "install",
    "tracking_id": "b34ce0f6d1578958972c30b6a35882fc",
    "advertiser_ref_id": null,
    "log_id": "7d6d2f08db789514af-20140709-877",
    "message": [
        "Duplicate request detected."
    ]
}
Have a Question? Please contact support@tune.com for technical support.