Set up debug reports

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

Published on

This article is part of a series on debugging the Attribution Reporting API. This series covers client-side debugging for event-level reports and aggregatable reports. Server-side debugging guidance for summary reports is available here. A handbook for API integration is available here.

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

Gotchas

Permissions-Policy requirements have been relaxed for testing, but a publisher or advertiser can still decide to explicitly disable the Attribution Reporting API via Permissions-Policy. In this case, no source nor trigger can be recorded (and hence no report can be generated or sent).

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.

These issues will not generate verbose debug reports, because they cause the API not to function. Only the absence of success debug reports indicates that you may be encountering some of these issues. Learn more in Part 3: Debugging cookbook.

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.

Screenshot: header validation tool

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

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.

  • 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

In the demo code, we give both debug keys the value of the legacy measurement third-party cookie. In a real system, you would make each key a unique ID, and map it to additional source-time information that you deem useful for debugging, as suggested in the example debug keys above.

Set up success debug reports

Try the demo to generate and preview success debug reports in your browser. Review the corresponding code.

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.
Screenshot: Attribution internals
  • 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

Try the demo to generate and preview verbose debug reports in your browser. Review the corresponding code.

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.

Gotchas

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

  1. Open chrome://attribution-internals in your browser.
  2. 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.
  3. 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.
  4. 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"
}
]
Gotchas

Unlike a success debug request, a verbose debug request contains a list (array) of verbose report(s) in its body.

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

Updated on Improve article

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.