注册归因触发器

了解如何注册归因触发器以统计转化次数。

归因触发器是指告知浏览器捕获转化的事件。

按照本文档中的步骤操作，您可以注册触发器来注册转化，然后浏览器会将这些转化归因于相关的来源事件，即广告展示或广告点击。

注册方法

如需注册触发器，请使用 HTML 元素或 JavaScript 调用：

  • <img> 标记
  • <script> 标记
  • fetch 次来电
  • XMLHttpRequest

这会生成网络请求，然后您可以使用触发注册 HTTP 响应标头来响应这些请求。

注册触发器以归因转化

注册触发器与注册归因来源事件类似。完整步骤将在下文中介绍。总结如下：

  1. 启动触发注册。使用像素或 fetch() 调用发出请求。

  2. 通过使用触发注册标头进行响应，完成触发注册。

    在收到像素请求（发送到常规 src 属性中定义的端点，或者发送到 attributionsrc 中定义的端点，如果您已选择使用 attributionsrc 并为其赋予了值）后，使用 Attribution-Reporting-Register-Trigger 标头进行响应。

    在此标题中，指定您最终希望在报告中显示哪些触发数据。任何响应都可以设置此标头。只要是对来自与 destination 匹配的网站的请求做出的响应，来源就会匹配。收到标头后，浏览器会查找匹配的来源并安排报告。

    事件级报告示例：

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

    摘要报告示例：

    {
  ... // 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
  }
}

处理子网域

如果 destination 为 https://advertiser.example，则可对 https://advertiser.example 及其子网域（例如 https://shop.advertiser.example）上的转化进行归因。

如果 destination 为 https://shop.advertiser.example，则可将转化归因于 https://advertiser.example 和 https://shop.advertiser.example。

必需属性和可选属性

当您使用 HTML 元素或进行 JavaScript 调用来注册触发器时，可能需要使用 attributionsrc 或 attributionReporting。如需详细了解何时需要提供这些信息，请参阅下表。

如果 attributionsrc 是可选的，则使用它表示相应请求符合归因报告的条件。如果您使用 attributionsrc，浏览器会发送 Attribution-Reporting-Eligible 标头。它还可用于应用到网站的衡量：如果存在 attributionsrc，浏览器会发送 Attribution-Reporting-Support 标头。

注册方法 触发器
<a> 标记 不适用：锚点无法注册触发器。
<img> 标记 attributionsrc 是可选的。该标头足以注册触发器。
<script> 标记 attributionsrc 是可选的。该标头足以注册触发器。
fetch 次来电 attributionReporting 选项是必需的。
XMLHttpRequest attributionReporting 选项是必需的。
window.open() 不适用： window.open 无法注册触发器。

第 1 步：启动触发器注册

您可以使用像素（<img> 代码）或脚本代码注册触发条件。

使用新的或现有的转化像素

以下示例通过添加 attributionsrc 属性来触发现有图片的提供方信息。

attributionsrc 的来源必须与执行来源注册的来源一致。

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

以下示例通过添加新的转化像素 attributionsrc 属性来触发归因。

src 的来源必须与执行来源注册的来源一致。

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

使用脚本标记

您可以使用脚本标记执行触发注册；其行为与 <img> 完全相同。以下代码示例说明了 fetch() 和 XMLHttpRequest() (XHR) 的用法。

此代码可有效模拟使用 attributionsrc 的 HTML 请求会执行的操作：

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

// Optionally set keepalive to make sure 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();

attributionsrc（无论是否具有值）

您可以添加带有或不带值的 attributionsrc。

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

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

如果您为 attributionsrc 设置了值，则该值可以是一个或多个以空格分隔的网址。

使用网址会导致浏览器发起单独的 keepalive 提取请求（每个网址一个），其中包含 Attribution-Reporting-Eligible 请求标头。

如果您想通过响应与元素的主要请求分开的请求来注册触发器，此方法非常有用。

例如，如果您需要在图片元素上注册触发器，但实际上无法控制图片响应，那么您可能需要一种配置，让您可以将触发器注册标头作为对与图片分开的请求的响应发送，并且可以完全控制该响应。通过为 attributionsrc 指定明确的值，您可以指示浏览器发出该额外请求并配置其目标位置。

第 2 步：使用标头进行响应

收到浏览器请求后，请做出响应，并在响应中包含 Attribution-Reporting-Register-Trigger 标头：

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

后续步骤

了解如何注册归因来源。