生成归因报告

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

本文介绍了如何生成归因报告 API 报告（包括归因报告和调试报告），以及如何控制生成的报告。这包括处理噪声、设置报告优先级、过滤报告和生成调试报告。

基本流程

当触发器与来源之间发生匹配时，浏览器会生成一个报告，并通过一个未经身份验证的 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"。

有关更多详细信息，请参阅自定义报告窗口。

在适当的端点收到事件级报告后，如何处理、存储和显示数据完全取决于开发人员。典型的事件级报告可能如下所示

json

{
  "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": 一个等于 "navigation" 或 "event" 的字符串，分别表示关联的归因来源是基于导航的还是基于事件的。
"randomized_trigger_rate": 一个介于 0 和 1 之间的随机数，表示针对此特定来源配置应用噪声的频率。
"scheduled_report_time": 一个表示从 Unix 纪元开始到浏览器最初安排发送报告的时间（以秒为单位）的字符串（以避免由于脱机设备延迟报告而导致的不准确性）。
"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。任何会生成报告并将值添加到超过此限制的转换都不会被记录。请确保跟踪预算并在您尝试衡量的不同指标之间共享它。

典型的可聚合报告可能如下所示

json

{
  "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
}

属性如下所示

"shared_info"

这是一个序列化 JSON 对象，提供聚合服务将用于汇总汇总报告的信息。此数据使用 AEAD 进行加密以防止篡改。序列化字符串中表示以下属性

"api": 一个枚举值，表示触发报告生成的 API。目前这将始终等于 "attribution-reporting"，但将来可能会扩展其他值以支持其他 API。
"attribution_destination": 一个表示在来源注册中设置的归因 "destination" URL 的字符串（通过关联的 Attribution-Reporting-Register-Source 响应标头）。
"report_id": 一个表示此报告的通用唯一标识符 (UUID) 的字符串，可用于防止重复计数。
"reporting_origin": 触发报告生成的来源。
"scheduled_report_time": 一个表示从 Unix 纪元开始到浏览器最初安排发送报告的时间（以秒为单位）的字符串（以避免由于脱机设备延迟报告而导致的不准确性）。
"source_registration_time": 一个表示从 Unix 纪元开始到注册归因来源的时间（以秒为单位）的字符串，向下舍入到整日。
"version": 一个表示用于生成报告的 API 版本的字符串。

"aggregation_service_payloads"

一个对象数组，表示包含聚合服务用于组装报告中包含的数据的直方图贡献的有效负载对象。目前，每个报告仅支持单个有效负载，由浏览器配置。将来可能会支持多个可自定义的有效负载。每个有效负载对象可以包含以下属性

"payload"

一个 CBOR 映射，通过 HPKE 加密，然后进行 base64 编码，其结构如下

{
  "operation": "histogram",  // Allows for the service to support other operations in the future
  "data": [{
    "bucket": <bucket, encoded as a 16-byte (i.e. 128-bit) big-endian bytestring>,
    "value": <value, encoded as a 4-byte (i.e. 32-bit) big-endian bytestring>
  }, ...]
}

"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的来源之前。优先级为"priority": "2"的来源将在"priority": "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字段可以扩展为进行选择性过滤以设置trigger_data、priority或deduplication_key，基于Attribution-Reporting-Register-Source标头中定义的filter_data。

例如

json

{
  "event_trigger_data": [
    {
      "trigger_data": "2",
      "filters": { "source_type": ["navigation"] }
    },
    {
      "trigger_data": "1",
      "filters": { "source_type": ["event"] }
    }
  ]
}

注意："source_type"是来源的"filter_data"上自动填充的字段。

注意：也支持使用否定进行过滤的not_filters。

在此上下文中，filters可以是对象或对象数组。当指定列表时，只需要一个字典匹配即可考虑触发器。

json

{
  "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_debug Cookie。这需要在来源和触发器注册期间都存在。
http
```
Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
```
在与您想要公开调试信息的归因报表相关的任何Attribution-Reporting-Register-Source和Attribution-Reporting-Register-Trigger响应标头中设置debug_key字段。每个debug_key值必须是格式化为基数 10 字符串的 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"字段中分别包含来源端和触发器端的调试键。

有关更多信息和示例，请参阅

调试报表的简介在 developers.google.com 上 (2023)
设置调试报表在 developers.google.com 上 (2023)
调试指南在 developers.google.com 上 (2023)