基本流程
当触发器与源匹配时，浏览器会生成一份报告，并通过未经身份验证的 POST 请求将其发送到报告来源上的特定端点。
- 对于事件级报告，端点是
<reporting-origin>/.well-known/attribution-reporting/report-event-attribution。 - 对于汇总报告，端点是
<reporting-origin>/.well-known/attribution-reporting/report-aggregate-attribution。
<reporting-origin> 将与注册源和触发器的来源相同。
报告数据包含在 JSON 结构中。
事件级报告
事件级报告生成后，会安排在其所属的报告窗口结束时发送。报告窗口的长度由源的 Attribution-Reporting-Register-Source 头部中设置的 "event_report_window" 或 "event_report_windows" 字段的值决定。
如果这两个字段都没有指定，报告窗口将回退到以下默认值：
- 对于基于事件的源，默认报告窗口在源的过期时间结束，该时间在
Attribution-Reporting-Register-Source"expiry"字段中设置。如果未明确设置，则默认为注册后 30 天。 - 对于基于导航的源，默认报告窗口是 2 天、7 天和源的
"expiry"。
有关更多详细信息，请参阅自定义报告窗口。
一旦事件级报告在适当的端点收到，数据的处理、存储和显示方式完全由开发者决定。典型的事件级报告可能如下所示：
{
"attribution_destination": "https://advertiser.example",
"source_event_id": "412444888111012",
"trigger_data": "4",
"report_id": "123e4567-e89b-12d3-a456-426614174000",
"source_type": "navigation",
"randomized_trigger_rate": 0.34,
"scheduled_report_time": "1692255696",
"source_debug_key": 647775351539539,
"trigger_debug_key": 647776891539539
}
属性如下：
"attribution_destination"-
一个字符串，或一个包含 2-3 个字符串的数组，取决于源是否注册了多个目标。这些字符串表示在源注册中通过关联的
Attribution-Reporting-Register-Source响应头部设置的归因"destination"站点。 "source_event_id"-
一个字符串，表示归因源 ID。这等于在源注册中设置的
"source_event_id"（通过关联的Attribution-Reporting-Register-Source响应头部）。 "trigger_data"-
一个字符串，表示源自归因触发器的数据，在触发器注册中设置（通过关联的
Attribution-Reporting-Register-Trigger响应头部设置的"trigger_data"）。 "report_id"-
一个字符串，表示此报告的通用唯一标识符 (UUID)，可用于防止重复计数。
"source_type""randomized_trigger_rate"-
一个介于 0 和 1 之间的随机数，表示对于此特定源配置，噪声应用的频率。
"scheduled_report_time"-
一个字符串，表示从 Unix Epoch 到浏览器最初计划发送报告的秒数（以避免由于离线设备延迟报告而导致的不准确）。
"source_debug_key"可选-
一个 64 位无符号整数，表示归因源的调试键。这与关联的
Attribution-Reporting-Register-Source头部中"debug_key"字段设置的值相同。有关更多信息，请参阅调试报告。 "trigger_debug_key"可选-
一个 64 位无符号整数，表示归因触发器的调试键。这与关联的
Attribution-Reporting-Register-Trigger头部中"debug_key"字段设置的值相同。有关更多信息，请参阅调试报告。
汇总报告
汇总报告由在适当端点收到的多个可聚合报告创建，然后进行批处理，以准备由聚合服务处理。一旦发生这种情况，数据的处理、存储和显示方式完全由开发者决定。
可聚合报告默认在触发器交互后生成并安排发送，并带有随机延迟以帮助模糊时间并提高隐私。对于给定的注册归因源，归因源事件将从注册到源过期一直记录——这被称为报告窗口。
过期时间由关联的 Attribution-Reporting-Register-Source 头部中设置的 expiry 值定义，如果未明确设置，则默认为注册后 30 天。请记住，报告窗口的长度可以通过在 Attribution-Reporting-Register-Source 头部中设置 aggregatable_report_window 值来进一步修改。有关更多详细信息，请参阅自定义报告窗口。
注意： 为了进一步保护用户隐私，与每个归因源关联的汇总报告值具有有限的总值——这被称为贡献预算。此值在 API 的不同实现中可能有所不同；在 Chrome 中，它为 65,536。任何生成超过此限制的报告的转换都不会被记录。请务必跟踪预算并在您尝试衡量的不同指标之间共享。
典型的可聚合报告可能如下所示：
{
"shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"report_id\":\"123e4567-e89b-12d3-a456-426614174000\",\"reporting_origin\":\"https://reporter.example\",\"scheduled_report_time\":\"1692255696\",\"source_registration_time\":\"1692230400\",\"version\":\"3\"}",
"aggregation_service_payloads": [
{
"payload": "[base64-encoded HPKE encrypted data readable only by the aggregation service]",
"key_id": "[string identifying public key used to encrypt payload]",
"debug_cleartext_payload": "[base64-encoded unencrypted payload]"
}
],
"aggregation_coordinator_origin": "https://publickeyservice.aws.privacysandboxservices.com",
"source_debug_key": 647775351539539,
"trigger_debug_key": 647776891539539
}
属性如下：
-
这是一个序列化的 JSON 对象，提供聚合服务将用于汇总报告的信息。此数据使用AEAD进行加密，以防止篡改。序列化字符串中包含以下属性：
"api"-
一个枚举值，表示触发报告生成的 API。目前它总是等于
"attribution-reporting"，但将来可能会扩展其他值以支持其他 API。 "attribution_destination"-
一个字符串，表示在源注册中设置的归因
"destination"URL（通过关联的Attribution-Reporting-Register-Source响应头部）。 "report_id"-
一个字符串，表示此报告的通用唯一标识符 (UUID)，可用于防止重复计数。
"reporting_origin"-
触发报告生成的来源。
"scheduled_report_time"-
一个字符串，表示从 Unix Epoch 到浏览器最初计划发送报告的秒数（以避免由于离线设备延迟报告而导致的不准确）。
"source_registration_time"-
一个字符串，表示从 Unix Epoch 到归因源注册的秒数，四舍五入到一整天。
"version"-
一个字符串，表示用于生成报告的 API 版本。
"aggregation_service_payloads"-
一个对象数组，表示包含聚合服务用于组装报告中数据的直方图贡献的有效载荷对象。目前，每个报告仅支持一个由浏览器配置的有效载荷。将来可能会支持多个可自定义的有效载荷。每个有效载荷对象可以包含以下属性：
"payload"-
一个通过 HPKE 加密，然后进行 base64 编码的 CBOR 映射，其结构如下（仅使用 JSON 进行表示）：
json{ "operation": "histogram", "data": [ { "bucket": "<Encoded as a 16-byte (i.e. 128-bit) big-endian bytestring>", "value": "<Encoded as a 4-byte (i.e. 32-bit) big-endian bytestring>" } // … ] }operation始终是"histogram"；它允许服务将来支持其他操作。 "key_id"-
一个字符串，标识用于加密有效载荷的公钥。
"debug_cleartext_payload"可选-
可选的调试信息。
"aggregation_coordinator_origin"-
聚合服务的部署选项。
"source_debug_key"可选-
一个 64 位无符号整数，表示归因源的调试键。这与关联的
Attribution-Reporting-Register-Source头部中"debug_key"字段设置的值相同。有关更多信息，请参阅调试报告。 "trigger_debug_key"可选-
一个 64 位无符号整数，表示归因触发器的调试键。这与关联的
Attribution-Reporting-Register-Trigger头部中"debug_key"字段设置的值相同。有关更多信息，请参阅调试报告。
为报告添加噪声
为了模糊与特定源相关的输出，从而保护用户隐私，报告中会添加噪声。确切的源数据无法识别并归因于单个用户，但从数据中获取的总体模式仍将提供相同的含义。
有关归因报告中噪声工作原理的信息，请参阅：
报告优先级和限制
默认情况下，所有归因源具有相同的优先级，归因模型是最后一次触摸，这意味着转换归因于最近匹配的源事件。对于事件级报告和可聚合报告，您都可以通过在关联的 Attribution-Reporting-Register-Source 头部中设置 "priority" 字段的新值来更改源优先级。默认值为 0；如果您在特定源上设置 "priority" 值为 1，则该源将首先匹配，排在任何优先级为 0 的源之前。优先级为 "2" 的源将排在优先级为 "1" 的源之前匹配，依此类推。
归因触发器优先级的工作方式相同；您还可以通过在关联的 Attribution-Reporting-Register-Trigger 头部中添加 "priority" 字段来设置触发器优先级，但仅适用于事件级报告。
不同的源类型具有不同的默认限制：
- 基于导航的归因源默认有三个报告限制。例如，假设用户点击广告并转换了四次：他们访问了广告客户网站主页，然后访问了产品页面，注册了新闻通讯，最后进行了购买。购买报告将被丢弃，因为它来自第四次转换。
- 基于事件的归因源默认有一个报告限制。
注意： 报告限制可以通过在关联的 Attribution-Reporting-Register-Source 头的 "event_report_windows" 字段中设置不同数量的 "end_times" 来调整。
当为给定源事件触发归因时，如果该源的归因最大数量（点击为三次，图像/脚本为一次）已达到，浏览器将：
- 比较新报告的优先级与该相同源的现有计划报告的优先级。
- 删除优先级最低的报告，以安排新报告。如果新报告是优先级最低的报告，则将其忽略，您将不会收到它。
如果未设置优先级，浏览器将回退到其默认行为：对于点击，第三次转换之后或对于视图，第一次转换之后发生的任何转换都将被丢弃。
过滤器
您可以使用过滤器来定义哪些转换生成报告。例如，您可以选择仅计算特定产品类别的转换，并过滤掉其他类别的转换。
要声明过滤器：
-
在源注册时，向
Attribution-Reporting-Register-Source头部添加filter_data字段，该字段定义您将在触发器端用于过滤转换的过滤器键。这些是完全自定义的字段。例如，要仅指定特定子域和特定产品的转换：json{ "filter_data": { "conversion_subdomain": [ "electronics.megastore", "electronics2.megastore" ], "product": ["1234"] } } -
在触发器注册时，向
Attribution-Reporting-Register-Trigger头部添加filters字段。例如，以下内容导致触发器交互与上述源注册匹配，因为它们都包含"electronics.megastore""conversion_subdomain"字段。另一方面，当尝试匹配时，"directory"过滤器被忽略，因为它未包含在上述源注册中。json{ "filters": { "conversion_subdomain": ["electronics.megastore"], "directory": ["/store/electronics"] } }
如果 "filter_data" 和 "filters" 字段包含匹配的子字段（如上例中的 "conversion_subdomain"），但所有子字段的值都不匹配，则触发器将被忽略，导致不匹配。
过滤触发器数据
Attribution-Reporting-Register-Trigger 头部中的 event_trigger_data 字段可以扩展以进行选择性过滤，从而根据 Attribution-Reporting-Register-Source 头部中定义的 filter_data 设置 trigger_data、priority 或 deduplication_key。
例如
{
"event_trigger_data": [
{
"trigger_data": "2",
"filters": { "source_type": ["navigation"] }
},
{
"trigger_data": "1",
"filters": { "source_type": ["event"] }
}
]
}
注意： "source_type" 是源 "filter_data" 上自动填充的字段。
注意： 也支持 not_filters，它通过否定进行过滤。
在此上下文中，filters 可以是对象或对象数组。指定列表时，只需匹配一个字典即可视为触发器匹配。
{
"event_trigger_data": [
{
"trigger_data": "2",
"filters": [
{
"product": ["1234"],
"conversion_subdomain": ["electronics.megastore"]
},
{
"product": ["4321"],
"conversion_subdomain": ["electronics4.megastore"]
}
]
}
]
}
如果过滤器与任何事件触发器都不匹配，则不会创建事件级报告。如果过滤器与多个事件触发器匹配，则使用第一个匹配的事件触发器。
调试报告
您可以启用调试报告以返回有关归因报告的故障排除信息。例如，这些报告可用于检查您的设置是否正常工作，并了解您的旧版基于 Cookie 的实现与新版归因报告实现之间测量结果的差距。调试报告会立即发送；它们不受事件级报告和汇总报告的相同调度限制。
有两种不同类型的调试报告：
- 成功调试报告跟踪特定归因报告的成功生成。成功调试报告在相应触发器注册后立即生成并发送。
- 详细调试报告让您更深入地了解与归因报告关联的归因源和归因触发器事件。它们使您能够确保源已成功注册，或跟踪缺失的报告并确定其缺失的原因（例如由于源或触发器事件注册失败或发送或生成报告失败）。详细调试报告在源或触发器注册后立即发送。
注意： 要使用调试报告，报告来源需要设置一个 cookie。如果配置为接收报告的来源是第三方，则此 cookie 将是第三方 cookie，这意味着在禁用/不可用第三方 cookie 的浏览器中，调试报告将不可用。
使用调试报告
要使用调试报告，您需要：
-
在您的报告来源上设置
ar_debugcookie。这在源注册和触发器注册期间都需要存在。httpSet-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly -
在任何您希望公开调试信息的归因报告相关的
Attribution-Reporting-Register-Source和Attribution-Reporting-Register-Trigger响应头部中设置debug_key字段。每个debug_key值必须是格式化为十进制字符串的 64 位无符号整数。使每个调试键成为唯一的 ID——例如，您可以将每个键设置为 Cookie ID + 源/触发器时间戳（如果您想比较两者，可以在旧的基于 Cookie 的系统中捕获相同的时间戳）。json{ "debug_key": "647775351539539" }注意： 使源侧调试键与
source_event_id不同，这样您就可以区分具有相同源事件 ID 的单个报告。 -
（可选）在
Attribution-Reporting-Register-Source和Attribution-Reporting-Register-Trigger头部中将debug_reporting字段设置为true。如果这样做，将生成一份详细调试报告。如果未这样做，将生成一份反映您正在生成的归因报告类型（事件级或可聚合）的成功调试报告。json{ "debug_key": "647775351539539", "debug_reporting": true } -
设置适当的端点以接收您要生成的调试报告。调试报告发送到报告来源中的三个单独端点：
- 事件级成功调试报告的端点：
<reporting-origin>/.well-known/attribution-reporting/debug/report-event-attribution - 可聚合成功调试报告的端点：
<reporting-origin>/.well-known/attribution-reporting/debug/report-aggregate-attribution - 详细调试报告的端点：
<reporting-origin>/.well-known/attribution-reporting/debug/verbose
- 事件级成功调试报告的端点：
生成的成功调试报告与归因报告相同，并在 "source_debug_key" 和 "trigger_debug_key" 字段中分别包含源侧和触发器侧调试键。
有关更多信息和示例，请参阅：