归因报告 API

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

安全上下文: 此功能仅在 安全上下文 (HTTPS) 中可用,在某些或所有 支持的浏览器 中。

归因报告 API 使开发人员能够衡量转化率——例如,当用户点击一个嵌入在某个网站上的广告,然后继续在供应商网站上购买商品时——然后访问有关这些转化的报告。它在不依赖第三方跟踪 Cookie 的情况下实现这一点。

概念和用法

广告商通常希望衡量有多少用户看到了广告,然后继续查看和购买产品(转化率)。这使他们能够弄清楚哪些广告位置为他们带来了最大的投资回报率 (ROI),以便他们可以相应地调整广告策略。衡量转化率的过程通常包括捕获以下数据:

  • 哪些用户完成了转化(例如购买了商品或注册了服务),以及转化人数。
  • 他们的地理位置。
  • 广告放置在哪些网站上。
  • 出售了多少产品,注册了多少服务等等。
  • 产生了多少收入。

传统上,Web 上的转化率是使用第三方跟踪 Cookie 进行衡量的。广告通常会嵌入网页中 <iframe>,它可以设置一个包含有关用户及其与广告交互的信息的 Cookie。

之后,当用户决定访问广告商的网站时,如果该网站与广告来自同一域,那么该网站可以访问之前由广告设置的第三方 Cookie。然后,广告商可以将来自广告的数据与他们自己的第一方数据相关联,以回答诸如“用户在与来自另一个网站的产品广告互动后是否购买了产品?”之类的问题。

这对用户 隐私 非常不利。此时,来自同一域的任何页面都可以访问该 Cookie,以及嵌入这些页面的网站的信息。令人惊讶的是,大量各方将能够访问这些数据,并根据用户的浏览习惯推断出有关用户的其他数据。

归因报告 API 提供了一种以保护用户隐私的方式衡量广告转化率的方法。

它是如何工作的?

让我们通过一个例子说明归因报告 API 的工作原理。

假设我们有一个在线商店 shop.example(即广告商),它在一个内容网站 news.example(即发布商)上嵌入其产品的广告。广告内容位于 ad.shop.example

在线商店所有者希望衡量有多少用户与广告互动,查看他们网站上的产品页面,并将产品放入购物车。

Image representation of the steps described below

所涉及的步骤如下

  1. 当用户访问 news.example 网站时,可以为用户与嵌入式广告的特定互动注册归因来源。用户可以通过多种方式与页面上的广告互动。为了使广告互动注册归因来源,广告必须发送带有 Attribution-Reporting-Eligible 头部的请求,以指示响应有资格注册归因来源。如果响应包含适当的 Attribution-Reporting-Register-Source 头部,则将完成注册。例如,归因来源可以是
    • 链接。在这种情况下,互动是用户点击链接(通过 <a> 元素直接点击,或者通过 Window.open() 调用点击)。来源在导航请求的响应中注册。
    • 图像,例如广告横幅或 1x1 透明跟踪像素。在这种情况下,互动是用户访问页面。当图像加载时,即当服务器响应图像请求时,将注册来源。
    • 提取请求(即 fetch()XMLHttpRequest)。在这种情况下,可以将互动指定为对您的应用程序有意义的任何内容——例如,提取请求可以由 clicksubmit 事件调用。响应返回后,将注册来源。
  2. 当发生归因来源互动时,Attribution-Reporting-Register-Source 头部中返回的来源数据将存储在私有本地缓存中,该缓存仅可由浏览器访问。此数据包括页面和广告商可用的上下文和第一方数据、收集转化数据的广告技术公司来源,以及您期望来自该广告的转化发生的 一个或多个目的地 (eTLD+1)(即广告商的网站,例如 shop.example)。
  3. 当用户稍后访问 shop.example 时,该网站可以在互动指示转化发生时注册归因触发器(例如,用户点击 shop.example 上的“添加到购物车”按钮)。然后,浏览器将发送一个带有 Attribution-Reporting-Eligible 头部的请求,以指示响应有资格注册归因触发器,如果响应包含适当的 Attribution-Reporting-Register-Trigger 头部,则将完成注册。例如,归因触发器可以是
    • 图像,例如购物车图标或 1x1 透明跟踪像素。在这种情况下,互动是用户访问页面。当图像加载时,即当服务器响应图像请求时,将注册触发器。
    • 提取请求(即 fetch()XMLHttpRequest)。在这种情况下,可以将互动指定为对您的应用程序有意义的任何内容——例如,提取请求可以由 clicksubmit 事件调用。响应返回后,将注册触发器。
  4. 当触发器归因完成时,浏览器尝试将来自 Attribution-Reporting-Register-Trigger 头部的數據与保存在私有本地缓存中的来源数据条目匹配(参见 2.)。有关匹配方法和要求,请参阅 注册归因触发器
  5. 如果匹配成功,浏览器将报告数据发送到通常由广告技术提供商拥有的报告服务器上的端点,以便在那里安全地进行分析。与 Cookie 不同,数据只能提供给您将其发送到的特定网站——不会与其他地方共享数据。这些报告可以是
    • 事件级报告:基于归因来源事件的报告,其中详细的来源数据与粗略的触发器数据相关联。例如,报告可能类似于“ad.shop.example 上的点击 ID 200498 导致了 shop.example 上的购买”,其中“点击 ID 200498”是详细的来源数据,“购买”是粗略的触发器数据。详细的来源数据可能会对来自来源页面的第一方数据或上下文数据进行编码,而触发器数据可能会对来自触发器页面的事件进行编码。
    • 汇总报告:更详细的报告,它将来自来源端和触发器端多个转化的数据组合在一起。例如,“news.example 上的活动 ID 774653 导致了 shop.example 上意大利用户 654 件小部件的销售,总收入为 9540 美元”。编制汇总报告需要使用聚合服务(例如,请参阅 Google 聚合服务)。

有关实现上述步骤所需功能的更多信息,请参阅

  1. 注册归因来源
  2. 注册归因触发器
  3. 生成报告

接口

归因报告 API 没有定义任何独立的接口。

对其他接口的扩展

HTMLAnchorElement.attributionSrcHTMLImageElement.attributionSrcHTMLScriptElement.attributionSrc

attributionSrc 属性允许您以编程方式获取和设置 <a><img><script> 元素上的 attributionsrc 属性。它反映该属性的值。

fetch()Request() 构造函数,attributionReporting 选项

通过 fetch() 生成请求时,这表示您希望响应能够注册归因来源或触发器。

XMLHttpRequest.setAttributionReporting()

通过 XMLHttpRequest 生成请求时,这表示您希望响应能够注册归因来源或触发器。

Window.open()attributionsrc 特性关键字

open() 方法完成时,导致完成归因来源的注册触发浏览器存储关联的来源数据(如 Attribution-Reporting-Register-Source 响应头部中提供的)。请注意,Window.open() 调用不能用于注册归因触发器。

HTML 元素

<a><img><script>attributionsrc 属性

指定您希望浏览器在发送关联资源请求时,同时发送一个 Attribution-Reporting-Eligible 头部信息。在服务器端,该头部信息用于触发在响应中发送一个 Attribution-Reporting-Register-SourceAttribution-Reporting-Register-Trigger 头部信息。在注册归因来源时,这是必需的;在注册归因触发器时,只有在您想要指定一个与 src 属性指向的资源不同的注册服务器时,才需要该头部信息。请注意,<a> 元素不能用于注册归因触发器。

HTTP 头

Attribution-Reporting-Eligible

HTTP 请求,表示相应的响应有资格注册归因来源或触发器。

Attribution-Reporting-Register-Source

HTTP 响应,将页面功能注册为归因来源。它包含在对包含 Attribution-Reporting-Eligible 头部的请求的响应中。

Attribution-Reporting-Register-Trigger

HTTP 响应,将页面功能注册为归因触发器。它包含在对包含 Attribution-Reporting-Eligible 头部的请求的响应中。

Permissions-Policy attribution-reporting 指令

控制当前文档是否允许使用归因报告。

注册和本地测试

要在您的网站中使用归因报告 API,您必须在 隐私沙盒注册流程 中指定它。如果您没有这样做,API 流程将在响应时被阻止,即响应头部信息将被忽略,并且来源和触发器将不会被注册。

您仍然可以在没有注册的情况下本地测试您的归因报告 API 代码。要允许本地测试,请启用以下 Chrome 开发者标志

chrome://flags/#privacy-sandbox-enrollment-overrides

示例

查看 演示:归因报告 API 以获取示例实现(也可以查看 源代码)。

规范

规范
归因报告
# element-attrdef-a-attributionsrc

浏览器兼容性

BCD 表仅在浏览器中加载

另请参阅