Get started with attribution reporting

This guide provides an overview and setup instructions for both event-level and summary attribution reports using the Attribution Reporting API.

To begin, you will learn to:

  • Differentiate between Attribution Reporting API report types

  • Complete API implementation and report generation steps

  • Find reference and troubleshooting information

Choose a report type

To effectively measure ad campaign performance with varying levels of detail and privacy, the Attribution Reporting API provides two distinct report types:

  • Event-level reports: Provide granular data linking a specific ad click or view (the source) with corresponding conversion data (the trigger). Event-level reports limit the amount of conversion data and add noise to reports. They are ideal for use cases where individual event attribution is key, such as measuring campaign reach.

  • Summary reports: Offer aggregated user data and can include more detailed conversion information with added noise. Using both the Attribution Reporting API and Private Aggregation API, they are constructed from aggregate reports and offer a richer data model than event-level reports. Summary reports are particularly useful for scenarios requiring aggregated insights, such as calculating conversion values or analyzing campaign performance across user segments.

Implementation overview

The following sections outline the high-level steps for generating each type of report. You can also follow along with the Attribution Reporting API Demo for a step-by-step walkthrough of the entire process.

Prerequisite: Your sites must have SSL/TLS certificates (HTTPS) before you can register sources, triggers, and receive reports.

Event-level report generation

The following steps describe how to generate event-level reports:

  1. Register a source: Associates an ad click or view with attribution information. See Register attribution sources and Attribution source registration for detailed instructions. Note that the registration process differs slightly for clicks and views.

  2. Register a trigger: Records a conversion event and links it to a previously registered source. Refer to Register attribution triggers for instructions.

  3. Set up a reporting endpoint: Create an endpoint on your server to receive event-level reports. The endpoint URL should follow this format: {REPORTING_ENDPOINT}/.well-known/attribution-reporting/report-event-attribution. See the example code in adtech.js for an example of the POST method. For more information on .well-known, see Wikipedia.

For a deeper dive into event-level reports, see the Event-level report explainer.

Summary report generation

  1. Register a source: Same as for event-level reports. See Register attribution sources and Attribution source registration for details.

  2. Register a trigger: Same as for event-level reports. See Register attribution triggers.

  3. Set up a reporting endpoint: Create an endpoint to receive aggregate reports. The URL should be: {REPORTING_ENDPOINT}/.well-known/attribution-reporting/report-aggregate-attribution. See adtech.js for a POST method example and Wikipedia for .well-known information.

  4. Batch and send reports: Batch the aggregate reports and send them to the Aggregation Service for processing. The Aggregation Service will then generate summary reports. See Strategies for batching for more information.

For a deeper dive into summary reports, refer to the Aggregatable report explainer.

In addition to the implementation steps, the following topics will help you plan your summary reporting strategy:

Set up filters (optional)

To gain more granular control over the attribution data you receive, you can set up filters.

Filtering provides refined data analysis that isolates specific subsets of data for your analysis, reducing noise. It also helps track the performance of specific ad campaigns and conversion events for more precise measurement.

To set up filtering see Define custom rules using filters and the triggers section of the Attribution trigger registration for details specific to aggregatable reports.

Confirm the API is enabled

Before using the API, check if it's enabled using the following code:

if (document.featurePolicy.allowsFeature('attribution-reporting')) {
  // the Attribution Reporting API is enabled
}

This check indicates if the API is allowed in the current context. However, user browser settings or other factors might still prevent the API from being used. Due to privacy considerations, there's no programmatic way to definitively confirm API usability.

Next steps

The following sections provide further information on getting started attribution reporting.

Implementation

Background and concepts

Demos and tools

Planning