关于调试归因报告的第 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,则系统会在运行该检查的上下文(页面)中允许该 API。
(测试阶段不需要:检查您是否设置了 Permissions-Policy)
解决基本集成问题
虽然调试报告有助于您大规模检测和分析损失,但一些集成问题可在本地检测出来。开发者工具问题标签页中会显示来源和触发器标头配置错误、JSON 解析问题、不安全上下文(非 HTTPS)以及其他阻止 API 正常运行的问题。
开发者工具问题可能有多种类型。如果您遇到 invalid header
问题,请将标头复制到标头验证工具中。这将有助于您找出并修正导致问题的字段。
![屏幕截图:标头验证工具](https://developers.google.cn/static/privacy-sandbox/assets/images/screenshot-header-valida-6fe8347784caf.png?authuser=3&hl=da)
设置调试报告:成功报告和详细报告通用的步骤
在报告来源上设置以下 Cookie:
Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
浏览器将在来源注册和触发器注册时检查是否存在此 Cookie。仅当 Cookie 同时存在时,系统才会生成成功调试报告。
请注意,可以为处于模式 B 的浏览器启用调试报告,在模式 B 下,系统会停用第三方 Cookie,以方便测试和准备弃用第三方 Cookie。对于模式 B 的浏览器,您无需设置调试 Cookie 即可启用调试报告。跳至第 2 步,为成功调试报告设置调试密钥。
第 2 步:设置调试密钥
每个调试密钥都必须是一个 64 位无符号整数,格式为以 10 为底数的字符串。 将每个调试密钥设为唯一 ID。只有在设置了调试密钥时,系统才会生成成功调试报告。
- 将源代码端调试密钥映射到您认为与调试相关的其他源代码时信息。
- 将触发器端调试键映射到您认为与调试相关的其他触发器时间信息。
例如,您可以设置以下调试键:
- 作为来源调试键的 Cookie ID + 来源时间戳(并在基于 Cookie 的系统中捕获相同的时间戳)
- Cookie ID + 触发器时间戳作为触发器调试键(并在基于 Cookie 的系统中捕获相同的时间戳)
这样,您就可以使用基于 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
- 可汇总的成功调试报告的端点:
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- 可汇总的成功调试报告的端点:
触发归因后,浏览器会立即通过 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
。 - 确保已选中“事件级报告”和“可汇总报告”标签页中的“显示调试报告”复选框。
- 打开已实现归因报告的网站。完成用于生成归因报告的步骤;这些步骤将生成成功调试报告。
- 在
chrome://attribution-internals
中:- 检查是否已正确生成归因报告。
- 在“事件级报告”和“可汇总的报告”标签页中,检查是否也生成了成功调试报告。使用蓝色
debug
路径在列表中识别它们。
![屏幕截图:归因工具内部](https://developers.google.cn/static/privacy-sandbox/assets/images/screenshot-attribution-i-e7d3e5d9e396.png?authuser=3&hl=da)
- 在您的服务器上,验证您的端点是否会立即收到这些成功调试报告。请务必查看事件级成功调试报告和可汇总的成功调试报告。
![屏幕截图:报告源服务器日志](https://developers.google.cn/static/privacy-sandbox/assets/images/screenshot-reporting-ori-89d44854473d7.png?authuser=3&hl=da)
第 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
和 Attribution-Reporting-Register-Trigger
中将 debug_reporting
设置为 true
。
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
中,打开详细调试报告标签页,然后检查是否已生成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 部分:调试实战宝典中的详细报告参考文档。
请求正文至少包含两个详细报告:
- 如果失败结果仅影响事件级报告(或者仅影响可汇总报告),则生成一份详细报告。来源或触发器注册失败的原因只有一种;因此,系统可以针对每种失败和每种报告类型(事件级或可汇总)生成一份详细报告。
- 如果失败同时影响事件级报告和可汇总报告,则提供两种详细报告,但有一个例外情况:如果事件级报告和可汇总报告的失败原因相同,则仅生成一份详细报告(例如:
trigger-no-matching-source
)