Digital Platform API - Engagement Metrics report

The Engagement Metrics report provides information about ad viewability, as well as indicating any problems that might be preventing Xandr from measuring an impression's viewability. This report is only available for Xandr Publisher Adserver customers.

Time frame

All dates and times are given in UTC.

Time ranges

Time ranges define the time period of the data extracted for the report. The following is a complete list of time ranges available for reports. However, all time ranges are not available for every report.

• custom
• last_available_day
• today
• last_24_hours
• last_48_hours
• yesterday
• last_2_days
• last_7_days
• last_7_available_days
• last_14_days
• last_14_available_days
• last_30_days
• last_30_available_days
• last_month
• last_100_days
• last_365_days
• quarter_to_date
• month_to_date
• month_to_yesterday
• lifetime

Intervals

Intervals determine how your data is grouped together into rows in the report response. The following is a complete list of intervals available for reports. However, all intervals are not available for every report.

• Daily: Data is grouped into rows by the day.
• Monthly: Data is grouped into rows by the month.
• Cumulative: Data is grouped together in one figure, covering the entire selected time range.

Note

For more information about how quickly report data is processed, see Availability of Reporting Data.

Dimensions

Column	Type	Filter?	Description
buyer_member_id	int	Yes	The ID of the buying member of the impressions.
seller_member_id	int	Yes	The ID of the selling member.
buyer_member_name	string	No	The name of the buying member of the impressions.
seller_member_name	string	No	The name of the selling member.
advertiser_id	int	Yes	The ID of the advertiser object associated to the served impressions.
advertiser_name	string	No	The name of the advertiser object associated to the served impressions.
line_item_id	int	Yes	The ID of the line item under which the impressions were purchased. The buy-side hierarchy is Line Item > Campaign.
line_item_name	string	No	The name of the line item under which the impressions were purchased. The buy-side hierarchy is Line Item > Campaign.
campaign_id	int	Yes	The ID of the campaign that purchased the impressions.
campaign_name	string	No	The name of the campaign that purchased the impressions.
imp_type	int	Yes	The name of the impression type which was occurred.
imp_type_id	int	Yes	The ID of the impression type which was occurred.
insertion_order_id	int	Yes	The ID of the insertion order under which the impressions were purchased. The buy-side hierarchy is Insertion Order > Line Item > Campaign.
insertion_order_name	string	No	The name of the insertion order under which the impressiond were purchased. The buy-side hierarchy is Insertion Order > Line Item > Campaign.
publisher_id	int	Yes	The ID of the publisher object on which the the impressions were occurred.
publisher_name	string	No	The name of the publisher object on which the the impressions were occurred.
placement_id	int	Yes	The ID of the placement or the open slot on publisher website where the advertiser's creative with matching specifications was served.
placement_name	string	No	The name of the placement or the open slot on publisher website where the advertiser's creative with matching specifications was served.
member_id	int	Yes	The ID of the member for which report is generated.
creative_id	int	No	The ID of the creative served for the impression.
creative_name	string	No	The name of the creative served for the impression.
mediatype	string	No	The name of the media type associated with the creative that served on the impression.
media_type_id	int	Yes	The ID of the media type associated with the creative that served on the impression.
device_type	string	Yes	The type of device on which the impression was served. Possible values: - Desktops & Laptops - Tablets - Mobile Phones - TV - Game Consoles - Set Top Box - Media Players - Other Devices
day	date	Yes	The day of the auction.
operating_system_family_id	int	Yes	The ID of the operating system family associated with the device where the impression was served on.
operating_system_family_name	string	No	The name of the operating system family associated with the device where the impression was served on.
split_id	int	Yes	The ID of the split that purchased the impressions in this data set. Splits are only applicable to augmented line items. For any reports that contain campaigns, the split_id (if included) will be null.
split_name	string	No	The name of the split that purchased the impressions in this data set. Splits are only applicable to augmented line items. For any reports that contain campaigns, the split_id (if included) will be null.
campaign_group_type_id	int	Yes	The ID of the campiagn group of which the campaign that purchaed the impression is a part of.

Metrics

Note

When values of a metric are displayed as percentages in the UI, they will be displayed as decimals when you export the report.

Column	Type	Formula	Description
imps	int	imps	The total number of impressions (served and resold).
viewed_imps	int	viewed_imps	The number of measured impressions that were viewable according to the IAB Viewability definition, which states that an impression is viewable if 50% of the pixels are in view for 1 continuous second.
view_measurable_rate	double	view_measurable_imps/imps	The percentage of impressions measured for viewability out of the total number of impressions.
view_rate	double	viewed_imps/view_measurable_imps	The percentage of impressions that were viewable out of the total number of impressions measured for viewability.
viewed_imps	int	viewed_imps	The total number of impressions that were measured for viewability.
nvt_unknown_imps	int	nvt_unknown_imps	The number of impressions not viewed because of unknow reasons.
nmt_not_initialised_imps	int	nmt_not_initialised_imps	The number of impressions not measured because the measurement script did not initialize. This could occur for very short sessions when a user leaves a page before the other component (like the OS in mobile apps) can provide feedback on viewability.
nmt_unknown_imps	int	nmt_unknown_imps	The number of impressions not measured because of unknow reasons.
view_iab_duration	double	view_iab_duration	The average duration (in seconds) measured for which impressions met the IAB Viewability definition.
nvt_crea_not_loaded_imps	int	nvt_crea_not_loaded_imps	The number of impressions not viewed because the creative could not be loaded by the viewability script on the page. For example, this could occur if the div is being replaced or the creative isn't located within five seconds.
nvt_sdk_imps	int	nvt_sdk_imps	The number of impressions not viewed because in-app SDK responded with a not visible signal. For example, the Open Measurement Software Development Kit (OM SDK) reported the ad as non-viewable.
nvt_hidden_crea_imps	int	nvt_hidden_crea_imps	The number of impressions not viewed because the creative was explicitly hidden by CSS or HTML on the webpage. For more details, check your ads' recent style changes.
nvt_out_viewport_imps	int	nvt_out_viewport_imps	The number of impressions not viewed because the creative was outside the visible area of a webpage on a display device. Ensure that the creative is visible and not at the bottom of the page.
nvt_surface_imps	int	nvt_surface_imps	The number of impressions not viewed because the surface threshold based on IAB definition was not met.
nvt_duration_imps	int	nvt_duration_imps	The number of impressions not viewed because time threshold based on IAB definition was not met.
nmt_imp_type_imps	int	nmt_imp_type_imps	The number of impressions not measured because the impression type is not supported. Please visit the Viewability FAQ to learn about supported media types.
nmt_media_type_imps	int	nmt_media_type_imps	The number of impressions not measured because the media type is not supported. Please visit the Viewability FAQ to learn about supported media types.
nmt_supply_type_imps	int	nmt_supply_type_imps	The number of impressions not measured because the supply type is not supported. Please visit the Viewability FAQ to learn about supported supply types.
nmt_cross_domain_imps	int	nmt_cross_domain_imps	The number of impressions not measured because the creative cannot be measured because the ad was served in a cross-domain iframe and the browser was not supported. All modern browsers are supported but certain old versions may not be supported.
nmt_no_crea_imps	int	nmt_no_crea_imps	The number of impressions not measured because the creative could not be found by the viewability script on the page. For example, this could occur if the div is being replaced or the creative isn't located within five seconds.
nmt_sdk_imps	int	nmt_sdk_imps	The number of impressions not measured because the in-app SDK for the specific inventory is not supported. Please visit the Viewability FAQ to learn about supported in-app SDKs.
nmt_no_callback_imps	int	nmt_no_callback_imps	The number of impressions not measured because no callback was received from the measurement script. For example, this could occur if the script hasn't executed.
nmt_native_imps	int	nmt_native_imps	The number of impressions not measured because the specific type of native inventory is not supported.
nvt_hidden_browser_imps	int	nvt_hidden_browser_imps	The number of impressions not viewed because either the browser was not in focus, or the browser tab was hidden.
view_duration_gt_0pct	double	view_duration_gt_0pct	The average duration (in seconds) for which impressions displaying greater than 0% of the pixels in the creative remained in view.
view_duration_gt_25pct	double	view_duration_gt_25pct	The average duration (in seconds) for which impressions displaying greater than 25% of the pixels in the creative remained in view.
view_duration_gt_25pct	double	view_duration_gt_25pct	The average duration (in seconds) for which impressions displaying greater than 50% of the pixels in the creative remained in view.
view_duration_gt_75pct	double	view_duration_gt_75pct	The average duration (in seconds) for which impressions displaying greater than 75% of the pixels in the creative remained in view.
view_duration_eq_100pct	double	view_duration_eq_100pct	The average duration (in seconds) for which impressions displaying 100% of the pixels in the creative remained in view.

Example

Create a JSON-formatted report request

The JSON file should include the report_type of "engagement_metrics_network", as well as the columns (dimensions and metrics) and report_interval that you want to retrieve. You can also filter for specific dimensions, define granularity (year, month, day), and specify the format in which the data should be returned ("csv", "excel", or "html"). For a full explanation of fields that can be included in the JSON file, see the Report Service.

$ cat engagement_metrics_network
  {
    "report":
    {
        "report_type":"engagement_metrics_network",
        "columns":[
            "advertiser_id",
            "insertion_order_id",
            "creative_id",
            "device_type",
            "imps",
            "view_iab_duration  ",
            "view_rate"
        ],
        "report_interval":"last_7_days",
        "format":"csv"
    }
}

POST the request to the reporting service

$ curl -b cookies -X POST -d @engagement_metrics_network 'https://api.appnexus.com/report'
{
   "response":{
      "status":"OK",
      "report_id":"097f59fc3ab7d02c5d60db42081d9b69"
   }
}

GET the report status from the report service

Make a GET call with the Report ID to retrieve the status of the report. Continue making this GET call until the execution_status is "ready". Then use the report-download service to save the report data to a file, as described in the next step.

$ curl -b cookies 'https://api.appnexus.com/report?id=097f59fc3ab7d02c5d60db42081d9b69'
{
   "response":{
      "status":"OK",
      "report":{
         "name":null,
         "created_on":"2010-05-25 19:19:53",
         "json_request":"{\"report\":{\"report_type\":\"engagement_metrics_network\",\"columns\":[\"advertiser_id\",
            \"insertion_order_id\",\"creative_id\",\"device_type\",\"imps\",\"view_iab_duration\",\"view_rate\"],
            \"report_interval\":\"last_7_days\"}}",
         "url": "report-download?id=b97897a7864dd8f34e7457226c7af592"
      },
      "execution_status":"ready"
   }
}

GET the report data from the report download service

To download the report data to a file, make another GET call with the Report ID, but this time to the report-download service. You can find the service and Report ID in the url field of the previous GET response. When identifying the file that you want to save to, be sure to use the file extension of the "format" that you specified in your initial POST.

Note

If an error occurs during download, the response header will include an HTTP error code and message. Use -i or -v in your call to expose the response header.

$ curl -b cookies 'https://api.appnexus.com/report-download?id=b97897a7864dd8f34e7457226c7af592' > /tmp/engagement_metrics_network.csv

Note

There is a limit of 100,000 rows per report when you download them as XLSX and Excel file.