Attribution Reporting API JavaScript Guide

The Attribution Reporting API is a Privacy Sandbox mechanism that allows developers and advertisers to measure ad conversions without relying on third-party cookies or cross-site tracking identifiers. By shifting the correlation of ad clicks or views with subsequent purchases or sign-ups directly into the browser, the API provides conversion measurement while safeguarding user privacy through data limiting, noise addition, and report delays.

Registering Attribution Sources

Measurement begins when a user interacts with an ad. This interaction—an impression or a click—is known as an attribution source. Developers can register an attribution source in JavaScript using the attributionsrc property with the fetch() API or standard HTML elements.

// Registering a click source via JavaScript Fetch
fetch("https://ad-tech.example/register-source", {
  attributionReporting: {
    eventSourceEligible: false,
    triggerEligible: false,
  },
  headers: {
    "Attribution-Reporting-Eligible": "navigation-source"
  }
});

Alternatively, it can be attached to anchor tags or image elements:

<a href="https://advertiser.example" attributionsrc="https://ad-tech.example/register-source">
  Visit Advertiser
</a>

When the browser receives the request, the ad-tech server responds with the Attribution-Reporting-Register-Source HTTP response header. This header contains the source event ID, destination origin, expiration time, and reporting endpoints.

Registering Attribution Triggers

When a user completes an action on the advertiser’s site (such as completing a checkout or registering an account), a trigger must be recorded. JavaScript initiates a network request to the reporting origin:

// Registering a conversion trigger via JavaScript Fetch
fetch("https://ad-tech.example/register-trigger", {
  method: "POST",
  attributionReporting: {
    eventSourceEligible: false,
    triggerEligible: true,
  }
});

The server responds with the Attribution-Reporting-Register-Trigger HTTP header. This header specifies trigger data, priority, and values associated with the conversion event.

Local Browser-Side Matching

Instead of sending raw identifiers to an external server to match ads with purchases, the browser performs the match internally:

1. Storage: The browser stores source events and trigger events securely within its local storage.
2. Attribution Logic: When a trigger request occurs, the browser looks for matching sources that share the same destination origin and fall within the defined expiration window.
3. Privacy Protections: The browser applies differential privacy techniques to prevent re-identification.

Generating Privacy-Preserving Reports

The Attribution Reporting API produces two types of reports:

• Event-Level Reports: These associate a specific ad click or view with coarse conversion data. To prevent tracking individual user journeys, the data is limited to a few bits (e.g., 3 bits for clicks, allowing values 0–7), random noise is introduced, and reports are delayed by hours or days to eliminate timing-based tracking.
• Summary (Aggregatable) Reports: These provide detailed data—such as purchase values or granular conversion types—by encrypting the reports on the device. These encrypted payloads are sent to the ad-tech server, which must forward them to a dedicated Aggregation Service operating within a Trusted Execution Environment (TEE). The Aggregation Service decrypts the data, adds noise, and outputs aggregate metrics without revealing individual user actions.