Measurement API

The TUNE Management API allows you - the Advertiser - to retrieve account, advertiser, agency, mobile app(s), and other information not related to reporting and measurement.

Advertisers can make API calls to the Management API to set and retrieve account-specific information for both advertiser and partner data.

Setup & Essentials

Review and learn about the TUNE Server APIs. Establish core tasks, authenticate resources, create user permissions, and connect to various TUNE endpoints.

TUNE Service APIs Overview

The TUNE API is a web service that defines a set of data interactions to its reports and other scripts. This web service is a collection of network Endpoints, each represented by a simple HTTP URL string. Most endpoints access reports via the web service's content, which typically comprises reports generated by data pulled from Records.

Endpoints

An Endpoint is based on an abstract definition, and can be either a "generic" or "data consumer" endpoint:

• Data consumer endpoint represents a connection point for querying a specific record for generating reports. Most of these endpoints have read/write functionality to create/update/delete datasets from their associated records, but some only have read-only functionality.
• Generic endpoint represents a connection point to a read-only service of a non-specific type, not bound to a record, and receives data that is of primitive types (such as string or integer).

Records

A Record represents a table in a database with fields defined by:

• 字段名称
• Property type - 'string', 'integer', 'choice', 'reference', etc...
• Default value [optional]
• Required [default not required] - Upon saving a new dataset, if this field is required, then a value must be provided.
• Choices - If property type is 'choice', then a list of allowed values is assigned.
• Nicename [optional] - Humanized wording for this field.

It is important to note the Property type 'reference', which is an identifier to a related Record of another type. There can be multiple 'reference' fields, each uniquely associated with different Record types, including itself.

Endpoints accessing Records

A data consuming Endpoint is associated with only one Record. It defines what and how information from its record is consumable by users. When an Endpoint is requested to generate a report by pulling datasets from its record, the Endpoint defines record fields that are:

• Provided by default.
• Extra and must be specifically requested.
• Aggregated results across multiple datasets.

When requesting an Endpoint to generate a report, the fields to define the report uses the same name as its associated Record's fields.

Related Endpoints and Record's Referenced Records

If a data consuming Endpoint is associated with a Record that has one or more fields referencing other Records, then in turn it has Related Endpoints that are associated with those referenced Records. As with a Record with 'reference' fields as identifiers to a unique set of related Record types, then so are the set of Related Endpoints of that Endpoint (associated with said Record).

For identification of Related Endpoints, an Endpoint assigns each Related Endpoint with a unique property name, which is used when a report request is to include content from its Related Endpoints' fields. If an Endpoint associated with a Record does not have 'reference' fields, then that Endpoint does not have any Related Endpoints.

Related Endpoints of an Endpoint define access to their Related Records.

Endpoint Actions

An action is an abstract description of an operation supported by an Endpoint, which can have one or more actions.

• Actions of a Data consumer endpoint request reports/results by preparing a query to its bound Records, and possibly including its Related Endpoints.
• Actions of a Generic endpoint request information from a service that is not data bound to any Record.

Most Data consumer endpoints have in common a set of base actions for querying and updating their bound Records (for example, 'count', 'find', 'save', 'delete', 'validate', and 'get'). An action receives requests via the query string portion of an endpoint URL. The contents of the query string must abide by the parameter signature of an action (or it will be rejected), which includes matching parameter naming, matching parameter type, and provide all required parameters. If the contents of the query string are valid, then the action makes a request to its sources. Upon completion, a response is provided based on the requested result format (JSON by default).

Importance of Providing Valid Fields

It is important to understand that every endpoint has its own unique set of fields based upon the model that its data is associated with, and the model's related entities.

Making a request with a field name that does not exist with the endpoint's set of available fields can cause an internal service error (ISE) within the TUNE Management API service. It is important to make sure that the field names used within method parameter type fields， filter， sort, and group are appropriate to the endpoint it is calling.

Every data-consuming endpoint is associated with a single data model (hosted upon either row-oriented or column-oriented DBMS) and with zero or more related data models.

When requesting a report for export from these endpoints, it is important to refer to only fields that are available to the endpoints' associated data models. Providing field names that are not associated with an endpoint's data models and included within actions' parameters will lead to:

1. 参数 fields: Report exported will be missing column.
2. 参数 sort， group， filter: TUNE Management API's service creates an invalid query and thus will fail returning an "Internal Service Error" (ISE).

Understanding Action's Parameters

Action parameters allow you to customize the query to the Management API. Developers familiar with SQL should find this very familiar and easy to understand.

The power of these features is harnessed through the following API call parameters:

• Common Parameters:
  • Parameter 'fields'
  • Parameter 'filter'
  • Parameter 'sort'
  • Parameters 'limit' and 'page'
  • Parameters 'id' and 'ids'
  • Parameters 'key' and 'display'
  • Parameter 'model_data'
  • Parameter 'related_entities'
  • Parameter 'term'

Parameter 'fields'

For those familiar with SQL, a field parameter is analogous to a SELECT statement, which is how you define the data you want returned for the entity. This parameter is also the mechanism by which you can get related data about an entity without having to do a secondary API call.

The fields parameter accepts a comma-separated value (CSV) list or array of field names to include, which can be the fields of the entity or related entity and/or their fields. The following examples demonstrate how to use the fields parameter in your API calls.

Parameter &fields is available for actions:

• find.json
• find_by_ids.json
• get.json

Assume you're working with the /advertiser/campaigns entity:

Example 1 – Getting a subset of entity fields parameters

To limit the result to only return specific fields then set the fields parameter to a comma separated array of the specific fields you'd like returned.

fields=id,name,site_id

When the API includes the above, it would return results below:

{
  id:1,
  name:"campaign1",
  advertiser_id: 3
}

Example 2 – Include subset of related entity fields

To include only a subset of related entity fields, simply include the specific fields after the related entity name separated by a period.

fields=id,name,advertiser.id,advertiser.name

In addition to the entities fields specified, this parameter also returns the two fields of the related advertiser entity.

{
  id:1,
  name:"campaign1",
  advertiser: {
    id:3,
    name:"advertiser3"
  }
}

Parameter 'filter'

For those familiar with SQL, a filter parameter is analagous to a WHERE clause.

Parameter &filter is available for actions:

• choices.json
• count.json
• find.json

Filter Fields

You can include fields to filter for both the entity that you're working on, as well as its related entities (similar to the fields parameter).

Comparison Operators

Support comparison operators:

• =
• >
• >=
• <
• <=
• IN
• BETWEEN
• LIKE

Multiple Filters

You can combine filters using the AND and OR operators.

Assume you're working with the /advertiser/campaigns entity:

Example 1 – Field equals value

To filter where a field equals a value set the filter parameter accordingly. Note that the operator = needs to be URL encoded.

filter=(status = 'active')

This parameter returns only the campaigns where the status field is active.

Example 2 – Related entity field equals value

You can use related entities as the filter field by referencing them appropriately.

filter=(publisher.name = 'Ad Network 123′)

This parameter returns the campaigns where the related publisher has a name of Ad Network 123.

Example 3 – Using IN and AND

You can use the in operate like a select statement and include a comma separated array in ( ).

filter=(publisher_id in (1,2,3,4)) AND (status = 'active')

This parameter returns the campaigns where both the publisher_id = 1,2,3, or 4 AND status of the publishers is active.

Parameter 'sort'

The sort parameter determines the order in which results are returned.

Parameter sort is available for actions:

• choices.json
• find.json

The examples below assume you're working with the advertiser/campaigns entity.

Example 1 – single field sort

To sort by a single field simply include the field for the sort parameter. This sorts ascending.

sort=name

This parameter returns the campaigns by campaign name in alphabetical order (from A to Z).

Example 2 – Single field descending (aka reverse) sort

To sort descending include a colon followed by "desc" after the sort field.

sort=name:desc

This parameter returns the campaigns by campaign name in reverse alphabetical order (from Z to A).

Example 3 – Multi field sort

You can sort by multiple fields by including them in a comma separated array.

sort=advertiser_id,name:desc

This parameter returns the campaigns by advertiser id (name) in reverse alphabetical order (from Z to A).

Parameters 'limit' and 'page' for Pagination

This parameter restricts the number of results to send back. Default value is 10.

Parameters 'id' and 'ids' for Record Identification

Parameter &id is used by these actions and must reference an identifier of an existing record:

• delete.json
• get.json

Parameter &ids is used by this action and must reference an identifier of an existing record:

• find_by_ids.json

Parameter 'model_data' for Actions 'save' and 'validate'

Parameter 'data' is associated with type 'model_data'.

Parameter 'term' for Autocomplete

Parameter 'term' used with Action 'autocomplete' searches for a match within values of its Endpoint's auto-completion column that starts with provided string of characters, case insensitive. Typical fields assigned to auto-completion column are:

• 'name'
• 'email'
• 'value'

Understanding Action's Reponse Format Choices

There are three choices result transformation of data from action results:

• JSON success result
• JSONP success result
• CSV success result (limited to Action 'find')
• JSON error

JSON Transformation

Transform output to JSON format.

示例： /controller_path/action_name.json?param_name=value&param_name=value

{
    "status_pre":200
    "response_size":"119858"
    "data":
        {
        "fields":{}
        "related_entities":
            {}
            "mod_name":"Records\\Model\\Advertisers"
            "mod_namespace":"Records\\Model"
            "mod_shortname":"Advertisers"
        }
}

JSONP Transformation

Transform output to JSON with padding format. JSONP format requires the name of the callback function as a named query parameter value.

示例： /controller_path/action_name.jsonp?callback=jQuery0123456789&param_name=value&param_name=value

jQuery0123456789(
    {
        "status_pre":200
        "response_size":"12345"
        "data":
        {…}
    }
)

CSV Transformation

The result of this transformation is a downloadable CSV file, and it is available only to a limit set of actions. It also requires providing an array of fields, and will not default all available fields for that action's endpoint.

示例： /controller_path/action_name.csv?fields=id%2Cname%2Cemail&param_name=value&param_name=value

JSON Transformation for Error Result

If upon calling a controller it is provided with any of the following conditions, then the output will be also in JSON as shown below:

• Invalid action name
• Valid action provided with invalid parameters
• Valid action provided with parameters containing invalid data

示例： /v2/controller_path/action_name.json?invalid_parameters

{
        "status_pre":401
        "response_size":"266"
        "data":
            "errors":[
            {
                "message":"API key is missing or invalid."
            ]
        }
    }

Understanding Endpoint Actions

What are Endpoint Actions?

An action is an abstract description of an operation supported by the endpoint.

If an action's endpoint is bound to a model, then it may request data underlying that model.

If an action's endpoint is not bound to a model or not, then it may perform an another service instead that excludes data access.

Calling an Endpoint Action

Defining an action is by adding a functional request + query string parameters following the endpoint's path:

• Action name must be in lowercase, for example /find
• Action result is transposed to JSON by adding .json
• Required parameter for any action is either:
  • Account provided API Key (32 characters long string) and assigning it to Parameter api_key.
    For example: &api_key=aaaabbbbccccddddeeeeffffgggghhhh

Example MAT/API request with action and api_key:

https://api.mobileapptracking.com/v2/advertiser/accounts/find.json&api_key=aaaabbbbccccddddeeeeffffgggghhhh

Endpoint Action's Parameters

An action's parameters defines the request to be serviced by its controller.

Endpoint Action's Return

The return result for most actions is transposed into JSON. The following is the JSON result from /account/users/find.json:

{
  "status_code": 200,
  "response_size": "327",
  "data": [
    {
      "country_id": 840,
      "region_id": 48,
      "id": 1587,
      "type": "company",
      "name": "HasOffers Demo Account",
      "address1": "2220 Western Ave.",
      "address2": "",
      "city": "Seattle",
      "zipcode": "98121",
      "phone": "206-508-11318",
      "website": "http:\/\/www.hasoffers.com",
      "verified_phone": false,
      "status": "active"
    }
  ]
}

Understanding Endpoint and Model Fields

Endpoints that bind to Models

Only Data Consuming Endpoints have Models, thereby only these endpoints have model fields.

These are examples of Read/Write Data Consuming Endpoints:

• /advertiser/ is \Model\Advertisers
• /advertiser/accounts/ is \Model\Accounts

Service Endpoints are not bound to a model, thereby its actions are bound to a service and do not have fields:

• /session/environment/

Mapping Model Fields within Endpoint

Data Consuming Endpoints defines access to fields of the Models it is bound to be available by its actions:

Model Fields

Models have a set of fields that provide access to their underlying data. For example, the following listing are the fields defining \Model\Advertisers, which defines the criteria for accessing this model by the Endpoint /account/ it is bound to.

It is especially important to note that the model data parameter of Action save.json must be compliant to the model fields for its dataset to be successfully received and then created. Model fields' constraints include if they are are required, property type, and value choice limitation.

Those fields marked as required are expected to values when creating a dataset within model called by via Action save.json.

Understanding Models

What are Models?

Models define the data binding for endpoints that use them.

Models enabling exchange of data representing accounts, advertisers, sites, etc. When a controller's action is requested, an entity relationship is established by creating an object instance of its associated model which adheres to the expected terms of access via their properties and relationships.

Models Bindings to Other Endpoints

Since it is an entity relationship to stored data, as set of fields and related entities are available for controllers to use, only if it so chooses to make them available through its associated actions.

Models can have a one-to-many binding to multiple endpoints, but endpoints can only be bound to one controller.

Understanding Related Endpoints and Models

Models may have identifiers which enforce links with other models, which these models would servicing the data need of other endpoints. Endpoints that have models with relations to other models, then these endpoints may expose actions to access its related endpoints.

Related Endpoints association with Endpoints are:

• Endpoint /advertiser/

  This endpoint is related to these other endpoints: /account/ /advertiser/agencies/ /advertiser/campaigns/ /advertiser/sites/ /agency/ This is because the model Advertisers it is bound to has identifiers that are associated with these other models: Accounts AdvertiserAgencies Campaigns Sites Agencies

• Endpoint /account/users/

This endpoint is not related to any other endpoints because it's associated model Users has no identifiers that are associated with these other models.

Related Endpoints' Property Name and Field Requests

The below shows field assignments from Endpoint and its Related Endpoints using assigned Property Name.

Service API Endpoint Actions

As mentioned earlier, "Data consumer" endpoints represent a connection point for querying its associated record for generating reports. Most of these endpoints have read/write functionality to create/update/delete datasets from their associated records, but some only have read-only functionality. "Data consumer" endpoints have a common set of actions for accessing associated records.

Accessing TUNE API Endpoints

API Service URL for Accessing Endpoints

The base Service URL for the TUNE API with currently available version is:

https://api.mobileapptracking.com/v2/

Endpoint paths are appended to the Service URL+Version by following these guidelines:

• All elements of the endpoint's path must be in lowercase.
• Endpoint paths must start with a base endpoint, for example /advertiser
• Paths may extend from here with one or more child endpoints, for example /accounts

Example MAT API request with controller path:

https://api.mobileapptracking.com/v2/advertiser/accounts/

Layout of API Endpoints

The Management API has 10 endpoints that start at the base of the Service URL, also referred to as Root Endpoints:

• (2) Read/Write Data Consumers – /account/, /advertiser/
• (6) Read/Only Data Consumers – /browser_platform/, /browsers/, /countries/, /currency_exchange_rates/, /languages/, /regions/
• (2) Generic Service – /export/, /session/

For example, the /account/ endpoint has a cascading set of sub-category data consumers, except for one endpoint (/account/users/password/) that accesses a service. Note how the endpoint paths extend from the base.

All active endpoints that provide either service or data-consuming functionality have one or more actions. However, there are some endpoints whose parent endpoint is only a category reference, and not an active endpoint with actions. For example, the /session/ endpoint has no actions; therefore, it is not an active endpoint and should not be used. However, this path does have sub-categories that are all active service endpoints.

Resource Authentication & User Permissions

Calls to the TUNE API require an api_key query string parameter to be passed with each request.

• api_key – API Keys are generated on a per-user basis, are permanent, and calls using an API Key are only allowed from devices with known IP addresses.

User Permissions with API Key

Since API Keys are on a per-user basis, they inherit the user's permissions because user permissions (ACLs) are enforced server-side in the TUNE API. Thus, the API Key should be associated with the user with the permissions you want applied.

Before using the TUNE API, you will need to create an API Key.

Generating an API Key

To generate an API Key, complete the following steps:

1. In the navigation (on the left side), under the Accounts section, click Users.
2. On the Users page, select the desired user.
3. On the User Details page, click the API Keys tab (near the top), and then click Add API Key.
4. In the Create API Key dialog box, enter a whitelisted IP address (optional), and then click Save. (These are the IP addresses that access the API. If you make your API requests from a server, then include its external IPs as well. To get your external IP address for the "Whitelist IP Addresses" list for the new API Key, visit a site like whatismyip.com.)
5. After adding your new API Key, it's displayed in the list for that user.

If you do not have access to the Account tab, ask a co-worker (who does have access) to generate an API Key for you.