- Overview
- SDK Installation
<li><a href="#sdk_gendoc">SDK Generated Documentation</a>
<ul>
<li><a href="#sdk_gendoc_yuidoc">YUIdoc</a></li>
</ul>
</li>
<li><a href="#sdk_advertiser_reporting_overview">Advertiser Reporting Overview</a>
</li>
<li><a href="#sdk_exporting_reports">Exporting Advertiser Reports</a>
</li>
<li><a href="#sdk_sources">SDK Sources</a>
<ul>
<li><a href="#sdk_sources_lib">Library</a></li>
<li><a href="#sdk_sources_examples">Examples</a></li>
<li><a href="#sdk_sources_tests">Tests</a></li>
</ul>
</li>
<li><a href="#sdk_classes">SDK Classes</a>
<ul>
<li><a href="#sdk_classes_service">TUNE Management Service Classes</a></li>
<li><a href="#sdk_report_readers">Helper Classes</a></li>
<li><a href="#sdk_classes_exceptions">Exception Classes</a></li>
</ul>
</li>
<li>
<a href="#sdk_methods">Advertiser Reporting Methods</a>
<ul>
<li><a href="#sdk_method_count"><code>count()</code></a></li>
<li><a href="#sdk_method_find"><code>find()</code></a></li>
<li><a href="#sdk_method_export"><code>export()</code></a></li>
<li><a href="#sdk_method_status"><code>status()</code></a></li>
<li><a href="#sdk_method_fetch"><code>fetch()</code></a></li>
<li><a href="#sdk_method_fields"><code>fields()</code></a></li>
</ul>
</li>
<li><a href="#sdk_reporting_fields">Advertiser Reporting Fields</a>
</li>
<li>
<a href="#sdk_parameters">Advertiser Reporting Parameters</a>
<ul>
<li><a href="#sdk_parameter_fields"><code>fields</code></a></li>
<li><a href="#sdk_parameter_group"><code>group</code></a></li>
<li><a href="#sdk_parameter_sort"><code>sort</code></a></li>
<li><a href="#sdk_parameter_filter"><code>filter</code></a></li>
</ul>
</li>
<li><a href="#sdk_license">MIT License</a>
</li>
<li><a href="#sdk_issues">SDK Issues</a>
</li>
The TUNE Reporting SDKs addressed in this posting are for creating hosted applications which require handling requests to TUNE Advertiser Report services with utility focus is upon Advertiser Reporting endpoints.
Even though the the breadth of the Management API goes beyond just reports, it is these reporting endpoints that our customers primarily access.
The second goal of the SDKs is to assure that our customers’ developers are using best practices in gathering reports in the most optimal way.
Supported programming languages for TUNE Reporting SDKs are:
- PHP: tune-reporting-php
- Python: tune-reporting-python
- Java: tune-reporting-java
- Node.js: tune-reporting-node
- Go: Coming soon
- C#: Coming soon
The TUNE Reporting SDKs should absolutely not be included within Mobile Apps.
All information pertaining to TUNE SDKs for Mobile Apps are found here.
Developer Community portal for MobileAppTracking™ (MAT), the industry leader in mobile advertising attribution and analytics. From API documentation to best practices, get everything you need to be successful with MAT.
https://developers.mobileapptracking.com
Additional positions on TUNE Reporting SDKs can be found here:
https://developers.mobileapptracking.com/tune-reporting-sdks/
This section detail what is required to use this SDK and how to install it for usage.
These are the basic requirements to use this SDK:
* node >= 0.10.*
* npm >= 1.4.*
To use SDK to access Advertiser Reporting endpoints of TUNE Advertiser Report, it requires a MobileAppTracking API Key: Generate API Key.
You can install tune-reporting-node via npm or by downloading the source from github.
It is available on npm: tune-reporting
Install as follows
$ npm install tune-reportingClick here to download the source code
(.zip) for tune-reporting.
$ git clone git@github.com:MobileAppTracking/tune-reporting-node
$ cd tune-reporting-node
$ npm install .The TUNE Reporting SDK configuration is set within file ./config.js.
And the appropriate environment settings:
config
├── development.json
├── production.json
└── test.json
With generated API_KEY from TUNE MobileAppTracking Platform account, replace UNDEFINED.
; TUNE MobileAppTracking Platform generated API Key. Replace UNDEFINED.
tune.reporting.auth_key=UNDEFINED
; TUNE Reporting Authentication Type: api_key OR session_token.
tune.reporting.auth_type=api_key
; Validate use TUNE Management API fields used within action parameters.
tune.reporting.verify_fields_boolean=false
; TUNE reporting export status sleep (seconds).
tune.reporting.status.sleep=10
; TUNE reporting export fetch timeout (seconds).
tune.reporting.status.timeout=240
; TUNE reporting export fetch verbose output.
tune.reporting.status.verbose=false
The TUNE Reporting SDK reads configuration through module ./config.js with the
current environment SDK configuration file.
var
authKey = config.get('tune.reporting.auth_key'),
authType = config.get('tune.reporting.auth_type');By default, configuration is assumed using api_key authentication type.
To override 'api_key' authentication type:
config.set('tune.reporting.auth_key', apiKey);
config.set('tune.reporting.auth_type', 'api_key');To override authentication type using session_token:
config.set('tune.reporting.auth_key', sessionToken);
config.set('tune.reporting.auth_type', 'session_token');If you wish to generate your own session_token, class SessionAuthentication is provided:
var
apiKey = config.get('tune.reporting.auth_key'),
sessionAuthenticate = new SessionAuthenticate();
sessionAuthenticate.getSessionToken(apiKey, function (error, response) {
if (error) {
return next(error);
}
console.log(' Status: "success"');
sessionToken = response.getData();
console.log(' session_token:');
console.log(sessionToken);
return next();
});and you're good to go!
SDK code is well commented and to see full documentation of its source using the provided Makefile commands that initiate code documentation generators.
The following will generate YUIdoc from Node.js codebase:
This code documentation generation may require npm installation of YUIdoc.
$ make docs-yuidoc
### Advertiser Reporting Overview
The utility focus of the SDKs is upon the Advertiser Reporting endpoints. Even though the the breadth of the Management API goes beyond just reports, it is these endpoints that our customers primarily access. The second goal of the SDKs is to assure that our customers' developers are using best practices in gathering reports in the most optimal way.
The endpoints interfaced by TUNE API SDKs provide access in gathering four types of reports:
- Log Reports
-
Log reports provide measurement records for each Click, Install, Event, Event Item and Postback. Instead of being aggregated, the data is on a per transaction / request basis. MobileAppTracking™ (MAT) uses these logs to generate the aggregated data for the Actuals and Cohort reports. Note that we don’t provide Log reports for Impressions and Opens currently.
Advertiser Reporting classes that perform Log Reports are:
AdvertiserReportLogClicks: /advertiser/stats/clicks/AdvertiserReportLogEventItems:/advertiser/stats/event/items/AdvertiserReportLogEvents:/advertiser/stats/events/AdvertiserReportLogInstalls:/advertiser/stats/installs/AdvertiserReportLogPostbacks:/advertiser/stats/postbacks/
- Actuals Report
-
The Actuals report gives you quick insight into the performance of your apps and advertising partners (publishers). Use this report for reconciliation, testing, debugging, and ensuring that all measurement and attribution continues to operate smoothly. MAT generates this report by aggregating all the logs of each request (MAT updates the report every 5 minutes).
Actuals report endpoint include: /advertiser/stats/: Reports' class
AdvertiserReportActualsAdvertiser Reporting class that perform Actuals Reports is:
AdvertiserReportActuals: /advertiser/stats/
- Cohort Report
-
The Cohort report analyzes user behavior back to click date time (Cohort by Click) or to install date time (Cohort by Install). Depending on whether you view the results based on click or install, the data in the report is vastly different.
Advertiser Reporting class that perform Cohort Reports is:
AdvertiserReportCohortValue: /advertiser/stats/ltv
- Retention Report
-
The Retention report shows you how many of your installed users open or engage with your app over time (how users continue to get value from the app). AdvertiserReportCohortRetention reports are particularly good for evaluating the quality of users as opposed to the quantity of users (as in the case of user acquisition campaigns). For more information about retention reports, please visit Running AdvertiserReportCohortRetention Reports.
Advertiser Reporting class that perform Retention Reports are:
AdvertiserReportCohortRetention: /advertiser/stats/retention
Currently, there are two different ways of handling advertiser report exports. Both approaches require (A) an action to request that a report be exported and (B) another action to request the report status (if ready to be exported), and if ready, then provide a URL to download the completed report.
Logs and Actuals reports all request an export using action find_export_queue.json, which returns a job_id. You then pass the job_id onto another endpoint Export::download.json, which performs the status checking and report URL retrieval.
Cohort and AdvertiserReportCohortRetention reports all request an export using action export.json, which also returns a job_id. You then pass the job_id onto another action status.json, which performs the status checking and report URL retrieval.
The key contents of SDK is src, which contains the library; followed by the examples, and tests.
File Makefile provides shortcuts for executing examples and tests.
.
├── AUTHORS.md
├── CHANGES.md
├── config
│ ├── development.json
│ ├── jsdoc.json
│ ├── nodelint.js
│ ├── production.json
│ ├── test.json
│ └── yuidoc.json
├── config.js
├── docs
├── examples
├── index.js
├── lib
├── Makefile
├── package.json
├── README.md
└── test
File index.js is the root of this Library.
Library folder lib contains the key functionality related to Advertiser Reporting classes are defined within folder /lib/api/.
Client classes that connect with the TUNE Advertiser Report Service are defined within folder /lib/base/service/.
Helper class for both the Library and Examples are defined within folder /lib/helpers/.
lib/
├── api
│ ├── AdvertiserReportActuals.js
│ ├── AdvertiserReportCohortRetention.js
│ ├── AdvertiserReportCohortValue.js
│ ├── AdvertiserReportLogClicks.js
│ ├── AdvertiserReportLogEventItems.js
│ ├── AdvertiserReportLogEvents.js
│ ├── AdvertiserReportLogInstalls.js
│ ├── AdvertiserReportLogPostbacks.js
│ ├── Export.js
│ ├── index.js
│ └── SessionAuthenticate.js
├── base
│ ├── endpoints
│ │ ├── AdvertiserReportActualsBase.js
│ │ ├── AdvertiserReportBase.js
│ │ ├── AdvertiserReportCohortBase.js
│ │ ├── AdvertiserReportLogBase.js
│ │ ├── EndpointBase.js
│ │ └── index.js
│ ├── index.js
│ └── service
│ ├── index.js
│ ├── TuneManagementClient.js
│ ├── TuneManagementQueryString.js
│ ├── TuneManagementRequest.js
│ └── TuneManagementResponse.js
├── helpers
│ ├── Date.js
│ ├── index.js
│ ├── InvalidArgument.js
│ ├── LogicError.js
│ ├── NotImplemented.js
│ ├── ReportReaderCSV.js
│ ├── ReportReaderJSON.js
│ ├── String.js
│ ├── TuneSdkError.js
│ └── TuneServiceError.js
└── index.js
Run the following script to view execution of all examples:
$ make examples api_key=[API_KEY]Each Advertiser Report class defined in /lib/api/ has an example:
examples/
├── ExampleAdvertiserReportActuals.js
├── ExampleAdvertiserReportCohortRetention.js
├── ExampleAdvertiserReportCohortValue.js
├── ExampleAdvertiserReportLogClicks.js
├── ExampleAdvertiserReportLogEventItems.js
├── ExampleAdvertiserReportLogEvents.js
├── ExampleAdvertiserReportLogInstalls.js
├── ExampleAdvertiserReportLogPostbacks.js
└── ExampleTuneManagementClient.js
Run the following script to view execution of all unittests:
$ make test api_key=[API_KEY]Each Advertiser Report class defined in /lib/api/ has a test:
test/
├── TestAdvertiserReportActuals.js
├── TestAdvertiserReportCohortRetention.js
├── TestAdvertiserReportCohortValue.js
├── TestAdvertiserReportLogClicks.js
├── TestAdvertiserReportLogEventItems.js
├── TestAdvertiserReportLogEvents.js
├── TestAdvertiserReportLogInstalls.js
├── TestAdvertiserReportLogPostbacks.js
└── TestTuneManagementClient.js
TuneManagementClient- Connects with TUNE Advertiser Report ServiceTuneManagementRequest- Defines request to TUNE Advertiser Report Service containing:- Controller / Endpoint
- Action
- Query String Parameters
- API Key
TuneManagementResponse- Complete response from TUNE Advertiser Report Service containing:- Status Code
- Data
- Errors
ReportReaderCSV- Reads exported CSV report using downloaded URL.ReportReaderJSON- Reads exported JSON report using downloaded URL.
TuneSdkException- Exception thrown if error occurs within TUNE Reporting SDK.TuneServiceException- Exception thrown if error condition is returned from TUNE Management Service.
Important to note on Sample Code: The example provided pertain to only Advertiser Reports class AdvertiserReportLogClicks. The fields used theses sample primarily pertain to the available fields for the record and related records for the the associated endpoint /advertiser/stats/clicks of this class. Do not expect that these fields will be available if used with other Advertiser Records classes.
The benefit of using TUNE Reporting API SDKs is it provides the same interface across all advertiser reports. The following class diagram lists what are all the expected functions. The signature of the expected parameters for each function will be consistent with the action it is interfacing.
Finds all existing records matching provided filter criteria and returns total count. It returns a populated instance of class Response, class of TUNE Reporting API SDK, with record count.
var advertiserReport = new AdvertiserReportLogClicks();
var count_request = advertiserReport.count(
startDate,
endDate,
null, // filter
strResponseTimezone
);
count_request.once('success', function onSuccess(response) {
if ((response.getHttpCode() !== 200) || (response.getErrors() !== null)) {
next(response);
} else {
var count = response.getData();
console.log('\n');
console.log(' Status: "success"');
console.log(' TuneManagementResponse:');
console.log(response.toString());
console.log('\n');
console.log(util.format(' Count: %d', count));
next();
}
});
count_request.once('error', function onError(response) {
return next(response);
});Gathers all existing records that match filter criteria and returns an array of found model data. Even though calling the action find.json is commonly used for gathering data, however it is not the preferred way of gathering full reports. It returns a populated instance of class Response with records.
var advertiserReport = new AdvertiserReportLogClicks();
var find_request = advertiserReport.find(
startDate,
endDate,
fieldsRecommended,
null, // filter
5, // limit
null, // page
{ 'created': 'DESC' }, // sort
strResponseTimezone
);
find_request.once('success', function onSuccess(response) {
if ((response.getHttpCode() !== 200) || (response.getErrors() !== null)) {
next(response);
} else {
console.log('\n');
console.log(' Status: "success"');
console.log(' TuneManagementResponse:');
console.log(response.toString());
next();
}
});
find_request.once('error', function onError(response) {
return next(response);
});Provides the same signature as function find(), accept parameters limit and page, because this function's intent is to request export of a full report. It returns a populated instance of class Response with job identifier of report in queue and ready to be processed. Format of content can be requested to be either CSV or JSON.
var advertiserReport = new AdvertiserReportLogClicks();
var export_request = advertiserReport.exportReport(
startDate,
endDate,
fieldsRecommended,
null, // filter
'csv', // format
strResponseTimezone
);
export_request.once('success', function onSuccess(response) {
if ((response.getHttpCode() !== 200) || (response.getErrors() !== null)) {
next(response);
} else {
console.log('\n');
console.log(' Status: "success"');
console.log(' TuneManagementResponse:');
console.log(response.toString());
csvJobId = advertiserReport.parseResponseReportJobId(response);
console.log('\n');
console.log(util.format(' CSV Report Job ID: "%s"', csvJobId));
next();
}
});
export_request.once('error', function onError(response) {
return next(response);
});As discussed in Exporting Advertise Reports, for gathering report export status records' classes Cohort (AdvertiserReportCohortValue) and AdvertiserReportCohortRetention uses it own method status(). Its purpose is the same as method Export::download().
A helper function that creates a threaded worker that handles the status request appropriate to it class. This function handles the polling of the service waiting for status of "complete" and its "report url". Upon completion, fetch downloads data into a reader that parses the contents that is appropriate requested content format type, CSV or JSON.
var advertiserReport = new AdvertiserReportLogClicks();
var fetch_request = advertiserReport.fetchReport(
csvJobId
);
fetch_request.once('success', function onSuccess(response) {
if ((response.getHttpCode() !== 200) || (response.getErrors() !== null)) {
next(response);
} else {
console.log('\n');
console.log(' Status: "success"');
console.log(' TuneManagementResponse:');
console.log(response.toString());
csvReportUrl = advertiserReport.parseResponseReportUrl(response);
console.log('\n');
console.log(util.format(' CSV Report URL: "%s"', csvReportUrl));
next();
}
});
fetch_request.once('error', function onError(response) {
return next(response);
});Method fields() returns a listing of all the fields that can be used that can be used by that report endpoint, which will include all the field of its immediate record and all its related records.
var advertiserReport = new AdvertiserReportLogClicks(
apiKey,
true
);
var fields_request = advertiserReport.getFields(
EndpointBase.TUNE_FIELDS_RECOMMENDED
);
fields_request.once('success', function onSuccess(response) {
console.log('\n');
console.log(' Status: "success"');
console.log(' TuneManagementResponse:');
console.log(response);
fieldsRecommended = response;
next();
});
fields_request.once('error', function onError(response) {
return next(response);
});
It is important to understand that every endpoint has its own unique set of fields based upon the model 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 a service error. So 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.
Two helpful functions that come with every report class are define() and fields(). Every advertiser reports endpoint has a different data model associated with it. With that, what fields are available are not consistent across records. So use these functions to understand available field choices.
Function define() returns a complete metadata mapping of the endpoint, and function fields() returns a complete listing of all field names of the model associated with the endpoint function was called through, and endpoint's related entities' field names.
In addition, the constructor for every advertiser records' class has a bool parameter validate which checks that the field names used within parameter values are valid.
Another tool is to pre-build your request using Management API Root Endpoints Explorer.
- AdvertiserReportActuals' fields: /advertiser/stats fields
- AdvertiserReportCohortRetention' fields: /advertiser/stats/retention fields
- AdvertiserReportCohortValue' fields: /advertiser/stats/ltv fields
- AdvertiserReportLogClicks' fields: /advertiser/stats/clicks fields
- AdvertiserReportLogEventItems' fields: /advertiser/stats/event/items fields
- AdvertiserReportLogEvents' fields: /advertiser/stats/events fields
- AdvertiserReportLogInstalls' fields: /advertiser/stats/installs fields
- AdvertiserReportLogPostbacks' fields: /advertiser/stats/postbacks fields
Most of the functions provided for the record classes have the following parameters in common. All of these parameters are based upon knowledge of available fields for that endpoint, which are discovered using endpoint's functions define() and fields().
##### Parameter
fields
Parameter fields can either be an array of field names, or a string containing comma-delimited field named:
##### Parameter
group
Parameter group is the same as parameter fields can either be an array of field names, or a string containing comma-delimited field named:
##### Parameter
sort
Parameter sort is a dictionary (associative array), where the key is the field name and value is the expected sort direction of either "DESC" or "ASC".
##### Parameter
filter
Parameter filter is a string that contains a set of query expressions based upon matching conditions to endpoint's fields. It is especially important to to provide an invalid field name because that will cause request to fail.
Report issues using the Github Issue Tracker or Email sdk@tune.com.