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.
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.
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
- Endpoint for aggregatable success debug reports:
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.
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
}
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.
- 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 typetrigger-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
)