Monitoring Performance with the Reporting API for Mobile Buyers

Buyers may choose to use our Reporting API instead of accessing Reports via the UI.

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

Our Reporting API uses Digest Access Authentication.

  • For those using Java, we highly recommend using Apache HttpClient.
  • For those using PHP, we recommend referencing this manual

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. Gain access to the API.

2. Make a request using https://reports.nexage.com/access/<CompanyID>/test. No credentials are needed at this point.

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

  • Username - Company Access Key
  • Response - the combined MD5 checksum of the following parameters:
    • HA1: The MD5 hash of the combined username (Company Access Key), realm and password (Secret Key)
    • Server nonce
    • Request counter
    • Client nonce (Client generated)
    • QOP code
    • HA2: The MD5 hash of the combined method (e.g. GET) and digest URI (e.g. "/<company id>/test")
  • Realm
  • Nonce
  • URI - from Request-URI of the Request Line (Duplicated here because proxies are allowed to change the Request-Line in transit)
  • QOP code: set to one of the values returned in the WWW-Authenticate header
  • Client Nonce -an opaque quoted string value provided by the client
  • Nonce Count - the hexadecimal count of the number of requests (including the current request) that the client has sent with the nonce value

Example Authorization Header

Authorization: Digest username="",
            response="",
            realm="",
            nonce="",
            uri="//test",
            qop=,
            cnonce="",
            nc=

5. The server should respond with one of the following:

  • "200 OK" if Authentication was successful
  • “401 Unauthorized” if Authorization or Authentication failed
  • "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
401 Unauthorized a) Authentication failure
b) Authorization failure
503 Service Unavailable The API is disabled

 

Back to Top

Report Specifications

API Request Structure

The general request structure is:

https://reports.nexage.com/access//reports/?
  • 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".
Parameter Required Description
start Yes Date of the first day of data included in the report
stop Yes Date of the last day of data included in the report
dim No The dimension by which details are broken down. Options are: "site", "seat", "hour", "day", "week", and "month".
site No Filters data by the site specified
seat No Filters data by the seat specified

Example of API Subscription Data Usage Report Request

https://reports.nexage.com/access/1234567890/reports/bidderseatperformance?start=2013-01-04&stop=2013-03-05&dim=hour&site=4a809429013835566f4f9ac0798422f0&seat=111

Example of Reporting API Response in JSON format

{
  "summary": { "requests": "integer", “responses”: “integer”, "bids": "integer", "wins": "integer", “insufficientBids”: “integer”, "timeouts": "integer", "forfeits": "integer", "delivered": "integer", “grossWins”: “float”, "spend": "float" },
  "detail": [
    { “site”: “string”, “siteId”: “string”, “seat”: “string”, “hour”: “string”, “day”: “string”, “week”: “string”, “month”: “string”, “requests”: “integer”, “responses”: “integer”, “bids”: “integer”, “wins”: “integer”, “insufficientBids”: “integer”, “timeouts”: “integer”, “forfeits”: “integer”, “delivered”: “integer”, “grossWins”: “float”, "spend": "float" }, ...
  ]
}

  • 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.)
  • Within the "detail" object, the "requests", "responses", "bids", "wins", "insufficientBids", "timeouts", "forfeits", "delivered", "grossWins", and "spend" attributes represent the actual data.
  • 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"
Parameter Required Description
start Yes Date of the first day of data included in the report
stop Yes Date of the last day of data included in the report
dim No The dimension by which details are broken down. Options are: "app", "campaign", "creative", "country", "hour", "day", "week", "month"
app No Filters data by the promo application specified.
campaign No Filters data by the campaign ID specified.
creative No Filters data by the creative ID specified.
country No Filters data by the country specified

 

Example of an API request for CPI Conversion report

https://reports.nexage.com/access/1234567890/reports/cpiconversions?start=2013-01-04&stop=2013-03-05&dim=day&app=111&campaign=222&creative=3333&country=USA

 

Example Reporting API Response in JSON format

[
  {
    "summary": { "installs": "integer", "clicks": "integer", "conversions": "integer", "spend": "float" }
  }
]
- or -
{
  "detail": [
    { "app": "string", "campaign": "string", "creative": "string", "country": "string", "day": "string", "week": "string", "month": "string",
      "installs": "integer", "clicks": "integer", "conversions": "integer", "spend": "float" }, ...
  ]
}
  • If the "dim" parameter is skipped, the "summary" will be returned
  • 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

 

Subscription Data Usage (only available if enabled)

reportID = "rtbsubscriptiondatausage"

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

Parameter Required Description
start Yes Date of the first day of data included in the report
stop Yes Date of the last day of data included in the report

Example of API Subscription Data Usage Report Request

 https://reports.nexage.com/access/1234567890/reports/rtbsubscriptiondatausage?start=2013-01-04&stop=2013-03-05

Example Reporting API Response in JSON format

{
  "detail": [
    { "provider": "string", "providerRequests": "integer", "overallBidRequests": "integer", "bids": "integer", "wins": "integer" }, ...
  ]
}

Back to Top

Additional Resources and Technical References

For those using Java, we highly recommend Apache HttpClient.

For those using PHP, we recommend referencing the following documentation: 
http://php.net/manual/en/features.http-auth.php

A pretty good treatment of Digest Access Authentication: 
http://en.wikipedia.org/wiki/Digest_access_authentication

Spring Security documentation. This is what our server uses and will be exactly what we expect: http://static.springsource.org/spring-security/site/docs/3.0.x/reference/springsecurity-single.html#digest-processing-filter

The RFC for Basic and Digest Access Authentication

For Microsoft users, references for Digest Access Authentication:
http://technet.microsoft.com/en-us/library/cc782794(v=ws.10).aspx

Back to Top

Have more questions? Submit a request