Set up debug reports for Attribution Reporting

Part 2 of 3 on debugging Attribution Reporting. Set up your debug reports.

Glossary

The reporting origin is the origin that sets the Attribution Reporting source and trigger headers. All reports generated by the browser are sent to this origin. In this guidance, we use https://adtech.example as the example reporting origin.
An attribution report (report for short) is the final report (event-level or aggregatable) that contains the measurement data you've requested.
A debug report contains additional data about an attribution report, or about a source or trigger event. Receiving a debug report does not necessarily mean that something is working incorrectly! There are two types of debug reports
A transitional debug report is a debug report that requires a cookie to be set in order to be generated and sent. Transitional debug reports will be unavailable if a cookie is not set, and once third-party cookies are deprecated. All debug reports described in this guide are transitional debug reports.
Success debug reports track successful generation of an attribution report. They relate directly to an attribution report. Success debug reports have been available since Chrome 101 (April 2022).
Verbose debug reports can track missing reports and help you determine why they're missing. They indicate cases where the browser did not record a source or trigger event, (which means it will not generate an attribution report), and cases where an attribution report can't be generated or sent for some reason. Verbose debug reports include a type field that describes the reason why a source event, trigger event or attribution report was not generated. Verbose debug reports are available starting in Chrome 109 (Stable in January 2023).
Debug keys are unique identifiers you can set on both the source side and the trigger side. Debug keys enable you to map cookie-based conversions and attribution-based conversions. When you've set up your system to generate debug reports and set debug keys, the browser will include these debug keys in all attribution reports and debug reports.

For more concepts and key terms used throughout our documentation, refer to the Privacy Sandbox glossary.

Implementation questions?

If you encounter any issue while setting up debug reports, create an issue on our developer support repository and we'll help you troubleshoot.

Prepare to set up debug reports

Before you set up debug reports, follow these steps:

Check that you've applied best practices for API integration

Check that your code is gated behind feature detection. To be sure the API is not blocked by Permissions-Policy, run the following code:
```
if (document.featurePolicy.allowsFeature('attribution-reporting')) {
// the Attribution Reporting API is enabled
}
```
If this feature detection check returns true, the API is allowed in the context (page) where the check is run.
(Not required during the testing phase: Check that you've set a Permissions-Policy)

Fix fundamental integration issues

While debug reports are useful to help you detect and analyze loss at scale, some integration issues can be detected locally. Source and trigger header misconfiguration issues, JSON parsing issues, insecure context (non-HTTPS), and other issues that prevent the API from functioning will be surfaced in the DevTools Issues tab.

DevTools issues can be of different types. If you encounter an invalid header issue, copy the header into the header validator tool. This will help you identify and fix the field that's causing an issue.

Validate Attribution Reporting Headers

You can use the header validator to validate headers related to the Attribution Reporting API. You can monitor validation errors originating from the browser to facilitate API debugging.

To opt in to receiving debugging reports, respond with the report-header-errors as part of the Attribution-Reporting-Info response header.

Attribution-Reporting-Info: report-header-errors

Note that Attribution-Reporting-Info is a dictionary structured headerAttribution-Reporting-Info, so providing the boolean report-header-errors key implies a true value.

Debugging reports are sent immediately to the reporting endpoint:

https://<reporting origin>/.well-known/attribution-reporting/debug/verbose

Report data is included in the request body as a JSON list of objects having this form:

[{
  "type": "header-parsing-error",
  "body": {
    "context_site": "https://source.example",
    "header": "Attribution-Reporting-Register-Source",
    "value": "!!!", // header value received in the response
    "error": "invalid JSON" // optional error details that may vary across browsers or different versions of the same browser
  }
}]

Set up debug reports: steps common to success reports and verbose reports

Set the following cookie on the reporting origin:

Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly

The browser will check for the presence of this cookie on both source and trigger registration. The success debug report will only be generated if the cookie is present at both times.

Demo code: debug cookie

Note that debug reports can be enabled for browsers in Mode B, where third-party cookies are disabled to facilitate testing and preparation for third-party cookie deprecation. For browsers in Mode B, you don't need to set the debug cookie to enable debug reports. Skip to step 2 to set up debug keys for success debug reports.

Step 2: Set debug keys

Each debug key must be a 64-bit unsigned integer formatted as a base-10 string. Make each debug key a unique ID. The success debug report will only be generated if the debug keys are set.

Map the source-side debug key to additional source-time information you think is relevant for you to debug.
Map the trigger-side debug key to additional trigger-time information you think is relevant for you to debug.

You could for example set the following debug keys:

Cookie ID + Source timestamp as a source debug key (and capture that same timestamp in your cookie-based system)
Cookie ID + Trigger timestamp as a trigger debug key (and capture that same timestamp in your cookie-based system)

With this, you can use cookie-based conversion information to look up the corresponding debug reports or attribution reports. Learn more in Part 3: Cookbook.

Make the source-side debug key different from source_event_id, so that you can differentiate individual reports that have the same source event ID.

Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"647775351539539"
}

Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743"
}

Demo code: source debug key Demo code: trigger debug key

Set up success debug reports

The example code in this section generates success debug reports for both event-level and aggregatable reports. Event-level and aggregatable reports use the same debug keys.

Step 3: Set up an endpoint to collect success debug reports

Set up an endpoint to collect the debug reports. This endpoint should be similar to the main attribution endpoint, with an additional debug string in the path:

Endpoint for event-level success debug reports: https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- Endpoint for aggregatable success debug reports: https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution

When an attribution is triggered, the browser will immediately send a debug report via a POST request to this endpoint. Your server code to handle incoming success debug reports may look as follows (here on a node endpoint):

// Handle incoming event-Level Success Debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/report-event-attribution',
  async (req, res) => {
    // Debug report is in req.body
    res.sendStatus(200);
  }
);

// Handle incoming aggregatable Success Debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/report-aggregate-attribution',
  async (req, res) => {
    // Debug report is in req.body
    res.sendStatus(200);
  }
);

Demo code: event-level debug reports endpoint

Demo code: aggregatable debug reports endpoint

Step 4: Confirm your setup will generate success debug reports

Open chrome://attribution-internals in your browser.
Make sure that the Show Debug Reports checkbox is checked, in both the Event-Level Reports and the Aggregatable Reports tabs.
Open the sites on which you've implemented Attribution Reporting. Complete the steps you use to generate attribution reports; these same steps will generate success debug reports.
In chrome://attribution-internals:
- Check that attribution reports are correctly generated.
- In the Event-Level Reports tab and the Aggregatable Reports tab, check that the success debug reports are generated too. Recognize them in the list with their blue debug path.

On your server, verify that your endpoint immediately receives these success debug reports. Make sure to check for both event-level and aggregatable success debug reports.

Screenshot: reporting origin server logs

Step 5: Observe success debug reports

A success debug report is identical to an attribution report, and contains both the source-side and the trigger-side debug keys.

{
  "attribution_destination": "https://advertiser.example",
  "randomized_trigger_rate": 0.0000025,
  "report_id": "7d76ef29-d59e-4954-9fff-d97a743b4715",
  "source_debug_key": "647775351539539",
  "source_event_id": "760938763735530",
  "source_type": "event",
  "trigger_data": "0",
  "trigger_debug_key": "156477391437535"
}

{
  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgqJldmFsdWVEAACAAGZidWNrZXRQPPhnkD+7c+wm1RjAlowp3KJldmFsdWVEAAARMGZidWNrZXRQJFJl9DLxbnMm1RjAlowp3GlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "d5f32b96-abd5-4ee5-ae23-26490d834012",
      "payload": "0s9mYVIuznK4WRV/t7uHKquHPYCpAN9mZHsUGNiYd2G/9cg87Y0IjlmZkEtiJghMT7rmg3GtWVPWTJU5MvtScK3HK3qR2W8CVDmKRAhqqlz1kPZfdGUB4NsXGyVCy2UWapklE/r7pmRDDP48b4sQTyDMFExQGUTE56M/8WFVQ0qkc7UMoLI/uwh2KeIweQCEKTzw"
    }
  ],
  "shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"debug_mode\":\"enabled\",\"report_id\":\"4a04f0ff-91e7-4ef6-9fcc-07d000c20495\",\"reporting_origin\":\"https://adtech.example\",\"scheduled_report_time\":\"1669888617\",\"source_registration_time\":\"1669852800\",\"version\":\"0.1\"}",
  "source_debug_key": "647775351539539",
  "trigger_debug_key": "156477391437535"
}

Set up verbose debug reports

Step 3: Opt into verbose debugging in the source and trigger headers

Set debug_reporting to true in both Attribution-Reporting-Register-Source and Attribution-Reporting-Register-Trigger.

Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}

Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}

Demo code: source header

Demo code: trigger header

Step 4: Set up an endpoint to collect verbose debug reports

Set up an endpoint to collect the debug reports. This endpoint should be similar to the main attribution endpoint, with an additional debug/verbose string in the path:

https://adtech.example/.well-known/attribution-reporting/debug/verbose

When verbose debug reports are generated, that is when a source or trigger isn't registered, the browser will immediately send a verbose debug report via a POST request to this endpoint. Your server code to handle incoming verbose debug reports may look as follows (here on a node endpoint):

// Handle incoming verbose debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/verbose',
  async (req, res) => {
    // List of verbose debug reports is in req.body
    res.sendStatus(200);
  }
);

Unlike success debug reports, there's only one endpoint for verbose reports. Verbose reports that relate to event-level and aggregated reports will all be sent to the same endpoint.

Demo code: verbose debug reports endpoint

Step 5: Confirm your setup will generate verbose debug reports

While there are numerous types of verbose debug reports, it's sufficient to check your verbose debugging setup with only one type of verbose debug report. If this one type of verbose debug report is correctly generated and received, this means that all types of verbose debug reports will be correctly generated and received as well, because all verbose debug reports use the same configuration and are sent to the same endpoint.

Key point: Pick a verbose debug report that's simple to test for. trigger-no-matching-source is a good candidate, because you can generate it by converting. Verbose reports that relate to trigger events tend to be better candidates; verbose report types that relates to source events are more tedious to purposefully generate.

Open chrome://attribution-internals in your browser.
Trigger an attribution (convert) on your site that's set up with Attribution Reporting. Given that there was no ad engagement (impression or click) before this conversion, you should expect a verbose debug report of type trigger-no-matching-source will be generated.
In chrome://attribution-internals, open the Verbose debug reports tab and check that a verbose debug report of type trigger-no-matching-source has been generated.
On your server, verify that your endpoint has immediately received this verbose debug report.

Step 6: Observe verbose debug reports

Verbose debug reports generated at trigger time include both the source-side and the trigger-side debug key (if there is a matching source for the trigger). Verbose debug reports generated at source time include the source-side debug key.

Example of a request containing verbose debugs reports, sent by the browser:

[
  {
    "body": {
      "attribution_destination": "http://arapi-advertiser.localhost",
      "randomized_trigger_rate": 0.0000025,
      "report_id": "92b7f4fd-b157-4925-999e-aad6361de759",
      "source_debug_key": "282273499788483",
      "source_event_id": "480041649210491",
      "source_type": "event",
      "trigger_data": "1",
      "trigger_debug_key": "282273499788483"
    },
    "type": "trigger-event-low-priority"
  },
  {
    "body": {
      "attribution_destination": "http://arapi-advertiser.localhost",
      "limit": "65536",
      "source_debug_key": "282273499788483",
      "source_event_id": "480041649210491",
      "source_site": "http://arapi-publisher.localhost",
      "trigger_debug_key": "282273499788483"
    },
    "type": "trigger-aggregate-insufficient-budget"
  }
]

Each verbose report contains the following fields:

Type: What caused the report to be generated. To learn about all verbose report types and what action to take depending on each type, review the verbose reports reference in Part 3: Debugging cookbook.
Body: The report's body. It will depend on its type. Review the verbose reports reference in Part 3: Debugging cookbook.

A request's body will contain at least one, and at most two verbose reports:

One verbose report if the failure only affects event-level reports (or if it only affects aggregatable reports). A source or trigger registration failure has only one reason; hence one verbose report can be generated per failure and per report type (event-level or aggregatable).
Two verbose reports if the failure affects both event-level and aggregatable reports—with an exception: if the failure reason is the same for event-level and aggregatable reports, only one verbose report is generated (example: trigger-no-matching-source)

Up next

Part 3: Debugging cookbook