Register attribution triggers

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:

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

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
     }
   }

# 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.

# 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

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

# 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:

// With fetch
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 });

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

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

# 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 should be a single URL.

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 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.

# 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'})

# Next steps

Learn how to Register attribution sources.