tune-reporting/README.md

TUNE Reporting SDK for Node.js

<h2>tune-reporting</h2>
<h2>TUNE Reporting SDK for Node</h2>
<h3>Incorporate TUNE Reporting services.</h3>
<h4>Update:  $Date: 2015-08-26 17:15:38 $</h4>
<h4>Version: 1.0.11</h4>
===

<a id="TOP"></a>
### Table of Contents

<ul>
    <li><a href="#sdk_overview">Overview</a>
        <ul>
            <li><a href="#sdk_overview_available">Available TUNE Reporting SDKs</a></li>
            <li><a href="#sdk_overview_mobile">TUNE SDKs for Mobile Apps</a></li>
            <li><a href="#sdk_overview_dev_community">Developers Community</a></li>
        </ul>
    </li>
    <li><a href="#sdk_install">SDK Installation</a>
        <ul>
            <li><a href="#sdk_install_prereq">Prerequisites</a>
                <ul>
                    <li><a href="#sdk_install_prereq_env">Environment</a></li>
                    <li><a href="#sdk_install_prereq_ini">node.ini</a></li>
                    <li><a href="#sdk_install_prereq_apikey">Environment</a></li>
                </ul>
            </li>
            <li><a href="#sdk_install_choices">Choices</a>
                <ul>
                    <li><a href="#sdk_installation_npm">Composer</a></li>
                    <li><a href="#sdk_install_method_zip">ZIP</a></li>
                    <li><a href="#sdk_prerequisites_api_key">Environment</a></li>
                </ul>
            </li>
            <li><a href="#sdk_install_library">Library</a></li>
            <li><a href="#sdk_install_config">Configuration</a></li>
        </ul>
    </li>
    <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_license">MIT License</a>
    </li>
    <li><a href="#sdk_issues">SDK Issues</a>
    </li>
</ul>

<p>
<a href="#TOP">
<img alt="Return to Top" src="https://raw.githubusercontent.com/MobileAppTracking/tune-reporting-node/master/docs/images/b_top.gif" border="0">
</a>
</p>

<!-- Overview -->

<a id="sdk_overview" name="sdk_overview"></a>
### Overview

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

<a id="sdk_overview_available" name="sdk_overview_available"></a>
#### Available TUNE Reporting SDKs

Supported programming languages for TUNE Reporting SDKs are:

<ul>
    <li><b>PHP</b>: <a href="https://github.com/MobileAppTracking/tune-reporting-php" target="_blank">tune-reporting-php</a></li>
    <li><b>Python</b>: <a href="https://github.com/MobileAppTracking/tune-reporting-python" target="_blank">tune-reporting-python</a></li>
    <li><b>Java</b>: <a href="https://github.com/MobileAppTracking/tune-reporting-java" target="_blank">tune-reporting-java</a></li>
    <li><b>Node.js</b>: <a href="https://github.com/MobileAppTracking/tune-reporting-node" target="_blank">tune-reporting-node</a></li>
    <li><b>Go</b>: Coming soon</li>
    <li><b>C#</b>: Coming soon</li>
</ul>

<a id="sdk_overview_mobile" name="sdk_overview_mobile"></a>
#### TUNE SDKs for Mobile Apps

The **TUNE Reporting SDKs** should absolutely not be included within Mobile Apps.

All information pertaining to **TUNE SDKs for Mobile Apps** are found [here](http://developers.mobileapptracking.com/sdks/).

<a id="sdk_overview_dev_community" name="sdk_overview_dev_community"></a>
#### Developers Community

<p><a href="https://developers.mobileapptracking.com" target="_blank"><strong>Developers Community Site</strong></a> for MobileAppTracking™ (MAT), the industry leader in mobile advertising attribution and analytics, provides TUNE Reporting API documentation to best practices and everything you need to be successful with MAT.
</p>

<p>This site contains complete information about <a href="https://developers.mobileapptracking.com/reporting-api/" target="_blank">TUNE Reporting API</a>, and references to all available <a href="https://developers.mobileapptracking.com/reporting-api/" target="_blank">TUNE Reporting SDKs</a> with sample code.
</p>

<p>
<a href="#TOP">
<img alt="Return to Top" src="https://raw.githubusercontent.com/MobileAppTracking/tune-reporting-node/master/docs/images/b_top.gif" border="0">
</a>
</p>

<!-- Installation -->

<a id="sdk_install" name="sdk_install"></a>
### SDK Installation

This section detail what is required to use this SDK and how to install it for usage.

<a id="sdk_install_prereq" name="sdk_install_prereq"></a>
#### Installation Prerequisites

<a id="sdk_install_prereq_env" name="sdk_install_prereq_env"></a>
##### Environment

These are the basic requirements to use this SDK:

    * node >= 0.10.*
    * npm >= 1.4.*

<a id="sdk_install_prereq_apikey" name="sdk_install_prereq_apikey"></a>
##### Generate API Key

To use SDK to access Advertiser Reporting endpoints of TUNE Advertiser Report, it requires a MobileAppTracking API Key: [Generate API Key](http://developers.mobileapptracking.com/generate-api-key/).

<a id="sdk_install_choices" name="sdk_install_choices"></a>
#### Installation Choices

You can install **tune-reporting-node** via *npm* or by downloading the source from github.

<a id="sdk_installation_npm" name="sdk_installation_npm"></a>
##### Via npm:

It is available on [npm](https://www.npmjs.com/): [*tune-reporting*](https://www.npmjs.com/package/tune-reporting)

Install as follows

```bash
    $ npm install tune-reporting
```

<a id="sdk_install_method_zip" name="sdk_install_method_zip"></a>
##### Via ZIP file:

[Click here to download the source code
(.zip)](https://github.com/MobileAppTracking/tune-reporting-node/archive/master.zip) for `tune-reporting`.

```bash
    $ git clone git@github.com:MobileAppTracking/tune-reporting-node
    $ cd tune-reporting-node
    $ npm install .
```

<a id="sdk_install_config" name="sdk_install_config"></a>
#### TUNE Reporting SDK Configuration

##### SDK Configuration file

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 Service 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
```

##### SDK Configuration module

The TUNE Reporting SDK reads configuration through module ```./config.js``` with the
current environment SDK configuration file.

```javascript
  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:

```javascript
    config.set('tune.reporting.auth_key', apiKey);
    config.set('tune.reporting.auth_type', 'api_key');
```

To override authentication type using ```session_token```:

```javascript
    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:

```javascript
  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!

<p>
<a href="#TOP">
<img alt="Return to Top" src="https://raw.githubusercontent.com/MobileAppTracking/tune-reporting-node/master/docs/images/b_top.gif" border="0">
</a>
</p>

<!-- Generated Documentation -->

<a id="sdk_gendoc" name="sdk_gendoc"></a>
### SDK Generated Documentation

SDK code is well commented and to see full documentation of its source using the provided Makefile commands that initiate code documentation generators.

<a id="sdk_gendoc_yuidoc" name="sdk_gendoc_yuidoc"></a>
#### Node.jsdoc

The following will generate [YUIdoc](http://yui.github.io/yuidoc/) from Node.js codebase:

This code documentation generation may require npm installation of [YUIdoc](http://yui.github.io/yuidoc/).

<pre lang="bash">
    $ make docs-yuidoc
</pre>

<p>
<figure id="attachment_17743" class="thumbnail wp-caption aligncenter" style="width: 600px"><a href="https://mat-websites.s3.amazonaws.com/wp-content/uploads/reporting_sdk_node_yuidoc.png"><img src="https://mat-websites.s3.amazonaws.com/wp-content/uploads/reporting_sdk_node_yuidoc-600x359.png" alt="TUNE Reporting SDK YuiDoc Generated" width="600" height="359" class="size-docs_600 wp-image-17743"></a><figcaption class="caption wp-caption-text"><p>TUNE Reporting SDK YuiDoc Generated</p></figcaption></figure>
</p>

<p>&nbsp;</p>
<a id="sdk_advertiser_reporting_overview" name="sdk_advertiser_reporting_overview"></a>
### Advertiser Reporting Overview

The utility focus of the SDKs is upon the <a href="https://developers.mobileapptracking.com/reporting-api/" target="_blank">Advertiser Reporting API endpoints</a>. 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.

<figure style="width: 600px"><a href="http://mat-websites.s3.amazonaws.com/wp-content/uploads/tune_reporting_sdk_classes.png"><img src="http://mat-websites.s3.amazonaws.com/wp-content/uploads/tune_reporting_sdk_classes-600x365.png" alt="TUNE Reporting SDK Classes" width="600" height="365" class="size-docs_600 wp-image-17763"></a><figcaption class="caption wp-caption-text">TUNE Reporting SDK Classes</figcaption></figure>

The endpoints interfaced by TUNE API SDKs provide access in gathering four types of reports:

<dl>
<dt>Log Reports</dt>
<dd>
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&trade; (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:
<ul>
    <li><code>AdvertiserReportLogClicks</code>: <a href="http://developers.mobileapptracking.com/management-api/explorer/root/endpoint/#/advertiser__stats__clicks/">/advertiser/stats/clicks/</a></li>
    <li><code>AdvertiserReportLogEventItems</code>:<a href="http://developers.mobileapptracking.com/management-api/explorer/root/endpoint/#/advertiser__stats__event__items/">/advertiser/stats/event/items/</a></li>
    <li><code>AdvertiserReportLogEvents</code>:<a href="http://developers.mobileapptracking.com/management-api/explorer/root/endpoint/#/advertiser__stats__events/">/advertiser/stats/events/</a></li>
    <li><code>AdvertiserReportLogInstalls</code>:<a href="http://developers.mobileapptracking.com/management-api/explorer/root/endpoint/#/advertiser__stats__installs/">/advertiser/stats/installs/</a></li>
    <li><code>AdvertiserReportLogPostbacks</code>:<a href="http://developers.mobileapptracking.com/management-api/explorer/root/endpoint/#/advertiser__stats__postbacks/">/advertiser/stats/postbacks/</a></li>
</ul>

</dd>
<dt>Actuals Report</dt>
<dd>
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: <a href="http://developers.mobileapptracking.com/management-api/explorer/root/endpoint/#/advertiser__stats/">/advertiser/stats/</a>: Reports' class <a href="#sdk-advertiser-report-actuals"><code>AdvertiserReportActuals</code></a>

Advertiser Reporting class that perform Actuals Reports is:
<ul>
    <li><code>AdvertiserReportActuals</code>: <a href="http://developers.mobileapptracking.com/management-api/explorer/root/endpoint/#/advertiser__stats/">/advertiser/stats/</a></li>
</ul>
</dd>
<dt>Cohort Report</dt>
<dd>
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:
<ul>
    <li><code>AdvertiserReportCohortValue</code>: <a href="http://developers.mobileapptracking.com/management-api/explorer/root/endpoint/#/advertiser__stats__ltv">/advertiser/stats/ltv</a></li>
</ul>
</dd>
<dt>Retention Report</dt>
<dd>
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 <a href="http://support.mobileapptracking.com/entries/42179044-Running-AdvertiserReportCohortRetention-Reports">Running AdvertiserReportCohortRetention Reports</a>.

Advertiser Reporting class that perform Retention Reports are:
<ul>
    <li><code>AdvertiserReportCohortRetention</code>: <a href="http://developers.mobileapptracking.com/management-api/explorer/root/endpoint/#/advertiser__stats__retention">/advertiser/stats/retention</a></li>
</ul>
</dd>
</dl>
<figure id="attachment_17769" class="thumbnail wp-caption aligncenter" style="width: 600px"><a href="http://mat-websites.s3.amazonaws.com/wp-content/uploads/tune_reporting_api_endpoints1.png"><img src="http://mat-websites.s3.amazonaws.com/wp-content/uploads/tune_reporting_api_endpoints1-600x315.png" alt="TUNE Reporting API Endpoints" width="600" height="315" class="size-docs_600 wp-image-17769"></a><figcaption class="caption wp-caption-text"><p>TUNE Reporting API Endpoints</p></figcaption></figure>
<p>
<a href="#TOP">
<img alt="Return to Top" src="https://raw.githubusercontent.com/MobileAppTracking/tune-reporting-node/master/docs/images/b_top.gif" border="0">
</a>
</p>

<a id="sdk_exporting_reports" name="sdk_exporting_reports"></a>
### Exporting Advertiser Reports
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 <code>find_export_queue.json</code>, which returns a <code>job_id</code>. You then pass the <code>job_id</code> onto another endpoint <code>Export::download.json</code>, which performs the status checking and report URL retrieval.

Cohort and AdvertiserReportCohortRetention reports all request an export using action <code>export.json</code>, which also returns a <code>job_id</code>. You then pass the <code>job_id</code> onto another action <code>status.json</code>, which performs the status checking and report URL retrieval.

<p>
<a href="#TOP">

<img alt="Return to Top" src="https://raw.githubusercontent.com/MobileAppTracking/tune-reporting-node/master/docs/images/b_top.gif" border="0">
</a>
</p>

<!-- Licenses -->

<a id="sdk_license" name="sdk_license"></a>
### License

[MIT License](http://opensource.org/licenses/MIT)

<a id="sdk_issues" name="sdk_issues"></a>
### Reporting Issues

Report issues using the [Github Issue Tracker](https://github.com/MobileAppTracking/tune-reporting-node/issues) or Email [sdk@tune.com](mailto:sdk@tune.com).