Register attribution triggers

Learn how to register attribution triggers to count your conversions.

An attribution trigger is the event that tells the browser to capture conversions.

By following the steps in this document, you can register triggers to register conversions that the browser then attributes to the relevant source events—namely, ad impressions or ad clicks.

Registration methods

To register triggers, use HTML elements or JavaScript calls:

• <img> tag
• <script> tag
• fetch call
• XMLHttpRequest

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

Register a trigger to attribute a conversion

Registering a trigger is similar to registering an attribution source event. The complete steps are described later. Here's the summary:

1. Initiate the trigger registration. Use a pixel or a fetch() call to make a request.

2. Complete the trigger registration by responding with the trigger registration header.

   Upon receiving the pixel request—sent either to the endpoint defined in the usual src attribute, or to the endpoint defined in attributionsrc if you've chosen to use attributionsrc and given it a value—respond with the header Attribution-Reporting-Register-Trigger.

   In this header, specify the trigger data you want surfaced in reports ultimately. Any response can set this header. As long as it's a response to a request made from a site that matches the destination, sources will be matched. When the header is received, the browser looks for matching sources and schedules a report.

   Example for event-level reports:

   {
     "event_trigger_data": [{
       "trigger_data": "[unsigned 64-bit integer]",
       "priority": "[signed 64-bit integer]",
       "deduplication_key": "[unsigned 64-bit integer]"
     }]
   }
   

   Example for summary reports:

   {
     ... // existing fields, such as "event_trigger_data"
   
     "aggregatable_trigger_data": [
      {
        "key_piece": "0x400",
        "source_keys": ["campaignCounts"]
      },
      {
        "key_piece": "0xA80",
        "source_keys": ["geoValue", "nonMatchingKeyIdsAreIgnored"]
      }
     ],
     "aggregatable_values": {
       "campaignCounts": 32768,
       "geoValue": 1664
     }
   }
   

Note: When the browser receives an attribution trigger response from an attributionsrc URL on a given page, a local storage lookup is done to find a source that matches both the attributionsrc origin and destination site to which that page belongs. If multiple sources are found, the browser picks the one that was stored most recently—unless sources have different priorities, in which the browser picks the one with the greatest priority.

Dealing with subdomains

If destination is https://advertiser.example, conversions on both https://advertiser.example and its subdomains, such as https://shop.advertiser.example can be attributed.

If destination is https://shop.advertiser.example, conversions on both https://advertiser.example and https://shop.advertiser.example can be attributed.

Required and optional attributes

As you use HTML elements or make JavaScript calls to register triggers, 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	Trigger
<a> tag	N/A: Anchors cannot register a trigger.
<img> tag	attributionsrc is optional. The header is sufficient to register a trigger.
<script> tag	attributionsrc is optional. The header is sufficient to register a trigger.
fetch call	The attributionReporting option is required.
XMLHttpRequest	The attributionReporting option is required.
window.open()	N/A: window.open cannot register a trigger.

Step 1: Initiate the trigger registration

You can register a trigger using a pixel (<img> tag) or script tag.

Using a new or existing conversion pixel

The following example triggers the attribution on an existing image by adding the attributionsrc attribute.

The origin for attributionsrc must match the origin that performed the source registration.

<img src="https://advertiser.example/conversionpixel"
     attributionsrc="https://adtech.example/attribution_trigger?purchase=13">

The next example triggers the attribution by adding a new conversion pixel attributionsrc attribute.

The origin for src must match the origin that performed the source registration.

<img src="https://adtech.example/conversionpixel"
     attributionsrc>

Key point: In both cases, an attribution can only be triggered on a page whose site matches the site that was provided in destination upon source registration.

Using a script tag

You can perform trigger registration with a script tag; it behaves identically to <img>. The following code samples illustrate the use of fetch() and XMLHttpRequest() (XHR).

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

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

// 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: false,
  triggerEligible: true,
};

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

Key point:

• The origin or the url set in fetch() or open() must match the origin that performed the source registration.
• An attribution can only be triggered on a page whose site matches the site that was provided in destination upon source registration.

attributionsrc with or without a value

You can add attributionsrc either with or without a value.

<!-- Without a value -->
<img src="..." width="1" height="1" attributionsrc>

<!-- With a value (URL) -->
<img src="..." width="1" height="1" attributionsrc="https://...">

If you set a value for attributionsrc, it can be one or more space-separated URLs.

Using a URL 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 trigger registration by responding to a request that is separate from the element's main request.

For example, if you need to register triggers on an image element, you may not actually be in control of the image response; in this case, you'll want a configuration whereby you send the trigger registration header as a response to a request that is separate from the image, 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.

Step 2: Respond with a header

Upon receiving the browser request, respond and include in your response the Attribution-Reporting-Register-Trigger header:

JSON.stringify({
  event_trigger_data: [{
    trigger_data: "412444888111012",
    // Optional
    priority: "1000000000000",
    deduplication_key: "2345698765"
  }],
  debug_key: "1115698977"
});

Caution: The event_trigger_data field value must be nested in square brackets, because the browser expects a JSON array. This is useful for filters.

Next steps

Learn how to Register attribution sources.