Register attribution sources

Learn how to register sources to attribute clicks and views to the appropriate events.

An attribution source is an ad-related event (a click or view), to which an ad tech can attach the following kinds of information:

Contextual reporting data, such as the ad creative ID, information about the campaign, or geography.
A conversion destination, as in the site where you expect the user to convert.

By following the steps in this document, you can register sources—ad impressions or clicks—to which the browser then attributes conversions.

Registration methods

To register attribution sources, use HTML elements or JavaScript calls:

<a> tag
<img> tag
<script> tag
fetch call
XMLHttpRequest
window.open call

This generates network requests you then respond to with a source registration HTTP response header.

Register sources for clicks or views

To register an attribution source for either clicks or views, follow the steps outlined here. The complete steps follow. Here's the summary:

Initiate the source registration. Use an HTML element or a JavaScript call to make a request. This step is different for clicks and views, as you'll notice in the following sections.

Complete the source registration by responding with the source registration header. Upon receiving that request, respond with the header Attribution-Reporting-Register-Source. In that header, specify the desired Attribution Reporting configuration. This step is the same for both clicks and views.

Example for summary reports:

{
  "aggregation_keys": {
    "campaignCounts": "0x159",
    "geoValue": "0x5"
  },
  "aggregatable_report_window": "86400",
  "destination": "https://example.com"
}

Example for event-level reports:

{
  "source_event_id": "12340873456",
  "destination": "[eTLD+1]",
  "expiry": "[64-bit signed integer]",
  "priority": "[64-bit signed integer]",
  "event_report_window": "[64-bit signed integer]"
}

Required and optional attributes

As you use HTML elements or make JavaScript calls to register sources, you may need to use attributionsrc or attributionReporting. Refer to the following table for details on when these are required.

When attributionsrc is optional, using it indicates that the request is eligible for Attribution Reporting. If you use attributionsrc, the browser sends the Attribution-Reporting-Eligible header. It's also useful for app-to-web measurement: if attributionsrc is present, the browser sends the Attribution-Reporting-Support header.

Registration method	Source
`<a>` tag	(navigation source) `attributionsrc` is required.
`<img>` tag	(event source) `attributionsrc` is required.
`<script>` tag	(event source) `attributionsrc` is required.
`fetch` call	The `attributionReporting` option is required.
`XMLHttpRequest`	The `attributionReporting` option is required.
`window.open` call	(navigation source) `attributionsrc` is required.

Step 1: Initiate source registration

Step 1 is different for clicks and views.

To register an attribution source for a click, you can use an <a> tag or JavaScript window.open().

Using an anchor

Add attributionsrc to existing <a> tags for which you want to measure impressions or clicks:

<a href="https://shoes.example/..." attributionsrc>Click me</a>

Review the example code for more information.

Using a script

Call window.open() with attributionsrc:

window.open(
  "https://shoes.example/...",
  "_blank",
  "attributionsrc");

To be taken into account, this method must be called within 5 seconds of user interaction.

Instead of adding attributionsrc by itself, for an image or script you can specify a single URL value:

<a href=... attributionsrc="https://a.example/register-source">Click me</a>

In the JavaScript case, if you give attributionsrc a value, make sure to encode that URL in case it contains special characters such as = that would cause the parameter to be improperly parsed.

Encode as follows:

const encodedUrl = encodeURIComponent(
  "https://adtech.example/attribution_source?ad_id=...");
window.open(
  "https://shoes.example/landing",
   "_blank",
   `attributionsrc=${encodedUrl}`);

attributionsrc can also take a space-separated list of URLs as illustrated here with an <a> tag:

<a href=... attributionsrc="https://a.example/register-source
  https://b.example/register-source">Click me</a>

or as it is here using window.open().

window.open("...", "_blank", `attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2}`)

In such cases, both URLs receive navigation-source-eligible attributionsrc requests (requests that include the Attribution-Reporting-Eligible header).

`attributionsrc` with or without a value

As you saw previously, you can specify attributionsrc without a URL. You can also specify a single URL. Additionally, you can use a space-separated list of URLs.

Using URLs causes the browser to initiate a separate keepalive fetch request—one for each URL—which includes the Attribution-Reporting-Eligible request header.

This is useful if you want to make the source registration by responding to a request that is separate from the element's main request.

For example, if you need to register sources for clicks on an anchor element, you may not actually be in control of the destination; in this case, you'll want a configuration whereby you send the source registration header as a response to a request that is separate from the navigation, and that you can completely control. By specifying an explicit value for attributionsrc, you're instructing the browser to make that extra request and configuring its destination.

To register an attribution source for a view, you can use an image or script tag to which you'll add the attributionsrc attribute.

Alternatively, you can use JavaScript fetch() or XMLHttpRequest().

With an image

<img attributionsrc
src="https://adtech.example/attribution_source?ad_id=...">

With a script

<script attributionsrc
  src="https://adtech.example/attribution_source?ad_id=..."></script>

Optionally, you can specify a URL value for attributionsrc in the same way as for clicks; that is, for an image or script , you can set the attributionsrc URL or URLs like so:

With a single URL:

<img attributionsrc="https://adtech.example/attribution_source?ad_id=123">

With a list of URLs:

<img attributionsrc="https://a.example/register-source
  https://b.example/register-source">

Using `fetch()` or `XMLHttpRequest()`

This code effectively simulates what an HTML request with attributionsrc would do:

const attributionReporting = {
  eventSourceEligible: true,
  triggerEligible: false,
};

// Optionally set keepalive to ensure the request outlives the page.
window.fetch("https://adtech.example/attribution_source?my_ad_id=123",
  { keepalive: true, attributionReporting });

const attributionReporting = {
  eventSourceEligible: true,
  triggerEligible: false,
};

const req = new XMLHttpRequest();
req.open("GET", url);
req.setAttributionReporting(attributionReporting);
req.send();

Step 2: Respond with header (clicks and views)

The next step for both clicks and views is to respond with the Attribution-Reporting-Register-Source header.