1. Web
  2. Web API
  3. 归因报告 API
  4. 注册归因触发器

注册归因触发器

本文档解释了如何注册归因触发器。

基本方法

在您注册归因来源之后，您需要注册归因触发器。这些是用于衡量转化的网站上的互动（例如，点击广告商网站上的“购买”按钮可能表明已发生转化）。然后，浏览器将尝试将归因触发器与存储在私有本地存储分区中的归因来源条目进行匹配，并在找到匹配项时生成报告。

不同类型的归因触发器以不同的方式注册，这些将在下面的各节中详细介绍 — 请参阅基于 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></script>
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 请求的响应时，它将尝试将触发器与已存储的归因来源进行匹配。

注意：请求可以是任何资源。它不需要直接与 Attribution Reporting 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";

另见

帮助改进 MDN

了解如何贡献

此页面最后修改于 ，由 MDN 贡献者修改。

在 GitHub 上查看此页面 • 报告此内容的问题
© . Content available under a Creative Commons license.