Monitoring Performance for Buyers

ONE by AOL: Mobile takes pride in bringing you the best and most reliable technology. We deeply believe that how technology performs is critical to accelerating and growing your mobile advertising business. Technology should deliver strategic advantage to you, giving you more opportunity to focus attention on growing your business versus making the technology work.

The ONE by AOL: Mobile UI gives you the insights and tools needed to control and tune your mobile advertising business, so that you understand current performance and can continuously adapt to changing realities. 

Quicklinks

Using the ONE by AOL: Mobile Interface

Reports

Select "Reports" to access all ONE by AOL: Mobile reporting functionality. "Reports" is also your homepage. A detailed description can be found in the Bidder Reports section below.

Note: Reporting is also available via API. Please contact your Demand Services Manager for details.

Ad Verification

As part of our comprehensive brand safety solution, our ad verification process proactively classifies each creative per IAB Level-2 content categories to ensure publishers have control over the creative served on their sites and apps. A detailed description of bidder ad verification functionality can be found in Creative Verification.

RTB Configuration

This is where you can view and edit your ONE by AOL: Mobile RTB Configuration. There are two main sections within RTB Configuration:

Bidder Configuration

This section allows you to change your endpoint and enter an optional Win Notice URL.

Traffic Filters

This section gives you control over volume and types of auctions you'd like to see:

Country and Country Groups Filters

The following section allows you to Whitelist or Block Countries. In addition, QPS can be set for groups of Countries. In the following example, Mexico, Canada and USA are whitelisted. In addition, USA traffic is set to a max QPS or 4000 and the group of Mexico and 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 also be whitelisted or blocked:

ONE by AOL: Mobile 3rd Party Data Solutions

If you contract with any of the following 3rd party data providers currently integrated into the Exchange they will be visible to you. Talk to your Demand Services Manager for details. These cannot be edited, except by your Demand Services Manger:

Publisher and Sites Filter

Finally, Publishers and Sites can be whitelisted or blocked:

Please contact your Demand Services Manager with any questions.

Bidder Reporting

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

Report Name

Report Description

Bidder Performance

  • Presents 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

Running Reports

The first step is to select a report:

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

After selecting a Date Range and clicking OK, your report will be run. You can always re-run the report by clicking the OK button.

Report View

This is an example of a ONE by AOL: Mobile report. Note the two main sections of the report: Summary Data and the Detailed Data. (Summary Data section only appears after drilling down)

Note that you can choose the Columns to display in your report using the "Columns" button.

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). You can 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.

If Site is selected, the report will refresh and the data will be broken down by Site.

You can now drill-down further into another dimension.

Note on "Time" Dimension: 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

Each field/column can be clicked on. This sorts the entire report by the field you've clicked on.

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 also 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. This report will exist until you choose to close it using the x button in the header of the report widget: 

Reports can also be collapsed using the collapse icon: 

Reports can be ordered in whatever way you'd like using drag and drop. Just grab the handle in the report header to reorder your reports: 

Refreshing Reports

Reports can be refreshed using the refresh button:

Clicking this button will refresh the data in the report, maintaining any drilldowns you 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 would refresh with data for the current week.

 

Data Dictionary

Some data in the Bidder Performance report is not available after drilling down by Seat. This is because Seat data only makes sense in regard to actual bid performance data.

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, ONE by AOL: Mobile sends 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, ONE by AOL: Mobile sends 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

Net Cost/Ads Delivered x 1000

Using the Reporting API

 

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”: your ONE by AOL: Mobile password used for Authorization.

Contact your ONE by AOL: Mobile Demand Services Manager if you don’t know these values.

Design

The ONE by AOL: Mobile Marketplace Reporting API is designed to provide access to all of your data currently available in the ONE by AOL: Mobile UI. The API is RESTful, with JSON object return and digest-based authentication. See below for detailed Authentication, Authorization and Report specifications.

API Security

The ONE by AOL: Mobile Marketplace Reporting API uses Digest Access Authentication.

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

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

The following instructions are a step-by-step guide if not using a library to handle the authentication piece.

Follow these steps to gain access to the API:

  1. Make a request using https://reports.nexage.com/access/<CompanyID>/test. No credentials are needed at this point.
  2. You should 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:
    1. Domain – Assume the protection space consists of all URIs on the responding server
    2. Opaque – Ignore and client doesn't have to include this directive in any of subsequent requests
    3. 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

    1. Username: Company Access Key.
    2. Response: the combined MD5 checksum of the following parameters:
      1. HA1: The MD5 hash of the combined username (Company Access Key), realm and password (Secret Key)
      2. Server nonce
      3. Request counter
      4. Client nonce (Client generated)
      5. QOP code
      6. HA2: The MD5 hash of the combined method (e.g. GET) and digest URI (e.g. "/<company id>/test")
    3. Realm
    4. Nonce
    5. URI: from Request-URI of the Request-Line. Duplicated here because proxies are allowed to change the Request-Line in transit
    6. QOP code: This should be set to one of the values returned in the WWW-Authenticate header
    7. Client Nonce: an opaque quoted string value provided by the client
    8. 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:

    1. "200 OK" if Authentication was successful
    2. “401 Unauthorized” if Authorization or Authentication failed
    3. "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 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" is the name of the specific report to be retrieved. See below for details.
  • "params" are 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, 2012 would be represented as "2012-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 2012 would be "2012-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. 

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

Technical References

For those using Java, we highly recommend Apache HttpClient.  Here is the link to the project: 
http://hc.apache.org/httpcomponents-client-ga/

„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 mainly for setting up the server-side, but 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 actual RFC for Basic and Digest Access Authentication, for those suffering from acute insomnia: 
http://www.ietf.org/rfc/rfc2617.txt

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