Monitoring Performance with the Reporting API for Mobile Buyers

Quicklinks

Getting Started

Access to your ONE by AOL: Mobile Marketplace data via our Reporting API requires authentication and authorization using the following values:

CompanyID - 32 character GUID used for Authentication.

Company Access Key - your ONE by AOL: Mobile access key used for Authorization.

Secret Key - the ONE by AOL: Mobile password you use for Authorization.

If you are having trouble locating these values submit a request for help.

Design

The ONE by AOL: Mobile Marketplace Reporting API UI provides access to all of your data. The API is RESTful, with JSON object return and digest-based authentication. See below for detailed authentication, authorization and report specifications.

API Security

Note: easily confirm authentication is working correctly by using a command line utility like curl that already has digest authentication support built in. Here is a simple template for those requests:

curl --digest -u user:pass "report_url_here"

If you are not using a library to handle the authentication piece, follow these step-by-step instructions.

1. Login to the API.

2. Enter this URL https://reports.nexage.com/access/<CompanyID>/test into your browser. No additional credentials should be needed.

3. Receive a "401 Unauthorized" response code and WWW-Authenticate header for Digest Access Authentication. The header will include a Realm, Quality of Protection (QOP) code (i.e. either auth or auth-int or both), and a randomly-generated, single-use value called a Nonce. A few optional directives like domain, opaque and algorithm are not included. The client can assume the defaults as defined in RFC 2617. The defaults are:

Domain – Assume the protection space consists of all URIs on the responding server

Opaque – Ignore and client doesn't have to include this directive in any of subsequent requests

Algorithm – Assume the default algorithm is MD5

Example 401 Response Authentication Header

WWW-Authenticate: Digest realm="",
qop="",
nonce=""

4. Now the client is expected to retry the request, passing an Authorization header line that includes

"503 Service Unavailable" if the Reporting API is disabled or otherwise unavailable

6. Upon successful "200 OK" response, client can start invoking the reports. See the Report Specifications section for details.

The server may respond with “401 Unauthorized” if the Nonce has expired, even after successful authentication and authorization. In this case the response will include a WWW-Authenticate header with a stale flag set to true which signifies the Nonce is invalid but the digest (i.e., user credentials) is still valid. In this case, the client is expected to retry with a new encrypted response and Nonce.

Summary of HTTP Response Codes

The following response codes are used. No other responses should be expected.

HTTP Code

Definition

Conditions When Used

200

General Success

a) Successful retrieval of a report b) Successful authentication test

204

No Content

Call was authenticated and authorized, but report returned an empty body

Report Specifications

API Request Structure

reportID - the name of the specific report to be retrieved. See below for details.

params - request parameters specific to the report. See below for details.

General Reporting Rules and Notes

All dates in both parameters and report output are in the format "yyyy-mm-dd", where month and day are zero-filled. For example, July 4, 2019 would be represented as "2019-07-04"

All "day", "week", "month" attributes in report output are represented as "yyyy-mm-dd hh:mm:ss", where all times are ET. The value will be midnight of the first day in the range (i.e., the month July 2019 would be "2019-07-01 00:00:00")

All "hour" attributes in report output are represented as "hh:mm:ss", where all times are ET. The value is the beginning of each hourly interval (e.g., "00:00:00", "01:00:00", "02:00:00", etc.)

All countries in report output conform to the ISO-3166-Alpha-3 standard. For example, the United States, Canada, and Great Britain would be represented as "USA", CAN", and "GBR", respectively

In the JSON report specifications, the data types of each attribute (e.g., integer, float, string) are intended to be descriptive of the data and not prescriptive of a particular data binding

An empty response body is returned if any of the following error conditions is true:

An invalid "start" or "stop" date is passed

The "start" date is greater than (i.e., future with respect to) the "stop" date

The period of the report as specified by the "start" and "stop" dates exceeds 92 days

An invalid dimension is passed in the "dim" parameter

Filter parameter and dim parameter cannot be identical in a given request. For example, dim=country and country=USA is not valid and will return no content.

Available Reports

There are up to three reports available: Bidder Performance is available to all Bidders, while both CPI Conversion and Subscription Data Usage are available when enabled.

Bidder Performance

report ID = "bidderseatperformance"

The "start" and "stop" dates place time bounds on the report

Results can be further narrowed by filter parameters as indicated

The report can either be a summary by omitting the "dim" parameter or a detailed breakdown by whichever dimension is specified in "dim".

If the "dim" parameter is skipped, only the summary object will be included

If the "dim" parameter is specified, the "details" array will be shown in the report where each "detail" object corresponds to a unique value of that dimension (e.g., specific site, specific seat, etc.)

The inclusion of other attributes depends on the dimension specified in the request. For example, if "dim=site" on the request, then the "site" and "siteId" attributes will be included to differentiate each detail object.

When the "site" and "siteId" attributes are included, they are presented as they are to bidders through the RTB Exchange (e.g., site ID is not DCN). As such, they may be transparent or masked depending on the visibility settings of the associated RTB profile.

The "grossWins" attribute is a sum of all winning bids, whereas "spend" refers to the net cost based on confirmed ad deliveries.

For hour, day, week, or month dimensions, their respective attribute values are full timestamps.

If the "seat" parameter is specified on the request or if "dim=seat", then the "requests" and "responses" attributes are omitted.

CPI Conversion (only available if enabled)

reportID = "cpiconversions"

The "start" and "stop" dates place time bounds on the report

Results can be further narrowed by filter parameters as indicated

The report can either be a summary by omitting the "dim" parameter or a detailed breakdown by whichever dimension is specified in "dim"

If the "dim" parameter is specified, the "details" array will be returned where each "detail" object corresponds to a unique value of that dimension (e.g., specific app, specific campaign, etc.)

Within the "detail" object, the "installs", "clicks", "conversions", and "spend" attributes represent the actual data

The inclusion of other attributes depends on the dimension specified in the request. For example, if "dim=app" on the request, then the "app" attributes will be included to differentiate each detail object

For day, week, or month dimensions, their respective attribute values are full timestamps