从 API 机制变更到新功能,归因报告提案经过了多项更改以解决社区反馈。
更新日志
- 2022 年 2 月 7 日:添加了有关标头触发器重定向的部分。
- 2022 年 1 月 27 日:首次发布本文。
此信息的适用对象
专为你准备的以下帖子:
- 如果您已经了解该 API(例如,一直在观察或参与有关 WICG 代码库的讨论,并希望了解 2022 年 1 月对该提案所做的批量更改),
- 如果您是在演示或生产环境中的实验中使用 Attribution Reporting API。
如果您刚开始使用此 API 和/或尚未试用过,请直接参阅 API 简介。
提前迁移
在 Chrome 中实现这些更改后:如果您在演示版或正式版实验(源试用)中使用来自 Attribution Reporting API 的事件级报告,则需要修改代码才能使该 API 继续工作。您也可以考虑使用新功能。
本文还列出了针对可汇总报告的变更。不过,这些变更在实施后无需任何操作或迁移,因为在撰写本文时尚未针对可汇总报告实施浏览器。
改名
摘要报告和可汇总报告
您可能已经称为汇总报告的内容现在称为摘要报告。
摘要报告是汇总多个可汇总报告的最终输出,以前称为贡献或直方图贡献。
API 机制变更
基于标头的来源注册(事件级报告)
具体变化和原因
当用户查看或点击广告时,用户设备上的本地浏览器会记录此事件以及归因报告专用参数(如 attributionsourceeventid
、attributiondestination
、attributionexpiry
及其他参数)。这些参数的值由广告技术平台设置。
这些参数的设置方式正在发生变化。
在之前的方案中,这些参数必须包含在客户端:可以作为 HTML 属性包含在锚标记中,也可以作为基于 JS 的调用的参数。必须在点击或查看时已知参数。
在新方案中,这些参数的值将改为在广告技术平台服务器上进行定义。
![基于标头的来源注册示意图](https://developers.google.cn/static/privacy-sandbox/assets/images/blog/diagram-header-based-sou-5d15e921f96f3.png?authuser=6&hl=nb)
这样做有很多好处,特别是在安全性方面:标头机制可让报告来源(通常是广告技术平台)直接控制归因来源是否在其范围内注册。这在一定程度上缓解了欺诈问题,因为有了这项变更,未经报告来源选择启用,正版浏览器绝不会注册来源。
来源注册的工作原理是什么?
- 对于给定的广告,广告技术平台现在需要定义特定的客户端属性
attributionsrc
。此属性的值是浏览器将向其发送请求的网址;该请求将包括一个新的 HTTP 标头Attribution-Reporting-Source-Info
,该标头的值navigation
或event,
分别指定来源是点击还是观看。 - 收到此请求后,点击/观看跟踪服务器应使用包含所需归因参数的 HTTP 标头
Attribution-Reporting-Register-Source
进行响应。 返回此标头的来源现在是报告来源(以前称为
attributionreportto
)。HTTP 响应标头
Attribution-Reporting-Register-Source
:{ "source_event_id": "267630968326743374", "destination": "https://toasters.example", "expiry": "604800000" }
前往技术说明文档了解详情
加入公开讨论
基于标头的归因触发器(事件级报告)
具体变化和原因
与点击或观看注册一样,新提案会将归因触发器(即广告技术平台指示浏览器记录转化时)更改为基于标头的方法。
此机制与基于标头的来源注册一致,并且比之前使用的重定向机制更传统。
此外,在新提案中,转化页上还需要添加 attributionsrc
属性。
原因在于权限:在之前的方案中,触发器端网站(通常是广告主网站)可以通过 Permissions-Policy
标头对该功能进行常规控制,但无法在元素级精确控制元素能否向最终触发归因的一方发送请求。attributionsrc
可以改变这种情况:借助这个强制性标记,广告客户能够监控并控制哪些元素可以触发归因。
请注意,在来源端(通常是发布商网站),具有一个通过 Permissions-Policy
实现的网页级控件,以及一个通过 attributionsrc
实现的元素级控件。
归因触发器的工作原理是什么?
收到像素请求并确定应将其归类为转化后,广告技术平台应使用新的 HTTP
标头 Attribution-Reporting-Register-Event-Trigger
进行响应。
此标头的值用于指定如何将触发器事件视为 JSON 对象。此信息与上一个提案中定义为查询参数的信息相同。
HTTP 响应标头 Attribution-Reporting-Register-Event-Trigger
:
[{
trigger_data: (unsigned 3-bit integer),
trigger_priority: (signed 64-bit integer),
deduplication_key: (signed 64-bit integer)
}]
重定向(可选)
(可选)广告技术平台服务器可以针对包含 Attribution-Reporting-Register-Event-Trigger
的响应做出重定向响应。这样,第三方就可以观察转化事件并指示浏览器进行归因。
重定向是可选的;如果广告技术平台和第三方在网页上均有像素,则不需要重定向。
如需了解详情,请参阅第三方报告。
前往技术说明文档了解详情
加入公开讨论
没有 Worklet(可汇总报告)
具体变化和原因
在之前关于可汇总报告的方案中,需要 JavaScript 访问权限才能调用 Worklet(一种基于 JavaScript 的机制)来生成这些报告。
在新提案中,不需要 Worklet。相反,广告技术平台将通过 HTTP 标头以声明方式定义浏览器在生成可汇总报告时应使用的规则。
新提案具有多项优势:
- 浏览器实现:与 Worklet 设计不同,新设计大大简化,因为它不需要在浏览器中新的执行环境。
- 开发者体验:新设计依赖于开发者广泛使用且广为人知的标头,与 Worklet 不同。它还与来源注册的 API Surface 紧密一致,使该 API 更易于学习和使用。
- 采用:新设计使更多现有衡量系统能够使用可汇总报告。许多衡量解决方案都仅支持 HTTP:它们依赖于不需要 JavaScript 访问的图片请求(像素请求)。但是,由于 Worklet 方法需要 JavaScript 访问,可能很难从某些现有的衡量系统迁移到。
- 稳健性:新设计有助于减少数据丢失,因为它更容易与
keepalive
语义集成,例如,在用户离开页面时是否注册了点击或查看。
无 Worklet 机制的工作原理是什么?
这种声明式机制基于 HTTP 标头,就像事件级来源注册和归因触发器标头一样。下文将对此进行详细介绍。
加入公开讨论
基于标头的来源注册(可汇总报告)
我们提出了一种新机制来为可汇总报告注册来源;此机制与事件级来源注册相同。
只有标头名称不同:Attribution-Reporting-Register-Aggregatable-Source
。
前往技术说明文档了解详情
基于标头的归因触发器(可汇总报告)
我们提出了一种新机制来为可汇总报告注册来源;此机制与事件级归因触发器相同。
只有标头名称不同:Attribution-Reporting-Register-Aggregatable-Trigger-Data
。
前往技术说明文档了解详情
新功能
第三方报告(事件级报告和可汇总报告)
具体变化和原因
新提案的两个方面有助于更好地支持第三方报表用例:
- (可选)广告技术平台可以将网络请求重定向到其他广告技术平台服务器,以便这些其他广告技术平台执行自己的来源和触发器注册。这是目前第三方配置的常见方式。这使得该 API 与其他现有的第三方报告系统一样,更易于采用。
- 报告来源(通常是广告技术平台)不再受大多数隐私保护限制。这支持多个广告技术平台与同一发布商或广告主合作的用例。
第三方报告是如何运作的?
在新方案中,基于响应的来源注册和触发器依赖于 HTTP 标头。广告技术平台可以针对这些请求利用 HTTP 重定向。
如果发布商网站上的一次点击/观看请求(来源注册)随后被重定向到多方,那么每一方都可以注册此观看或点击(来源事件)。
同样,广告技术平台可以重定向来自广告客户网站的特定归因请求,从而允许多方注册转化(归因触发器)。
各方都可以访问各自的报告,并使用单独的数据进行配置。
注册多个无重定向的触发器
您还可以通过在转化端添加多个像素元素(每个触发器一个)注册多个归因触发器,而无需使用重定向。
加入公开讨论
浏览型转化衡量(事件级报告和可汇总报告)
具体变化和原因
在新提案中,“浏览型转化次数”衡量和“点击型转化”衡量采用统一的运作方式:
registerattributionsrc
是视图专用属性,用于指示浏览器记录点击时的浏览次数,而不再是方案的一部分。- 现在,对于点击和观看,隐私权机制是统一的。有关详情,请参阅噪声和透明度。
我们提议进行这项更改,以便与新的基于标头的注册机制保持一致。 此外,打算同时支持点击型衡量和浏览型转化衡量时,这还可以简化开发者体验。
“浏览型转化次数”衡量是如何运作的?
浏览型转化衡量和点击衡量均依赖于基于标头的注册。
前往技术说明文档了解详情
加入公开讨论
调试 / 性能分析(事件级报告和可汇总报告)
具体变化和原因
我们在方案中添加了调试机制,以帮助开发者检测 bug,并将归因报告的性能与现有基于 Cookie 的效果衡量解决方案的性能进行比较。
![基于 Cookie 的新调试系统的示意图](https://developers.google.cn/static/privacy-sandbox/assets/images/blog/diagram-the-cookie-base-60490ad30c9e9.png?authuser=6&hl=nb)
调试是如何进行的?
来源注册和触发器注册都将接受新参数 debug_key
,即 64 位无符号整数(即大数)。
如果创建包含来源和触发器调试键的报告,并且在来源和触发器注册时,报告来源的 Cookie jar 中存在 Samesite=None ar_debug=1
Cookie,则系统会向 .well-known/attribution-reporting/debug
端点发送调试报告 (JSON):
{
"source_debug_key": 1234567890987,
"trigger_debug_key": 4567654345028
}
事件级报告和可汇总报告也将包含这两个新参数,以便与正确的调试报告相关联。
前往技术说明文档了解详情
加入公开讨论
过滤功能(事件级报告和可汇总报告)
具体变化和原因
由于事件级报告和可汇总报告现已支持许多用例,因为它们支持当今广告生态系统中的重要用例:
- 转化过滤:根据来源端信息过滤转化。例如,为广告点击和浏览选择不同的触发器数据(转化数据)。
- 归因不匹配:过滤归因有误的转化;这是一种特定的转化过滤类型。例如,由于 API 中的 etld+1 目标范围,会滤除与错误广告点击/浏览匹配的转化。
过滤功能如何工作?(针对事件级报告)
来源端 JSON 对象中的可选 source_data
字段可以定义浏览器在转换时随后将用于应用过滤逻辑的项。
{
source_event_id: "267630968326743374",
destination: "https://toasters.example",
expiry: "604800000"
source_data: {
conversion_subdomain: ["electronics.megastore"
"electronics2.megastore"],
product: "198764",
// Note that "source_type" will be automatically generated as one of {"navigation", "event"}
}
}
触发器注册现在将接受可选的标头 Attribution-Reporting-Filters
。
HTTP 响应标头 Attribution-Reporting-Filters
:
{
"conversion_subdomain": "electronics.megastore",
"directory": "/store/electronics"
}
或者,也可以使用 filters
字段扩展 Attribution-Reporting-Register-Event-Trigger
标头,以进行选择性过滤,从而根据 source_data
设置 trigger_data
。
如果过滤条件 JSON 中的键与 source_data
中的键匹配,且交集为空,则
完全忽略触发器。
前往技术说明文档了解详情
加入公开讨论
隐私保护方面的变更
噪声和透明度(事件级报告和可汇总报告)
具体变化和原因
在新方案中,对报告的其中一个隐私机制进行了改进:对报告进行随机响应。
这意味着系统会正确报告一些实际转化;在一定百分比的时间里,一些实际转化会被抑制或添加一些虚假转化。
这种新技术具有以下优势:
- 它统一了针对点击和观看的隐私权机制。
- 比起将触发器数据(转化数据)和触发器来源链接噪声分离开来的机制,推断更简单。
- 它建立了一个隐私权框架,通过适当的噪声设置,确保任何一方都不能依赖该 API 确定具体用户是否因为特定广告完成了转化。
这种新机制取代了以前的机制:在 5% 的情况下,触发器数据(转化数据)会被随机值替换。
此外,报告正文(randomized_trigger_rate
字段)中添加了随机响应概率值。此字段用于指定来源受到随机回复的概率(0 到 1)。
这样做有两大好处:
- 这会使底层浏览器行为对将要接收报告的各方(通常是广告技术平台)保持transparent。
- 在未来跨浏览器支持该 API 时,这会非常有用:不同的浏览器可能会根据其隐私目标决定采用不同的噪声水平,并且负责处理报告的各方需要了解这一点。
噪声如何发挥作用?
在新提案中,在注册来源(即记录了广告点击或观看)时,浏览器会随机决定是如实归因转化并发送有关此次广告点击/观看的报告,还是会生成虚假输出。
虚构输出可以是:
- 根本没有报告 - 无论用户是否完成转化;
- 一个或多个虚假举报 - 无论用户是否完成转化。
在虚构报告中,触发器数据(转化数据)是随机的:针对点击使用随机的 3 位值(0 到 7 之间的任何数字),针对观看使用随机的 1 位值(0 或 1)。
与真实报告一样,用户完成转化后,系统不会立即发送虚假报告。系统会在随机报告期结束时发送这些报告。
对于点击次数,有三个报告期(点击后 2 天、7 天或 30 天)。每个虚构报告都会随机分配到其中一个报告期。
另外,正如之前的方案所述,窗口中的报告是随机的。
前往技术说明文档了解详情
加入公开讨论
报告限制(事件级报告和可汇总报告)
具体变化和原因
新提案明确限制了可以衡量两个网站之间事件的各方。
- 针对每个 {publisher, advertiser} 可以注册来源的唯一报告来源(通常是广告技术平台)的数量上限建议为每 30 天 100 个。对于每次广告点击或观看(来源事件),即使是未归因的事件,此计数器也会递增。
- 针对每个 {publisher, advertiser} 可以发送报告的唯一报告来源(通常是广告技术平台)的数量上限建议为每 30 天 10 个。此计数器会针对每次归因转化递增。
这些限制应该足够高,不会限制任何操作者衡量转化的能力,但也足够低,有助于减少某些形式的 API 滥用。
报告冷却期 / 速率限制
具体变化和原因
报告冷却期是一种隐私保护机制,可限制用户在指定时间段内通过此 API 发送的总信息量。
在新提案中,可以按计划在 30 天内为每个 {来源网站、目标、报告来源}(通常是 {publisher, advertiser, adtech})生成 100 份报告。
超出此限制后,浏览器将停止定期生成与这个给定 {source site, destination, reporting origin}(通常为 {publisher, advertiser, adtech})匹配的报告,直到该 {source site, destination, reporting origin}(30 天滚动周期报表数量)降到 100 以下。
前往技术说明文档了解详情
目标页面上限(仅限事件级报告)
具体变化和原因
目标页面上限已修改为包含范围内的报告来源(通常为广告技术平台):每个 {发布商、广告技术平台} 允许 100 个唯一的待处理目标(通常是广告客户网站或预计会发生转化的网站)。
这是隐私保护,旨在限制重新创建浏览记录。
前往技术说明文档了解详情
所有资源
- 请参阅归因报告。
- 请参阅您需了解关于此 API 的注意事项。
标题图片来自 Unsplash 网站 Diana Polekhina。