注册归因来源

归因来源采用您要衡量其交互的内容中包含的链接、图像或脚本的形式（例如，它们可能是您想要衡量其转化率的广告）。当发生特定用户交互时，它们会使浏览器将源数据存储在私有的本地缓存中（仅浏览器可访问）。不同的归因来源类型以不同的方式注册和发出交互信号——它们被区分成

• 导航来源，这些来源会导致浏览器响应导航存储源数据——例如，当用户点击链接或使用键盘激活链接时，或者当导航是由于 Window.open() 调用引起的时。有关示例，请参阅 基于导航的归因来源.
• 事件来源，这些来源会导致浏览器响应事件触发存储源数据。有关示例，请参阅 基于事件的归因来源.

无论哪种情况，注册来源以及检索和存储源数据的幕后过程都相同

1. 当用户与归因来源进行交互时，它会在对衡量交互的服务器（通常是广告主的服务器）的请求中发送一个 Attribution-Reporting-Eligible 标头，这表示响应有资格注册来源。例如
   http

   Attribution-Reporting-Eligible: navigation-source
   

2. 当服务器接收到包含 Attribution-Reporting-Eligible 标头的请求时，它可以在响应中包含一个 Attribution-Reporting-Register-Source 标头，以完成来源注册。它的值是一个 JSON 字符串，其中包含浏览器应存储有关已交互的归因来源的信息。此标头中包含的信息还决定了浏览器将生成哪种类型的报告
   • 以下示例将在触发器与来源匹配时生成 事件级别报告
     js

     res.set(
       "Attribution-Reporting-Register-Source",
       JSON.stringify({
         source_event_id: "412444888111012",
         destination: "https://advertiser.example",
         trigger_data: [0, 1, 2, 3, 4],
         trigger_data_matching: "exact",
         expiry: "604800",
         priority: "100",
         debug_key: "122939999",
         event_report_window: "86400",
       }),
     );
     

     在此上下文中，唯一必需的字段是 destination，它指定预期在其中发生触发器的 1-3 个站点。这些用于在与触发器交互时将归因触发器与来源匹配。上面指定的其他字段执行以下操作
     • "source_event_id"：表示归因来源 ID 的字符串，可在与归因来源交互时将其映射到其他信息，或在报告端点汇总信息（有关端点信息，请参阅 生成报告 > 基本过程）。
     • "trigger_data"：表示描述可能与该来源匹配的不同触发事件的数据的 32 位无符号整数数组。例如，“用户将商品添加到购物车”或“用户注册邮件列表”可能是发生在触发器站点上的操作，这些操作可能与该来源匹配，并表明广告主试图衡量的某种转化。这些必须与在 触发器 中指定的 "trigger_data" 匹配，才能进行事件级别的归因。

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

     • "trigger_data_matching"：指定如何将来自触发器的 "trigger_data" 与来源的 "trigger_data" 匹配的字符串。"exact" 是您几乎始终使用的值，它匹配确切的值。
     • "expiry"：表示归因来源的过期时间的字符串（以秒为单位），在此时间之后，归因来源将不再处于活动状态（即，后续触发器将不再归因于该来源）。
     • "priority"：表示归因来源的优先级值的字符串。有关更多信息，请参阅 报告优先级和限制.
     • "debug_key"：表示调试密钥的以 10 为底格式的 64 位无符号整数。如果您想要与关联的归因报告一起生成 调试报告，请设置此值。
     • "event_report_window"：表示时间的字符串（以秒为单位），在此时间之后，后续触发器将不再归因于该来源，以用于生成事件级别报告。
     有关此标头上的所有可用字段的详细说明，请参阅 Attribution-Reporting-Register-Source.
   • 要使浏览器在触发器与来源匹配时生成 汇总报告，您需要包含一些额外的字段，除了生成事件级别报告所需的字段之外。
     js

     res.set(
       "Attribution-Reporting-Register-Source",
       JSON.stringify({
         source_event_id: "412444888111012",
         destination: "https://advertiser.example",
         trigger_data: [0, 1, 2, 3, 4],
         trigger_data_matching: "exact",
         expiry: "604800",
         priority: "100",
         debug_key: "122939999",
         event_report_window: "86400",
     
         aggregation_keys: {
           campaignCounts: "0x159",
           geoValue: "0x5",
         },
         aggregatable_report_window: "86400",
       }),
     );
     

     此示例中的附加字段是
     • "aggregation_keys"：包含用户提供的密钥的对象，这些密钥代表不同的数据点，将汇总报告值。
     • "aggregatable_report_window"：表示时间的字符串（以秒为单位），在此时间之后，触发器数据将不再包含在生成的聚合报告中。
     同样，有关此标头上的所有可用字段的详细说明，请参阅 Attribution-Reporting-Register-Source.
3. 成功注册来源后，浏览器会将其提供的源数据存储在私有的本地缓存中。

导航来源对于衡量链接的交互很有用——例如，用户可能会在发布者的页面上看到一个广告，并点击它以导航到广告主的页面，在那里有望发生转化。

有几种不同类型的基于导航的归因来源（例如，点击广告）可以注册——那些基于 HTML 的来源（使用 attributionsrc 属性）和那些基于 Window.open() 调用的来源（使用 attributionsrc 窗口功能）。

要注册基于导航的归因来源，您可以将 attributionsrc 属性添加到适当的 <a> 元素，该元素指定将发送注册请求的位置。

如果您将属性值留空，则注册请求将发送到要链接到的位置。还可以指定一个或多个附加 URL 在值内部，以便将注册请求发送到这些 URL；有关更多详细信息，请参阅 在 attributionsrc 中指定 URL.

attributionsrc 可以声明式地添加

<a href="https://shop.example" attributionsrc target="_blank">
  Click to visit our shop
</a>

或者通过 HTMLAnchorElement.attributionSrc 属性

const aElem = document.querySelector("a");
aElem.attributionSrc = "";

在这种情况下，交互会发生，当用户点击链接并且浏览器接收到响应时，浏览器会存储与基于导航的归因来源关联的源数据（如 Attribution-Reporting-Register-Source 响应标头中提供的那样）。

您还可以将 attributionsrc 功能关键字添加到 Window.open() 调用的 features 属性中。在此示例中，我们响应 click 事件触发来运行它

elem.addEventListener("click", () => {
  window.open("https://shop.example", "_blank", "attributionsrc");
});

在这种情况下，交互会发生，并且当调用 Window.open() 并且浏览器接收到响应时，浏览器会存储源数据。

基于事件的归因来源会导致浏览器响应某种事件触发存储源数据，例如在 <img> 或 <script> 元素的情况下，load 事件（它们像我们在上面看到的 <a> 元素一样使用 attributionsrc 属性），或者您在 JavaScript 中选择的自定义事件。

基于 HTML 的事件来源可用于衡量发布者页面首次加载时的交互——或者更准确地说，是在 <img> 或 <script> 加载时。要通过 HTML 注册基于事件的归因来源，您可以将 attributionsrc 属性添加到适当的元素——<img> 或 <script>.

如果您将属性值留空，则注册请求将发送到托管所请求资源的服务器。还可以指定一个或多个附加 URL 在值内部，以便将注册请求发送到这些 URL；有关更多详细信息，请参阅 在 attributionsrc 中指定 URL.

让我们来看一个 <img> 元素示例

<img src="advertising-image.png" attributionsrc />

您也可以通过 HTMLImageElement.attributionSrc 属性来实现这一点

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

当浏览器接收到包含图像文件的响应时（即 load 事件发生时），浏览器会存储归因来源数据。请记住，用户可能不一定能够感知图像——它可能是一个仅用于归因报告的 1x1 透明跟踪像素。

以下是一个 <script> 的示例

<script src="advertising-script.js" attributionsrc />

或者通过 HTMLScriptElement.attributionSrc 属性

const scriptElem = document.querySelector("script");
scriptElem.attributionSrc = "";

在这种情况下，浏览器在收到包含脚本的响应时会进行交互，并存储源数据。

基于脚本的归因源比基于 HTML 的归因源更通用。您可以设置一个脚本，以启动符合注册归因源条件的请求，具体取决于您的应用程序适合的任何请求。这是一种灵活的方法，当您想要响应自定义交互（例如，点击自定义元素或提交表单）存储源数据时非常有用。

要设置基于脚本的归因源，您可以：

• 发送包含 attributionReporting 选项的 fetch() 请求
  js

  const attributionReporting = {
    eventSourceEligible: true,
    triggerEligible: false,
  };
  
  // Optionally set keepalive to ensure the request outlives the page
  function triggerSourceInteraction() {
    fetch("https://shop.example/endpoint", {
      keepalive: true,
      attributionReporting,
    });
  }
  
  // Associate the interaction trigger with whatever
  // event makes sense for your code (does not have to be a
  // DOM event/user interaction)
  elem.addEventListener("click", triggerSourceInteraction);
  

• 发送包含 setAttributionReporting() 的 XMLHttpRequest 请求
  js

  const attributionReporting = {
    eventSourceEligible: true,
    triggerEligible: false,
  };
  
  function triggerSourceInteraction() {
    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
  // event makes sense for your code (does not have to be a
  // DOM event/user interaction)
  elem.addEventListener("click", triggerSourceInteraction);
  

在这种情况下，浏览器在收到 fetch 请求的响应时会进行交互，并存储源数据。

到目前为止，在我们看到的所有示例中，attributionsrc 属性/特性或 attributionSrc 属性都留空，取值为一个空字符串。如果持有请求资源的服务器与您想要处理注册的服务器相同（即接收 Attribution-Reporting-Eligible 头部并用 Attribution-Reporting-Register-Source 头部响应），则这没有问题。

但是，请求的资源可能不在您控制的服务器上，或者您只是想要在不同的服务器上处理归因源的注册。在这种情况下，您可以将一个或多个 URL 指定为 attributionsrc 的值。当资源请求发生时，除了资源来源之外，Attribution-Reporting-Eligible 头部还会被发送到 attributionsrc 中指定的 URL(s)；这些 URL 然后可以用 Attribution-Reporting-Register-Source 来注册源。

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

<a
  href="https://shop.example"
  attributionsrc="https://a.example/register-source">
  Click to visit our shop
</a>

或者在 JavaScript 中通过 attributionSrc 属性

// encode the URLs in case they contain special characters
// such as '=' that would be improperly parsed.
const encodedUrlA = encodeURIComponent("https://a.example/register-source");
const encodedUrlB = encodeURIComponent("https://b.example/register-source");

const aElem = document.querySelector("a");
aElem.attributionSrc = `${encodedUrlA} ${encodedUrlB}`;

对于 Window.open() 调用，不同的 URL 必须作为 windowFeatures 参数中的多个单独的 attributionsrc 特性列出，并用逗号或空格隔开

// encode the URLs in case they contain special characters
// such as '=' that would be improperly parsed.
const encodedUrlA = encodeURIComponent("https://a.example/register-source");
const encodedUrlB = encodeURIComponent("https://b.example/register-source");

elem.addEventListener("click", () => {
  window.open(
    "https://ourshop.example",
    "_blank",
    `attributionsrc=${encodedUrlA},attributionsrc=${encodedUrlB}`,
  );
});

• 归因报告头部验证工具