Digital Platform API - Seller CMP Analytics report

The Seller CMP (Consent Management Platform) Analytics Report provides insight into the number, validity, and content of the IAB Transparency & Consent Framework (IAB TCF) strings on seller ad requests to our endpoints. This report enables sellers to answer questions like:

• How many ad requests contained TCF strings encoded according to the TCF V1 and V2 specifications?
• How many ad requests contained TCF strings that were not encoded properly and therefore invalid or malformed?
• Is my CMP (Consent Management Platform) correctly passing permission information?

Overview

This report does not prove or disprove compliance with any laws or regulations. The language "GDPR applied" for this report means applied TCF logic. We support the IAB TCF and this report enables sellers using the TCF to confirm that TCF signals are communicated properly.

For instructions on retrieving a report, see Report Service or the example below.

Sellers wishing to have all of their ad requests treated according to the IAB TCF standards and policies can force application of TCF logic by passing 'gdpr=1' according to the IAB OpenRTB Spec. If the GDPR parameter is omitted but the request includes a TCF string according to the IAB OpenRTB specification, the auction will also apply TCF logic.

A high number of present but malformed strings for a given publisher usually means that the publisher's CMP is not creating or encoding the strings according to TCF specifications, and therefore are unreadable to vendors. Unreadable strings, because they do not provide clear signals to vendors, are treated as no permission for any vendor, and should be avoided.

For more information about the IAB TCF, refer to the following resources:

• IAB Europe's TCF Policies
• IAB Europe's TCF Governance
• IAB Techlab TCF v1 and v2 Technical Spec & Implementation Guides
• IAB Techlab TCF RTB Spec

Time frame

The report_interval field in the JSON request can be set to one of the following:

• custom
• last_7_days
• month_to_date
• last_30_days

Data retention period

Data retention period for this report is 30 days.

Dimensions

Metrics

Example

Create a JSON report request

The JSON file should include the report_type of "cmp_analytics", 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 (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 cmp_analytics

{"report":
    {
        "report_type":"cmp_analytics",
        "columns":[
            "day",
            "seller_member_id",
            "call_type",
            "url",
            "ad_requests_gdpr_country",
            "ad_requests_gdpr_applied_valid_consent_string",
            "ad_requests_gdpr_applied_blank_consent_string",
            "ad_requests_gdpr_applied_valid_consent_string_tcf_version_2",
            "pct_ad_requests_gdpr_country_gdpr_applied",
            "pct_ad_requests_gdpr_applied_valid_consent_string",
            "pct_ad_requests_gdpr_applied_blank_consent_string",
            "pct_ad_requests_gdpr_applied_valid_consent_string_tcf_version_2",
        ],
        "report_interval":"last_7_days",
        "format":"csv"
    }
}

POST a request to the Report Service

POST the JSON request to get back a report ID.

$ curl -b cookies -X post -d @cmp_analytics "https://api.appnexus.com/report?seller_member_id=123"

{
   "response":{
      "status":"OK",
      "report_id":"09b6979a6a4c3805bdac8921378d3622"
   }
}

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=09b6979a6a4c3805bdac8921378d3622'

{
   "response":{
      "status":"OK",
      "report":{
         "name":null,
         "created_on":"2016-12-11 19:15:48",
         "json_request": "{\"report\":{\"report_type\":\"cmp_analytics\",
             \"columns\":[\"day\",\"seller_member_id\",
             \"call_type\",\"url\",\"ad_requests_gdpr_country\",\"ad_requests_gdpr_applied_valid_consent_string\",\"ad_requests_gdpr_applied_blank_consent_string\",
             \"ad_requests_gdpr_applied_valid_consent_string_tcf_version_2\",\"pct_ad_requests_gdpr_country_gdpr_applied\",
             \"pct_ad_requests_gdpr_applied_valid_consent_string\",\"pct_ad_requests_gdpr_applied_blank_consent_string\",
             \"pct_ad_requests_gdpr_applied_valid_consent_string_tcf_version_2\"],
             \"report_interval\":\"last_7_days\",\"format\":\"csv\",\"filters\":[{\"seller_member_id\":\"123\"}]}}",
             "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 response to your previous GET call. When identifying the file that you want to save to, be sure to use the file extension of the file format that you specified in your initial POST.

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