Monitoring Performance for Buyers

The ONE by AOL: Mobile interface provides the tools, technology and insight that will help you understand current performance, adapt to market changes and grow your revenue.

Using the Buyer Interface

Reports - To access all reporting features select Reports from the left nav bar. Reports may be your homepage. Reporting is also available via API.

RTB Configuration - View and edit your RTB Configuration.

Bidder Configuration - allows you to change an endpoint and enter an optional Win Notice URL.

Traffic Filters

This section gives you control over volume and types of auctions.

Country and Country Groups Filters

This section allows you to Whitelist or Block Countries or groups of countries as well asset a max QPS.
Example: Mexico, Canada and USA are whitelisted, USA traffic is set to a max QPS of 4000 and the group Mexico/Canada is set to a max QPS of 3000. New "Country Groups" can be added using the "+ New Country Group" button. "Country Groups" can be removed using the trash icon to the right of each group. Countries can only be in one Country Group.

Content Categories Filter

IAB Tier 1 Content Categories can be whitelisted or blocked.

ONE by AOL: Mobile 3rd Party Data Solutions

If you contract with any of the 3rd party data providers currently integrated into the Marketplace they will be visible here.

Publisher and Sites Filter

Publishers and Sites can be whitelisted or blocked in this section. Please submit a request if you have any questions about filtering.

 

Bidder Performance Reporting

The Bidder Performance report is available to all bidders. Please note that two optional reports (CPI Conversions and RTB Subscription Data Usage) are discussed in separate documentation.

The Bidder Performance Report present:

  • A consolidated view of bidder performance across all sites and seats
  • Performance data is available through the current day
  • Ability to drill down by Site, Seat, Hourly, Daily, Weekly, Monthly

Two other optional reports (CPI Conversions and RTB Subscription Data Usage) are discussed in separate documentation.

How to Run Reports

First, select a report.

Then select a preset date ranges or create a custom range.

Click OK to run the report. Re-run the report as needed by clicking the OK button.

Example Report

Note the two main sections of the report: Summary Data only appears after drilling down) and the Detailed Data.

Customize your reports by selecting which columns are displayed from the columns dropdown.

Drilling Down

To drill-down, double-click on the row you want to analyze (you can also select a row and use the "Add Dimension" button to drilldown). Then select the dimension you would like to drill-down into. In this report, the drill-down options are Site, Seat, and four Time options.

Select the dimension and the report will refresh with data broken down by the selected dimension.

Further sorting of data is accomplished by adding another drill-down dimension. However, Drilling into a "Time" dimension will eliminate the ability to drill down any further. If you choose to drill down into a "Time" dimension, it should be your last step in the drill down.

Rolling Up

You can back out of any drill down. To do this, close the dimension you'd like to remove by clicking the "x" button. The screen will refresh with your rolled up data.

Sorting Data

Columns are clickable and this action causes the entire report to be resorted by the field you've clicked on. Drag and Drop report columns and features to present data in the format most useful to you.

Exporting Report Data

Any ONE by AOL: Mobile report can be exported as an Excel file or CSV file. To export your data, run your report, drill-down to the data you want to save, and then select Export from the Actions menu.

Data can be copied directly from the report by clicking the copy icon at the bottom of each report.

Running Multiple Reports

Every time you run a report a new report widget is created and will exist until you choose to close it using the x button in the header of the report widget. Reports can be collapsed using the collapse icon.

 

Refreshing Reports

Reports can be refreshed using the refresh button.

 

Refreshing a report, maintains any drilldowns already applied. For example, if you ran a report a week ago using the "This Week" date range, then refreshed the report today, the report will refresh with data for the current week.

Data Dictionary

Some data in the Bidder Performance Report is not available after drilling down by Seat because Seat data only applies to actual bid performance data.

<tdNet Cost/Ads Delivered x 1000
Column Name Pre-Drill Down by Seat Post-Drill Down by Seat
Bid Requests bid requests sent to a bidder n/a
Bid Responses bid responses received with at least one valid bid n/a
Bid Rate Bid Responses/Bid Requests x100% n/a
Bids The total number of seat bids submitted in the bidder's bid responses The number of bids submitted by this bidder on behalf of this seat
Bids Won The number of auctions the bidder won The number of auctions the bidder-seat won
Win Rate Bids Won/Bid Responses x 100% Bids Won/Bids x 100%
Insufficient Bids Number of bids that were below the site's reserve price Number of bids that were below the site's reserve price
Response Timeouts The number of bid requests that resulted in timeout and thus were considered no-bids. Communication failures are not counted as timeouts. n/a
Response Timeout Rate Response Timeouts/Bid Requests x 100% n/a
Win Notice Timeouts The number of win notice URL calls that resulted in timeout. Once a winning bidder is selected, we send a win notification to the URL provided by the bidder. For bidders who pass markup upon receiving this win notification (as opposed to those who pass markup in the bid response), this timeout will result in forfeits. The number of win notice URL calls that resulted in timeout. Once a winning bidder is selected, we send a win notification to the URL provided by the bidder. For bidders who pass markup upon receiving this win notification (as opposed to those who pass markup in the bid response), this timeout will result in forfeits.
Win Notice Timeout Rate Win Notice Timeouts/Bids Won x 100% Win Notice Timeouts/Bids Won x 100%
Forfeits The number of auctions that would have been won (i.e., highest bids) that were then lost due to failure to deliver markup or ad quality rejection. The number of auctions that would have been won (i.e., highest bids) that were then lost due to failure to deliver markup or ad quality rejection.
Ads Delivered The number of ads confirmed delivered to the device (e.g., via tracking pixel, SDK report). The number of ads confirmed delivered to the device (e.g., via tracking pixel, SDK report).
Gross Wins The sum of all settlement prices in USD CPM The sum of all settlement prices in USD CPM
Avg Clearing Price Gross Wins/Bids Won x 1000 Gross Wins/Bids Won x 1000
Spend The actual spend by the bidder in USD for all ads delivered The actual spend by the seat in USD for all ads delivered
eCPM Net Cost/Ads Delivered x 1000

Using the Reporting API

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 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="<response realm>",
                        qop="<response qop>",
                        nonce="<single use server nonce>"

3.  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="<Company Access Key>",
            response="<MD5 Checksum>",
            realm="<realm from header response>",
            nonce="<server nonce from header response>",
            uri="/<company id>/test",
            qop=<qop from header response>,
            cnonce="<client specified string>",
            nc=<hexadecimal nonce count, increment each request>

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

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

Report Specifications

API Request Structure

The general request structure is:

Base URL
https://reports.nexage.com/access/<CompanyID>/reports/<reportID>?<params>
  • 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

 

Here's an example of a Bidder Performance Report request:

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

 

The JSON format of the response is shown below:

Example Reporting API Response
{
  "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

 

Here's an example of a CPI Conversion report request:

Example API Request
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

 

The JSON format of the response is shown below:

Example Reporting API Response
[
  {
    "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

 

Here's an example of a Subscription Data Usage report request:

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

 

The JSON format of the response is shown below:

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

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

Have more questions? Submit a request