Attribution Reporting API
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
The Attribution Reporting API enables developers to measure conversions — for example when a user clicks an ad embedded on one site and then proceeds to purchase the item over on the vendor's site — and then access reports on those conversions. It does this without relying on third-party tracking cookies.
Concepts and usage
Advertisers commonly want to measure how many users see an ad and then go on to view and purchase a product (conversions). This allows them to figure out what advertising placements are giving them the greatest return on investment (ROI) so they can adjust their advertising strategy accordingly. The process of measuring conversions usually includes capturing data such as:
- Which users converted (for example purchased an item, or signed up for a service), and how many.
- The geographic regions they are based in.
- What sites the ads were placed on.
- How many products were sold, services were signed up for, etc.
- How much revenue was generated.
Traditionally on the web, conversion has been measured using third-party tracking cookies. An ad will typically be embedded on a web page in an <iframe>
, which can set a cookie containing information about the user and their interaction with the ad.
Later on, when the user decides to visit the advertiser's site, provided it is from the same domain as the ad, that site can access the third-party cookie set previously by the ad. The advertiser can then associate the data from the ad with their own first-party data to answer questions such as "did the user purchase a product after interacting with an ad for the product from another site?"
This is bad for user privacy. At this point, any page from the same domain can get access to that cookie, plus information from sites that embed those pages. A surprisingly large number of parties will be able to access that data, and infer other data about the user based on their browsing habits.
The Attribution Reporting API provides a way to measure ad conversions in a way that protects user privacy.
How does it work?
Let's illustrate how the Attribution Reporting API works via an example.
Say we have a online shop, shop.example
(aka the advertiser), which embeds an ad for one of its products on a content site, news.example
(aka the publisher). The ad content is found at ad.shop.example
.
The online shop owners want to measure how many conversions they get from users interacting with the ad, viewing the product page on their site, and putting the product into their shopping cart.
The steps involved are as follows:
- When a user visits the
news.example
site, an attribution source can be registered for specific user interactions with the embedded ad. There are several ways that a user can interact with ads on the page. For an ad interaction to register an attribution source, the ad must send a request with anAttribution-Reporting-Eligible
header to indicate that the response is eligible to register an attribution source. Registration will be completed if the response includes an appropriateAttribution-Reporting-Register-Source
header. The attribution source can be, for example:- A link. In this case, the interaction is the user clicking on the link (directly via an
<a>
element, or via aWindow.open()
call). The source is registered via the response to the navigation request. - An image such as an advertising banner or a 1x1 transparent tracking pixel. In this case, the interaction is the user visiting the page. The source is registered when the image loads, i.e. when the server responds to the image request.
- A fetch request (i.e. a
fetch()
orXMLHttpRequest
). In this case the interaction can be specified as whatever makes sense for your app — for example the fetch request could be invoked by aclick
orsubmit
event. The source is registered once the response comes back.
- A link. In this case, the interaction is the user clicking on the link (directly via an
- When the attribution source interaction occurs, the source data returned in the
Attribution-Reporting-Register-Source
header is stored in a private local cache accessible only by the browser. This data includes the contextual and first-party data available to the page and the advertiser, the origin of the ad tech company that is collecting the conversion data, and one or more destinations (eTLD+1s) where you expect the conversion from that ad to occur (i.e. the advertiser's site(s), for exampleshop.example
). - When the user later visits
shop.example
, this site can register an attribution trigger when an interaction indicates that a conversion has occurred (for example, the user clicks the "Add to cart" button onshop.example
). The browser will then send a request along with anAttribution-Reporting-Eligible
header to indicate that the response is eligible to register an attribution trigger, and registration will be completed if the response includes an appropriateAttribution-Reporting-Register-Trigger
header. The attribution trigger can be, for example:- An image such as a shopping cart icon or a 1x1 transparent tracking pixel. In this case, the interaction is the user visiting the page. The trigger is registered when the image loads, i.e. when the server responds to the image request.
- A fetch request (i.e. a
fetch()
orXMLHttpRequest
). In this case the interaction can be specified as whatever makes sense for your app — for example the fetch request could be invoked by aclick
orsubmit
event. The trigger is registered once the response comes back.
- When the trigger attribution completes, the browser attempts to match the data from the Attribution-Reporting-Register-Trigger header with a source data entry saved in the private local cache (see 2.). See Registering attribution triggers for matching methodology and requirements.
- If a match is made, the browser sends report data to an endpoint on a reporting server typically owned by the ad tech provider where it can be securely analyzed. Unlike with cookies, the data is only available to the specific site you send it to - there will be no data shared elsewhere. These reports can be either:
- Event-level reports: Reports based on an attribution source event, where detailed source data is associated with coarse trigger data. For example, a report may look like "Click ID 200498 on
ad.shop.example
led to a purchase onshop.example
", where "Click ID 200498" is the detailed source data, and "purchase" is the coarse trigger data. The detailed source data may encode first-party or contextual data from the source page, and the trigger data may encode the event from the trigger page. - Summary reports: More detailed reports that combine data from multiple conversions on both the source and trigger side. For example "Campaign ID 774653 on
news.example
has led to 654 sales of widgets onshop.example
from users in Italy, with a total revenue of $9540." Compiling a summary report requires usage of an aggregation service (see for example the Google aggregation service).
- Event-level reports: Reports based on an attribution source event, where detailed source data is associated with coarse trigger data. For example, a report may look like "Click ID 200498 on
For more information on implementing the functionality required for the above steps, see:
Interfaces
The Attribution Reporting API doesn't define any distinct interfaces of its own.
Extensions to other interfaces
HTMLAnchorElement.attributionSrc
,HTMLImageElement.attributionSrc
,HTMLScriptElement.attributionSrc
-
The
attributionSrc
property allows you to get and set theattributionsrc
attribute on<a>
,<img>
, and<script>
elements programmatically. It reflects the value of that attribute. fetch()
and theRequest()
constructor, theattributionReporting
option-
When generating a request via
fetch()
, this indicates that you want the response to be able to register an attribution source or trigger. XMLHttpRequest.setAttributionReporting()
-
When generating a request via
XMLHttpRequest
, this indicates that you want the response to be able to register an attribution source or trigger. Window.open()
, theattributionsrc
feature keyword-
Causes completion of the registration of an attribution source and triggers the browser to store the associated source data (as provided in the
Attribution-Reporting-Register-Source
response header) when theopen()
method completes. Note thatWindow.open()
calls cannot be used to register attribution triggers.
HTML elements
<a>
,<img>
, and<script>
— theattributionsrc
attribute-
Specifies that you want the browser to send an
Attribution-Reporting-Eligible
header along with the associated resource request. On the server-side this header is used to trigger sending anAttribution-Reporting-Register-Source
orAttribution-Reporting-Register-Trigger
header in the response. When registering an attribution source, this is required; when registering an attribution trigger it is only required if you want to specify a separate registration server to the resource thesrc
attribute is pointing at. Note that<a>
elements cannot be used to register attribution triggers.
HTTP headers
Attribution-Reporting-Eligible
-
HTTP request that indicates that the corresponding response is eligible to register an attribution source or trigger.
Attribution-Reporting-Register-Source
-
HTTP response that registers a page feature as an attribution source. This is included as part of a response to a request that included an
Attribution-Reporting-Eligible
header. Attribution-Reporting-Register-Trigger
-
HTTP response that registers a page feature as an attribution trigger. This is included as part of a response to a request that included an
Attribution-Reporting-Eligible
header. Permissions-Policy
attribution-reporting
directive-
Controls whether the current document is allowed to use attribution reporting.
Enrollment and local testing
To use the Attribution Reporting API in your sites, you must specify it in the privacy sandbox enrollment process. If you don't do this, the API flow is blocked at response time, i.e. the response headers are ignored and sources and triggers are not registered.
You can still test your Attribution Reporting API code locally without enrollment. To allow local testing, enable the following Chrome developer flag:
chrome://flags/#privacy-sandbox-enrollment-overrides
Examples
See Demo: Attribution Reporting API for an example implementation (see the source code also).
Specifications
Specification |
---|
Attribution Reporting # element-attrdef-a-attributionsrc |
Browser compatibility
BCD tables only load in the browser
See also
- Attribution Reporting Header Validation tool
- Attribution reporting on developer.chrome.com (2023)
- Register multiple reporters on developer.chrome.com (2023)
- The Privacy Sandbox on developer.chrome.com (2023)