注册归因触发器

实验性： 这是一种 实验性技术
在生产环境中使用此功能之前，请仔细查看 浏览器兼容性表。

本文介绍如何注册归因触发器。

基本方法

一旦你 注册了归因来源，你需要注册归因触发器。这些是在网站上进行转换测量的交互（例如，点击广告客户网站上的“购买”按钮可以表明可能发生了转换）。然后，浏览器将尝试将归因触发器与存储在私有本地存储分区中的归因来源条目匹配，并在找到匹配项时 生成报告。

不同的归因触发器类型以不同的方式注册，这些方式在下面的部分中详细说明 - 请参阅 基于 HTML 的归因触发器 和 基于 JavaScript 的归因触发器。

但是，在幕后注册触发器、查找匹配项等的操作在所有情况下都是相同的。

  1. 所有触发器类型都在请求中发送 Attribution-Reporting-Eligible 标头，这表示响应有资格注册触发器。例如
    http
    Attribution-Reporting-Eligible: trigger
  2. 当服务器收到包含 Attribution-Reporting-Eligible 标头的请求时，它可以在响应中包含 Attribution-Reporting-Register-Trigger。其值为包含可包含在生成报告中的数据的 JSON 字符串，例如触发器的 ID，以及优先级和重复数据删除值。以下示例旨在与 事件级报告 归因来源匹配
    js
    res.set(
  "Attribution-Reporting-Register-Trigger",
  JSON.stringify({
    "event_trigger_data": [
      {
        "trigger_data": "4",
        "priority": "1000000000000",
        "deduplication_key": "2345698765",
      },
    ],
    "debug_key": "1115698977",
  });
);
    此处指定的字段如下
    • "event_trigger_data"：表示有关触发器的数据的对象。这包括
      • "trigger_data"：与触发器关联的数据，通常用于指示事件，例如“用户将商品添加到购物车”或“用户注册邮件列表”。如果存在，此值将包含在生成的报告中，尽管它将根据归因来源的 "trigger_data_matching" 字段进行修改。

        注意：用于表示每个事件的值以及数组中的元素数量完全是任意的，由你作为开发人员定义。数组可能包含未使用的值，但必须在数组中存在值，以便在注册触发器时由浏览器将其归因于来源。

      • "priority"：表示归因触发器优先级值的字符串。有关更多信息，请参阅 报告优先级和限制。
      • "deduplication_key"：表示可用于防止归因重复的唯一密钥的字符串 - 例如，如果用户多次将同一商品添加到购物车。有关更多信息，请参阅 防止报告中的重复。
    • "debug_key"：表示调试密钥的数字。如果要与关联的归因报告一起生成 调试报告，请设置此值。
    请参阅 Attribution-Reporting-Register-Trigger 以详细了解所有可用字段。旨在与 汇总报告 归因来源匹配的触发器需要以下所示的字段
    js
    res.set(
  "Attribution-Reporting-Register-Trigger",
  JSON.stringify({
    "aggregatable_trigger_data": [
      {
        "key_piece": "0x400",
        "source_keys": ["campaignCounts"]
      },
      {
        "key_piece": "0xA80",
        "source_keys": ["geoValue", "nonMatchingKeyIdsAreIgnored"]
      }
    ],
    "aggregatable_values": {
      "campaignCounts": 32768,
      "geoValue": 1664
    },
    "debug_key": "1115698977"
  });
);
    此示例中的字段为
    • "aggregatable_trigger_data"：对象数组，每个对象定义一个应用于不同源密钥的聚合密钥。
    • "aggregatable_values"：包含属性的对象，表示为 "aggregatable_trigger_data" 中定义的每个数据点提供的值。
    同样，请参阅 Attribution-Reporting-Register-Trigger 以详细了解所有可用字段。
  3. 当用户与归因触发器交互时，浏览器会尝试将触发器与存储在浏览器私有本地缓存中的任何归因来源条目匹配。对于成功的匹配，Attribution-Reporting-Register-Trigger 的 "trigger_data" 必须与 Attribution-Reporting-Register-Source 的 "trigger_data" 中提供的其中一个值匹配，并且注册触发器的顶级页面的站点（方案 + eTLD+1）必须
    • 与源关联数据中指定的至少一个 destination 的站点匹配。
    • 与指定源注册的请求具有相同的来源。

    注意：这些要求提供了隐私保护，但也提供了灵活性 - 来源和触发器都可能嵌入在 <iframe> 中或位于顶级站点中。

    还有许多其他因素会导致匹配失败；例如
  4. 如果找到成功的匹配，浏览器将 生成报告（基于源和触发器数据），并将其发送到报告端点。

注意：归因触发器不能在 <a> 元素或 Window.open() 调用上注册，就像归因来源一样。

基于 HTML 的归因触发器

基于 HTML 的归因触发器可用于在页面首次加载时检测转换 - 或更准确地说，是在 <img> 或 <script> 加载时检测转换。例如，如果用户点击了发布者页面上的归因来源链接并导航到广告客户页面，则可以在广告客户页面加载后立即注册归因触发器并让浏览器尝试与存储的来源条目匹配。

可以通过将 attributionsrc 属性添加到适当的元素来注册归因触发器。这可以在 <img> 和 <script> 元素上完成。

如果将属性值留空，则注册请求将发送到托管请求资源的服务器。也可以在值中指定其他 URL 以将注册请求发送到该 URL；有关更多详细信息，请参阅 在 attributionsrc 中指定 URL。

这是一个 <img> 元素示例

html
<img
  src="https://shop.example/conversion/4rghshdh5"
  width="1"
  height="1"
  attributionsrc />

你也可以通过 HTMLImageElement.attributionSrc 属性实现此目的

js
const imgElem = document.querySelector("img");
imgElem.attributionSrc = "";

在这种情况下，当浏览器收到包含图像文件的响应（当 load 事件触发时）时，浏览器将尝试将触发器与存储的归因来源匹配。请记住，用户可能不一定能够感知图像 - 它可能是一个仅用于归因报告的 1x1 透明跟踪像素。

一个 <script> 示例可能如下所示

html
<script src="advertising-script.js" attributionsrc />
js
const scriptElem = document.querySelector("script");
scriptElem.attributionSrc = "";

在这种情况下，当浏览器收到包含脚本的响应时，浏览器将尝试将触发器与存储的归因来源匹配。

基于 JavaScript 的归因触发器

基于 JavaScript 的归因触发器比基于 HTML 的归因触发器更通用。你可以根据自定义交互触发浏览器尝试与存储的来源匹配，例如，点击自定义元素或提交表单。

要注册基于脚本的归因触发器，你可以

  • 发送包含 attributionReporting 选项的 fetch() 请求
    js
    const attributionReporting = {
  eventSourceEligible: false,
  triggerEligible: true,
};

// Optionally set keepalive to ensure the request outlives the page
function triggerMatching() {
  fetch("https://shop.example/endpoint", {
    keepalive: true,
    attributionReporting,
  });
}

// Associate the interaction trigger with whatever
// element and event makes sense for your code
elem.addEventListener("click", triggerMatching);
  • 发送 XMLHttpRequest 并对请求对象调用 setAttributionReporting()
    js
    const attributionReporting = {
  eventSourceEligible: false,
  triggerEligible: true,
};

function triggerMatching() {
  const req = new XMLHttpRequest();
  req.open("GET", "https://shop.example/endpoint");
  // Check availability of setAttributionReporting() before calling
  if (typeof req.setAttributionReporting === "function") {
    req.setAttributionReporting(attributionReporting);
    req.send();
  } else {
    throw new Error("Attribution reporting not available");
    // Include recovery code here as appropriate
  }
}

// Associate the interaction trigger with whatever
// element and event makes sense for your code
elem.addEventListener("click", triggerMatching);

在这种情况下，当浏览器收到 fetch 请求的响应时，浏览器将尝试将触发器与存储的归因来源匹配。

注意：请求可以针对任何资源。它不需要与归因报告 API 直接相关，并且可以是针对 JSON、纯文本、图像 blob 或任何其他对你的应用有意义的内容的请求。

在 attributionsrc 中指定 URL

在以上示例中，attributionsrc 属性为空白，取空字符串的值。如果持有请求资源的服务器与您希望处理注册的服务器相同，则此操作没有问题，即接收 Attribution-Reporting-Eligible 标头并使用 Attribution-Reporting-Register-Trigger 标头进行响应。

但是，请求的资源可能不在您控制的服务器上，或者您只想在不同的服务器上处理注册归因触发器。在这种情况下，您可以将一个或多个 URL 指定为 attributionsrc 的值。当发生资源请求时，除了资源来源之外，Attribution-Reporting-Eligible 标头也将发送到 attributionsrc 中指定的 URL；然后，这些 URL 可以使用 Attribution-Reporting-Register-Trigger 进行响应以完成注册。

例如，对于 <img> 元素，您可以在 attributionsrc 属性中声明 URL

html
<img
  src="https://shop.example/conversion/4rghshdh5"
  attributionsrc="https://my-separate-tracking-site.example.com"
  width="1"
  height="1" />

或者通过 JavaScript 的 attributionSrc 属性

js
const imgElem = document.querySelector("img");
imgElem.attributionSrc = "https://my-separate-tracking-site.example.com";

另请参阅