有关调试 Attribution Reporting 的第 2 部分(共 3 部分)。设置调试报告。
术语库
- 报告来源是用于设置归因报告来源和触发器标头的来源。浏览器生成的所有报告都会发送到此源。在本指南中,我们使用
https://adtech.example
作为示例报告来源。 - 归因报告(简称“报告”)是包含您请求的衡量数据的最终报告(事件级报告或可汇总报告)。
- 调试报告包含有关归因报告或者来源或触发器事件的其他数据。收到调试报告并不一定表示存在问题!调试报告有两种
- 过渡调试报告是一种调试报告,需要设置 Cookie 才能生成和发送。如果 Cookie 未设置且第三方 Cookie 被弃用,过渡调试报告将不可用。本指南中描述的所有调试报告都是过渡性调试报告。
- 成功调试报告用于跟踪成功生成归因报告。它们与归因报告直接相关。从 Chrome 101(2022 年 4 月)开始,已提供成功调试报告。
- 详细调试报告可以跟踪缺失的报告,并帮助您确定缺失报告的原因。它们分别用于表明浏览器未记录来源或触发器事件(这意味着浏览器不会生成归因报告)以及由于某种原因无法生成或发送归因报告的情况。详细调试报告包含一个
type
字段,用于说明未生成来源事件、触发器事件或归因报告的原因。从 Chrome 109(2023 年 1 月稳定版)开始提供详细调试报告。 - 调试键是您可以在来源端和触发器端设置的唯一标识符。通过调试键,您可以映射基于 Cookie 的转化和基于归因的转化。将系统设置为生成调试报告并设置调试密钥后,浏览器会将这些调试密钥添加到所有归因报告和调试报告中。
如需了解我们的文档中使用的更多概念和关键术语,请参阅 Privacy Sandbox 术语表。
实施方面的问题?
如果您在设置调试报告时遇到任何问题,请在以下位置创建问题: 我们的开发者支持团队 代码库 ,我们将帮助您排查问题。
准备设置调试报告
在设置调试报告之前,请按以下步骤操作:
检查您是否采用了 API 集成方面的最佳实践
检查您的代码是否受功能检测的保护。为了确保 API 未被 Permissions-Policy 屏蔽,请运行以下代码:
if (document.featurePolicy.allowsFeature('attribution-reporting')) { // the Attribution Reporting API is enabled }
如果此功能检测检查返回 true,则允许在 运行检查的上下文(页面)。
(测试阶段无需执行此操作:检查您是否设置了 Permissions-Policy)
修复基本集成问题
虽然调试报告可以帮助您大规模检测和分析丢失情况, 一些集成问题可以在本地检测到。来源和触发器标头 配置错误、JSON 解析问题、不安全的上下文(非 HTTPS)以及 阻碍 API 运行的其他问题会在 开发者工具的问题标签页。
开发者工具问题可能有多种类型。如果您遇到 invalid header
,
请将该标头复制到 标头验证工具中
工具。这个
可帮助您找出并修正引发问题的字段。
![屏幕截图:标头验证工具](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/screenshot-header-valida-6fe8347784caf.png?authuser=8&hl=zh-cn)
设置调试报告:成功报告和详细报告的常见步骤
在报告来源上设置以下 Cookie:
Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
浏览器将检查来源和网站上是否存在此 Cookie 触发器注册。只有在以下情况下,系统才会生成成功调试报告: Cookie。
请注意,您可以在处于“模式”下的浏览器上启用调试报告 B,其中 但会停用第三方 Cookie 以方便测试和准备, 第三方 Cookie 弃用。对于模式 B 下的浏览器,您不需要设置 调试 Cookie 以启用调试报告。跳至第 2 步以设置调试密钥 用于成功调试报告。
第 2 步:设置调试密钥
每个调试密钥都必须是 64 位无符号整数,格式为 base-10 字符串。 为每个调试密钥设置唯一 ID。系统仅会生成成功调试报告 如果设置了调试密钥,则会发生此错误。
- 将源代码端调试键映射到 调试。
- 将触发器端调试键映射到您定义的其他触发时间信息 调试。
例如,您可以设置以下调试键:
- 将 Cookie ID + 来源时间戳作为来源调试键(并捕获相同的时间戳) 时间戳)
- 将 Cookie ID + 触发时间戳作为触发器调试键(并捕获相同的时间戳) 时间戳)
这样,您就可以使用基于 Cookie 的转化信息来 相应的调试报告或归因报告。如需了解详情,请参阅第 3 部分: 实战宝典。
使源代码端调试密钥与 source_event_id
不同,以便您可以
区分来源事件 ID 相同的各个报告。
Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"647775351539539"
}
Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743"
}
设置成功调试报告
本部分中的示例代码会针对上述两种情况生成成功调试报告 事件级报告和可汇总报告。事件级报告和可汇总报告使用 相同的调试密钥。
第 3 步:设置端点以收集成功调试报告
设置端点以收集调试报告。此端点应类似于
主归因端点,并在路径中额外添加一个 debug
字符串:
- 事件级成功调试报告的端点:
https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- aggregatable 成功调试报告的端点:
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- aggregatable 成功调试报告的端点:
触发归因时,浏览器会立即发送调试信息
通过 POST
请求向此端点发送报告。要处理的服务器代码
收到的成功调试报告可能如下所示(此处在节点端点上):
// Handle incoming event-Level Success Debug reports
adtech.post(
'/.well-known/attribution-reporting/debug/report-event-attribution',
async (req, res) => {
// Debug report is in req.body
res.sendStatus(200);
}
);
// Handle incoming aggregatable Success Debug reports
adtech.post(
'/.well-known/attribution-reporting/debug/report-aggregate-attribution',
async (req, res) => {
// Debug report is in req.body
res.sendStatus(200);
}
);
第 4 步:确认您的设置将生成成功调试报告
- 在浏览器中打开
chrome://attribution-internals
。 - 确保选中 Show Debug Reports 复选框, 事件级报告和可汇总报告标签页。
- 打开已实现 Attribution Reporting 的网站。完整播放率 生成归因报告的步骤;相同的步骤 生成成功调试报告。
- 在
chrome://attribution-internals
中:- 检查是否已正确生成归因报告。
- 在事件级报告标签页和可汇总的报告标签页中,
检查是否也生成了成功调试报告。认识他们
带有蓝色
debug
路径。
![屏幕截图:归因内部机制](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/screenshot-attribution-i-e7d3e5d9e396.png?authuser=8&hl=zh-cn)
- 在服务器上,验证端点是否立即收到这些成功消息 调试报告。确保检查事件级和可汇总 成功调试报告。
![屏幕截图:报告源服务器日志](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/screenshot-reporting-ori-89d44854473d7.png?authuser=8&hl=zh-cn)
第 5 步:观察成功调试报告
成功调试报告与归因报告完全相同,两者都包含 来源端和触发器端调试键。
{
"attribution_destination": "https://advertiser.example",
"randomized_trigger_rate": 0.0000025,
"report_id": "7d76ef29-d59e-4954-9fff-d97a743b4715",
"source_debug_key": "647775351539539",
"source_event_id": "760938763735530",
"source_type": "event",
"trigger_data": "0",
"trigger_debug_key": "156477391437535"
}
{
"aggregation_service_payloads": [
{
"debug_cleartext_payload": "omRkYXRhgqJldmFsdWVEAACAAGZidWNrZXRQPPhnkD+7c+wm1RjAlowp3KJldmFsdWVEAAARMGZidWNrZXRQJFJl9DLxbnMm1RjAlowp3GlvcGVyYXRpb25paGlzdG9ncmFt",
"key_id": "d5f32b96-abd5-4ee5-ae23-26490d834012",
"payload": "0s9mYVIuznK4WRV/t7uHKquHPYCpAN9mZHsUGNiYd2G/9cg87Y0IjlmZkEtiJghMT7rmg3GtWVPWTJU5MvtScK3HK3qR2W8CVDmKRAhqqlz1kPZfdGUB4NsXGyVCy2UWapklE/r7pmRDDP48b4sQTyDMFExQGUTE56M/8WFVQ0qkc7UMoLI/uwh2KeIweQCEKTzw"
}
],
"shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"debug_mode\":\"enabled\",\"report_id\":\"4a04f0ff-91e7-4ef6-9fcc-07d000c20495\",\"reporting_origin\":\"https://adtech.example\",\"scheduled_report_time\":\"1669888617\",\"source_registration_time\":\"1669852800\",\"version\":\"0.1\"}",
"source_debug_key": "647775351539539",
"trigger_debug_key": "156477391437535"
}
设置详细调试报告
第 3 步:在来源标头和触发器标头中选择启用详细调试
在两个 Attribution-Reporting-Register-Source
中将 debug_reporting
都设置为 true
。
和 Attribution-Reporting-Register-Trigger
。
Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}
Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}
第 4 步:设置端点以收集详细调试报告
设置端点以收集调试报告。此端点应类似于
并将额外的 debug/verbose
字符串发送到主归因端点
路径:
https://adtech.example/.well-known/attribution-reporting/debug/verbose
生成详细调试报告时,如果来源或触发器
注册后,浏览器会立即通过
POST
请求发送到此端点。用于处理传入的详细消息的服务器代码
调试报告可能如下所示(此处在节点端点上):
// Handle incoming verbose debug reports
adtech.post(
'/.well-known/attribution-reporting/debug/verbose',
async (req, res) => {
// List of verbose debug reports is in req.body
res.sendStatus(200);
}
);
与成功调试报告不同,详细报告只有一个端点。 与事件级报告和汇总报告相关的详细报告都将 发送到同一端点
第 5 步:确认您的设置将生成详细的调试报告
详细调试报告类型有很多,但只要完成 仅使用一种详细调试检查详细调试设置 报告。如果正确生成了这类详细调试报告,并且 这意味着系统将正确提供所有类型的详细调试报告 因为所有详细调试报告都使用相同的 配置并发送到同一端点
- 在浏览器中打开
chrome://attribution-internals
。 - 在您的网站上触发使用归因工具设置的归因(转化)操作
报告。假设没有发生广告互动(展示或点击)
在此转换之前,您应该会收到以下类型的详细调试报告:
将生成
trigger-no-matching-source
。 - 在
chrome://attribution-internals
中,打开 Verbose debug reports(详细调试报告)标签页 并检查trigger-no-matching-source
类型的详细调试报告 已生成。 - 在您的服务器上,验证端点是否立即收到此 详细调试报告。
第 6 步:查看详细调试报告
在触发时生成的详细调试报告包括来源端和 触发器端调试键(如果存在与触发器匹配的来源)。 在来源时生成的详细调试报告包含来源端调试 键。
浏览器发送的包含详细调试报告的请求示例:
[
{
"body": {
"attribution_destination": "http://arapi-advertiser.localhost",
"randomized_trigger_rate": 0.0000025,
"report_id": "92b7f4fd-b157-4925-999e-aad6361de759",
"source_debug_key": "282273499788483",
"source_event_id": "480041649210491",
"source_type": "event",
"trigger_data": "1",
"trigger_debug_key": "282273499788483"
},
"type": "trigger-event-low-priority"
},
{
"body": {
"attribution_destination": "http://arapi-advertiser.localhost",
"limit": "65536",
"source_debug_key": "282273499788483",
"source_event_id": "480041649210491",
"source_site": "http://arapi-publisher.localhost",
"trigger_debug_key": "282273499788483"
},
"type": "trigger-aggregate-insufficient-budget"
}
]
每份详细报告包含以下字段:
Type
- 导致生成报告的原因。全面了解所有详细情况 以及根据每种类型应采取的操作,请参阅 详细报告参考(第 3 部分:调试) 实战宝典。
Body
- 报告的正文。具体取决于其类型。查看详细内容 报告参考第 3 部分:调试 实战宝典。
请求正文将包含至少 1 到最多 2 份详细报告:
- 如果失败只影响事件级报告(或者如果失败情况 只会影响可汇总报告)。来源或触发器注册失败 只有一个原因;因此每次失败可生成一份详细报告 和报告类型(事件级或可汇总)。
- 如果失败同时影响事件级和可汇总,请提供两份详细报告
但有一个例外情况:如果事件级的失败原因相同
和可汇总报告,系统只会生成一份详细报告(例如:
trigger-no-matching-source
)