From 5e414fd9b9e6f7f69be8cc1fb3a7a68ccea4f323 Mon Sep 17 00:00:00 2001 From: Allo Date: Mon, 9 Sep 2024 15:49:19 +0800 Subject: [PATCH] fix translation ref: https://developer.android.com/design-for-safety/privacy-sandbox/guides/attribution?hl=zh-cn --- .../generating_reports/index.md | 70 ++++++------ .../api/attribution_reporting_api/index.md | 22 ++-- .../registering_sources/index.md | 104 +++++++++--------- .../registering_triggers/index.md | 32 +++--- 4 files changed, 117 insertions(+), 111 deletions(-) diff --git a/files/zh-cn/web/api/attribution_reporting_api/generating_reports/index.md b/files/zh-cn/web/api/attribution_reporting_api/generating_reports/index.md index 0e8a055a7ff830..1586a30982b5aa 100644 --- a/files/zh-cn/web/api/attribution_reporting_api/generating_reports/index.md +++ b/files/zh-cn/web/api/attribution_reporting_api/generating_reports/index.md @@ -1,6 +1,8 @@ --- title: 生成归因报告 slug: Web/API/Attribution_Reporting_API/Generating_reports +l10n: + sourceCommit: f430d277573ba0b06b1ac33ae8017fd90f170bef --- {{SeeCompatTable}}{{DefaultAPISidebar("Attribution Reporting API")}} @@ -14,7 +16,7 @@ slug: Web/API/Attribution_Reporting_API/Generating_reports - 对于事件级报告，端点为 `/.well-known/attribution-reporting/report-event-attribution`。 - 对于汇总报告，端点为 `/.well-known/attribution-reporting/report-aggregate-attribution`。 -`` 与注册来源和触发器的源相同。 +`` 与注册的来源（source）和触发器同源（same-origin）。 报告数据包含在一个 JSON 结构中。 @@ -24,8 +26,8 @@ slug: Web/API/Attribution_Reporting_API/Generating_reports 如果未指定这些字段，报告窗口将回退到以下默认值： -- 对于[基于事件的来源](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于事件的归因源)，默认报告窗口在来源的 `"expiry"` 到期时结束，该值在 `Attribution-Reporting-Register-Source` 的 [`"expiry"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#expiry) 字段中设置。如果未显式设置，则默认为注册后 30 天。 -- 对于[基于导航的来源](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于导航的归因源)，默认报告窗口分别为 2 天、7 天和来源的 `"expiry"`。 +- 对于[基于事件的来源](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于事件的归因来源)，默认报告窗口在来源的 `"expiry"` 到期时结束，该值在 `Attribution-Reporting-Register-Source` 的 [`"expiry"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#expiry) 字段中设置。如果未显式设置，则默认为注册后 30 天。 +- 对于[基于导航的来源](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于导航的归因来源)，默认报告窗口分别为 2 天、7 天和来源的 `"expiry"`。 有关详细信息，请参阅[自定义报告窗口](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/custom-report-windows)。 @@ -50,43 +52,43 @@ slug: Web/API/Attribution_Reporting_API/Generating_reports - `"attribution_destination"` - : 一个字符串，或者是一个包含 2-3 个字符串的数组，取决于来源是否注册了多个目标。这些字符串代表在来源注册时通过关联的 {{httpheader("Attribution-Reporting-Register-Source")}} 响应标头中设置的归因 [`"destination"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#destination) 站点。 - `"source_event_id"` - - : 一个表示归因源 ID 的字符串。这等同于在来源注册时通过关联的 {{httpheader("Attribution-Reporting-Register-Source")}} 响应标头中设置的 [`"source_event_id"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#source_event_id)。 + - : 一个表示归因来源 ID 的字符串。这等同于在来源注册时通过关联的 {{httpheader("Attribution-Reporting-Register-Source")}} 响应标头中设置的 [`"source_event_id"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#source_event_id)。 - `"trigger_data"` - : 一个表示归因触发器来源数据的字符串，在触发器注册时设置（通过关联的 {{httpheader("Attribution-Reporting-Register-Trigger")}} 响应标头设置的 [`"trigger_data"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Trigger#trigger_data)）。 - `"report_id"` - : 一个表示此报告的[通用唯一标识符（UUID）](/zh-CN/docs/Glossary/UUID)的字符串，可用于防止重复计算。 - `"source_type"` - - : 一个字符串，值为 `"navigation"` 或 `"event"`，分别表示相关的归因源是[基于导航的](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于导航的归因源)，还是[基于事件的](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于事件的归因源)。 + - : 一个字符串，值为 `"navigation"` 或 `"event"`，分别表示相关的归因来源是[基于导航的](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于导航的归因来源)，还是[基于事件的](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于事件的归因来源)。 - `"randomized_trigger_rate"` - - : 一个介于 0 和 1 之间的随机数，表示此特定来源配置应用噪声的频率。[噪声](#为报告添加噪声)处理见下文。 + - : 一个介于 0 和 1 之间的随机数，表示此特定来源配置应用[噪声](#为报告添加噪声)的频率。 - `"scheduled_report_time"` - : 一个字符串，表示从 Unix 纪元开始到浏览器最初计划发送报告的秒数（以避免因设备离线导致报告延迟而产生的不准确性）。 - `"source_debug_key"` {{optional_inline}} - - : 一个 64 位无符号整数，表示归因源的调试密钥。此值与关联的 {{httpheader("Attribution-Reporting-Register-Source")}} 标头中的 [`"debug_key"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#debug_key) 字段中设置的值相同。有关更多信息，请参阅[调试报告](#调试报告)。 + - : 一个 64 位无符号整数，表示归因来源的调试密钥。此值与关联的 {{httpheader("Attribution-Reporting-Register-Source")}} 标头中的 [`"debug_key"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#debug_key) 字段中设置的值相同。有关更多信息，请参阅[调试报告](#调试报告)。 - `"trigger_debug_key"` {{optional_inline}} - : 一个 64 位无符号整数，表示归因触发器的调试密钥。此值与关联的 {{httpheader("Attribution-Reporting-Register-Trigger")}} 标头中的 `"debug_key"` 字段中设置的值相同。有关更多信息，请参阅[调试报告](#调试报告)。 ## 汇总报告 -汇总报告是从收到的多个可聚合报告创建的，并随后[批处理](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/summary-reports-intro#batching)以准备由[聚合服务](https://developers.google.com/privacy-sandbox/private-advertising/aggregation-service)处理。此后，数据如何处理、存储和显示完全取决于开发者。 +汇总报告是从收到的多个可汇总报告创建的，并随后[批处理](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/summary-reports-intro#batching)以准备由[汇总服务](https://developers.google.com/privacy-sandbox/private-advertising/aggregation-service)处理。此后，数据如何处理、存储和显示完全取决于开发者。 -默认情况下，可聚合报告是在触发器交互后生成并计划发送的，带有随机延迟以帮助模糊时序并提高隐私性。对于给定的已注册归因源，从注册到来源过期期间会记录归因源事件——这称为**报告窗口**。 +默认情况下，可汇总报告是在触发器交互后生成并计划发送的，带有随机延迟以帮助模糊时序并提高隐私性。对于给定的已注册归因来源，从注册到来源过期期间会记录归因来源事件——这称为**报告窗口**。 到期时间由关联的 {{httpheader("Attribution-Reporting-Register-Source")}} 标头中的 `expiry` 值定义，如果未明确设置，则默认为注册后 30 天。请注意，可以通过在 `Attribution-Reporting-Register-Source` 标头中设置 `aggregatable_report_window` 值来进一步修改报告窗口的长度。有关详细信息，请参阅[自定义报告窗口](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/custom-report-windows)。 > [!NOTE] -> 为了进一步保护用户隐私，每个归因源相关的汇总报告值具有有限的总值——这称为**贡献预算**。此值可能因 API 的不同实现而有所不同；在 Chrome 中为 65,536。任何生成报告的转换操作导致的总值超出此限制将不被记录。请确保跟踪预算并在你尝试测量的不同指标之间共享它。 +> 为了进一步保护用户隐私，每个归因来源相关的汇总报告值具有有限的总值——这称为**贡献预算**。此值可能因 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 编码的 HPKE 加密数据，仅供聚合服务读取]", - "key_id": "[标识用于加密负载的公钥的字符串]", - "debug_cleartext_payload": "[base64 编码的未加密负载]" + "payload": "[base64 编码的 HPKE 加密数据，仅供汇总服务读取]", + "key_id": "[标识用于加密有效负载的公钥的字符串]", + "debug_cleartext_payload": "[base64 编码的未加密有效负载]" } ], "aggregation_coordinator_origin": "https://publickeyservice.aws.privacysandboxservices.com", @@ -98,24 +100,24 @@ slug: Web/API/Attribution_Reporting_API/Generating_reports 属性如下： - `"shared_info"` - - : 这是一个序列化的 JSON 对象，提供汇总报告服务使用的信息。这些数据使用 [AEAD](https://zh.wikipedia.org/wiki/认证加密) 进行加密，以防篡改。序列化字符串中包含以下属性： + - : 这是一个序列化的 JSON 对象，提供汇总服务使用的信息。这些数据使用 [AEAD](https://zh.wikipedia.org/wiki/认证加密) 进行加密，以防篡改。序列化字符串中包含以下属性： - `"api"` - : 表示触发报告生成的 API 的枚举值。目前，这个值将始终等于 `"attribution-reporting"`，但将来可能会扩展以支持其他 API。 - `"attribution_destination"` - - : 一个表示归因 [`"destination"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#destination) URL 的字符串，该 URL 在源注册时通过相关的 {{httpheader("Attribution-Reporting-Register-Source")}} 响应标头设置。 + - : 一个表示归因 [`"destination"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#destination) URL 的字符串，该 URL 在来源注册时通过相关的 {{httpheader("Attribution-Reporting-Register-Source")}} 响应标头设置。 - `"report_id"` - : 一个表示此报告的[全局唯一标识符（UUID）](/zh-CN/docs/Glossary/UUID)的字符串，可用于防止重复计数。 - `"reporting_origin"` - - : 触发报告生成的源。 + - : 触发报告生成的来源。 - `"scheduled_report_time"` - : 一个字符串，表示从 Unix 纪元到浏览器最初计划发送报告的时间，以秒为单位（避免由于设备离线导致的报告延迟）。 - `"source_registration_time"` - - : 一个字符串，表示从 Unix 纪元到归因源注册的时间，四舍五入到整天。 + - : 一个字符串，表示从 Unix 纪元到归因来源注册的时间，四舍五入到整天。 - `"version"` - : 一个表示生成报告的 API 版本的字符串。 - `"aggregation_service_payloads"` - - : 一个对象数组，表示汇总服务用来组装报告中数据的直方图贡献负载对象。目前，每个报告只支持一个由浏览器配置的负载。将来可能会支持多个可定制的负载。每个负载对象包含以下属性： + - : 一个对象数组，表示汇总服务用来组装报告中数据的直方图贡献的有效负载对象。目前，每个报告只支持一个由浏览器配置的有效负载。将来可能会支持多个可定制的有效负载。每个有效负载对象包含以下属性： - `"payload"` @@ -125,44 +127,44 @@ slug: Web/API/Attribution_Reporting_API/Generating_reports { "operation": "histogram", // 允许服务支持将来其他操作 "data": [{ - "bucket": , - "value": + "bucket": <分桶，编码为 16 字节（即 128 位）的大端字节串>, + "value": <桶值，编码为 4 字节（即 32 位）的大端字节串> }, ...] } ``` - `"key_id"` - - : 一个字符串，标识用于加密负载的公钥。 + - : 一个字符串，标识用于加密有效负载的公钥。 - `"debug_cleartext_payload"` {{optional_inline}} - : 可选的调试信息。 - `"aggregation_coordinator_origin"` - : 汇总服务的部署选项。 - `"source_debug_key"` {{optional_inline}} - - : 一个 64 位无符号整数，表示归因源的调试密钥。此值与相关 {{httpheader("Attribution-Reporting-Register-Source")}} 标头的 [`"debug_key"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#debug_key) 字段中的值一致。更多信息请参见[调试报告](#调试报告)。 + - : 一个 64 位无符号整数，表示归因来源的调试密钥。此值与相关 {{httpheader("Attribution-Reporting-Register-Source")}} 标头的 [`"debug_key"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#debug_key) 字段中的值一致。更多信息请参见[调试报告](#调试报告)。 - `"trigger_debug_key"` {{optional_inline}} - : 一个 64 位无符号整数，表示归因触发器的调试密钥。此值与相关 {{httpheader("Attribution-Reporting-Register-Trigger")}} 标头的 `"debug_key"` 字段中的值一致。更多信息请参见[调试报告](#调试报告)。 ## 为报告添加噪声 -噪声被添加到报告中，以模糊与特定源相关的输出，从而保护用户隐私。确切的源数据无法被识别并归因到个别用户，但从数据中提取的总体模式仍然可以提供相同的意义。 +噪声被添加到报告中，以模糊与特定来源相关的输出，从而保护用户隐私。确切的来源数据无法被识别并归因到用户个体，但从数据中提取的总体模式仍然可以提供相同的意义。 关于归因报告中噪声的工作原理，请参见： -- [理解汇总报告中的噪声](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/understanding-noise)。 +- [理解汇总报告中的噪声](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/understanding-noise) - [数据限制和噪声](https://github.com/WICG/attribution-reporting-api/blob/main/EVENT.md#data-limits-and-noise) -- [与噪声的协作](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/working-with-noise) +- [处理噪声](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/working-with-noise) ## 报告优先级和限制 -默认情况下，所有归因源的优先级相同，并且归因模型是最后接触（last-touch）模型，这意味着转换被归因于最新的匹配源事件。对于事件级和可汇总的报告，你可以通过在相关 {{httpheader("Attribution-Reporting-Register-Source")}} 标头中设置 `"priority"` 字段的新值来更改源优先级。默认值为`0`；如果你为特定源设置了`"priority"`值为`1`，则该源将首先匹配，优先于任何优先级为 `0` 的源。优先级为 `2` 的源将在优先级为 `1` 的源之前匹配，依此类推。 +默认情况下，所有归因来源的优先级相同，并且归因模型是最后接触（last-touch）模型，这意味着转化被归因到最新的匹配来源事件。对于事件级和可汇总的报告，你可以通过在相关 {{httpheader("Attribution-Reporting-Register-Source")}} 标头中设置 `"priority"` 字段的新值来更改来源优先级。默认值为 `0`；如果你将特定来源的 `"priority"` 值设置为 `1`，则该来源将首先匹配，优先于任何优先级为 `0` 的来源。优先级为 `2` 的来源将在优先级为 `1` 的来源之前匹配，依此类推。 归因触发器优先级的工作方式相同；你也可以通过在相关 {{httpheader("Attribution-Reporting-Register-Trigger")}} 标头中添加 `"priority"` 字段来设置触发器优先级，但仅适用于事件级报告。 不同的来源类型有不同的默认限制： -- [基于导航的归因源](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于导航的归因源)默认有三个报告限制。例如，如果用户点击了一个广告并进行了四次转化：他们访问了广告商网站主页，然后访问了产品页面，注册了新闻通讯，最后进行了购买。由于这是第四次转化，购买报告将被丢弃。 -- [基于事件的归因源](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于事件的归因源)默认只有一个报告限制。 +- [基于导航的归因来源](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于导航的归因来源)默认限制为三个报告。例如，如果用户点击了一个广告并进行了四次转化：他们访问了广告商网站主页，然后访问了产品页面，注册了时事通讯，最后进行了购买。由于这是第四次转化，购买报告将被丢弃。 +- [基于事件的归因来源](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于事件的归因来源)默认限制为一个报告。 > [!NOTE] > 可以通过在关联的 `Attribution-Reporting-Register-Source` 标头的 `"event_report_windows"` 字段中设置不同的 `"end_times"` 来调整报告限制。 @@ -259,7 +261,7 @@ slug: Web/API/Attribution_Reporting_API/Generating_reports - **详细调试报告**为与归因报告关联的归因来源和归因触发事件提供更多可见性。它们使你能够确保来源已成功注册，或跟踪丢失的报告并确定其原因（例如，由于来源或触发事件注册失败或发送或生成报告时失败）。详细调试报告在来源或触发器注册时立即发送。 > [!NOTE] -> 要使用调试报告，报告来源需要设置 cookie。如果配置为接收报告的来源是第三方，则该 cookie 将是[第三方 cookie](/zh-CN/docs/Web/Privacy/Third-party_cookies)，这意味着在禁用/不可用第三方 cookie 的浏览器中将无法使用调试报告。 +> 要使用调试报告，报告来源（origin）需要设置 cookie。如果配置为接收报告的来源是第三方，则该 cookie 将是[第三方 cookie](/zh-CN/docs/Web/Privacy/Third-party_cookies)，这意味着在禁用/不可用第三方 cookie 的浏览器中将无法使用调试报告。 ### 使用调试报告 @@ -297,10 +299,10 @@ slug: Web/API/Attribution_Reporting_API/Generating_reports - 汇总成功调试报告的端点：`/.well-known/attribution-reporting/debug/report-aggregate-attribution` - 详细调试报告的端点：`/.well-known/attribution-reporting/debug/verbose` -生成的成功调试报告与归因报告相同，并包含来源端和触发端调试键，分别位于 `"source_debug_key"` 和 `"trigger_debug_key"` 字段中。 +生成的成功调试报告与归因报告相同，并包含来源端和触发器端的调试键（分别位于 `"source_debug_key"` 和 `"trigger_debug_key"` 字段中）。 有关更多信息和示例，请参见： -- [调试报告介绍](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/attribution-reporting-debugging/)（2023 年，developers.google.com） -- [设置调试报告](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/attribution-reporting-debugging/part-2/)（2023 年，developers.google.com） -- [调试烹饪手册](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/attribution-reporting-debugging/part-3/)（2023 年，developers.google.com） +- developers.google.com 上的[调试报告介绍](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/attribution-reporting-debugging/)（2023） +- developers.google.com 上的[设置调试报告](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/attribution-reporting-debugging/part-2/)（2023） +- developers.google.com 上的[调试宝典](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/attribution-reporting-debugging/part-3/)（2023） diff --git a/files/zh-cn/web/api/attribution_reporting_api/index.md b/files/zh-cn/web/api/attribution_reporting_api/index.md index 0f94c6788959a0..22dc0fa6fb70c8 100644 --- a/files/zh-cn/web/api/attribution_reporting_api/index.md +++ b/files/zh-cn/web/api/attribution_reporting_api/index.md @@ -1,11 +1,13 @@ --- title: 归因报告 API slug: Web/API/Attribution_Reporting_API +l10n: + sourceCommit: f430d277573ba0b06b1ac33ae8017fd90f170bef --- {{SeeCompatTable}}{{securecontext_header}}{{DefaultAPISidebar("Attribution Reporting API")}} -归因报告 API（Attribution Reporting API）使开发者能够衡量转化事件——比如当用户点击嵌入在某个网站上的广告，然后在供应商的网站上购买商品——并随后访问这些转化事件的报告。它在不依赖第三方跟踪 cookie 的情况下完成这一过程。 +**归因报告 API**（Attribution Reporting API）使开发者能够衡量转化——比如当用户点击嵌入在某个网站上的广告，然后在供应商的网站上购买商品——并随后访问这些转化的报告。它在不依赖第三方跟踪 cookie 的情况下完成这一过程。 ## 概念和用法 @@ -17,7 +19,7 @@ slug: Web/API/Attribution_Reporting_API - 销售了多少产品、注册了多少服务等。 - 产生了多少收入。 -传统上，网络上的转化测量依赖于第三方跟踪 cookie。广告通常嵌入在网页的一个 {{htmlelement("iframe")}} 中，这样可以设置一个包含用户及其与广告互动信息的 cookie。 +传统上，Web 上的转化测量依赖于第三方跟踪 cookie。广告通常嵌入在网页的一个 {{htmlelement("iframe")}} 中，这样可以设置一个包含用户及其与广告互动信息的 cookie。 之后，当用户决定访问广告主的网站时，只要该网站来自与广告相同的域名，该网站就可以访问之前由广告设置的第三方 cookie。广告主可以将广告的数据与自己的第一方数据关联起来，以回答诸如“用户在与另一个网站的产品广告互动后是否购买了该产品？”的问题。 @@ -41,11 +43,11 @@ slug: Web/API/Attribution_Reporting_API - 一个链接。在这种情况下，交互是用户点击链接（直接通过 {{htmlelement("a")}} 元素，或通过 {{domxref("Window.open()")}} 调用）。通过对导航请求的响应来注册来源。 - 一张图片，例如广告横幅或 1x1 透明跟踪像素。在这种情况下，交互是用户访问页面。图片加载时，即服务器响应图片请求时，注册来源。 - 一个 fetch 请求（即 {{domxref("Window/fetch", "fetch()")}} 或 {{domxref("XMLHttpRequest")}}）。在这种情况下，交互可以根据你的应用程序的需要进行指定——例如，fetch 请求可以由 `click` 或 `submit` 事件触发。来源在响应返回时注册。 -2. 当归因来源交互发生时，{{httpheader("Attribution-Reporting-Register-Source")}} 标头中返回的来源数据会存储在仅浏览器可访问的私有本地缓存中。此数据包括页面和广告主可用的上下文和第一方数据、收集转化数据的广告技术公司的来源以及一个或多个期望从该广告发生转化的目标（[eTLD+1](/zh-CN/docs/Glossary/eTLD)）（即广告主的网站，例如 shop.example）。 +2. 当归因来源交互发生时，{{httpheader("Attribution-Reporting-Register-Source")}} 标头中返回的来源数据会存储在仅浏览器可访问的私有本地缓存中。此数据包括页面和广告主可用的上下文和第一方数据、收集转化数据的广告技术公司的来源以及一个或多个期望从该广告发生转化的目标（[eTLD+1](/zh-CN/docs/Glossary/eTLD)）（即广告主的网站，例如 `shop.example`）。 3. 当用户稍后访问 `shop.example` 时，当交互指示转化发生时，该网站可以注册一个**归因触发器**（例如，用户点击 `shop.example` 上的“添加到购物车”按钮）。浏览器将发送一个带有 {{httpheader("Attribution-Reporting-Eligible")}} 标头的请求，以表明响应有资格注册归因触发器，如果响应中包含适当的 {{httpheader("Attribution-Reporting-Register-Trigger")}} 标头，则完成注册。归因触发器可以是，例如： - 一张图片，例如购物车图标或 1x1 透明跟踪像素。在这种情况下，交互是用户访问页面。触发器在图片加载时注册，即当服务器响应图片请求时。 - 一个 fetch 请求（即 {{domxref("Window/fetch", "fetch()")}} 或 {{domxref("XMLHttpRequest")}}）。在这种情况下，交互可以根据你的应用程序的需要进行指定——例如，fetch 请求可以由 `click` 或 `submit` 事件触发。触发器在响应返回时注册。 -4. 当触发器归因完成后，浏览器会尝试将 [归因报告注册触发器](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Trigger) 标头中的数据与私有本地缓存中保存的来源数据条目进行匹配（见第 2 步）。有关匹配方法和要求，请参阅[注册归因触发器](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_triggers)。 +4. 当触发器归因完成后，浏览器会尝试将 [Attribution-Reporting-Register-Trigger](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Trigger) 标头中的数据与私有本地缓存中保存的来源数据条目进行匹配（见第 2 步）。有关匹配方法和要求，请参阅[注册归因触发器](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_triggers)。 5. 如果找到匹配，浏览器将把报告数据发送到通常由广告技术提供商拥有的报告服务器上的端点，在那里可以安全地进行分析。与 cookie 不同，这些数据仅对你发送数据的特定网站可用——不会在其他地方共享数据。这些报告可以是： - **事件级报告**：基于归因来源事件的报告，其中详细的来源数据与粗略的触发器数据相关联。例如，报告可能看起来像“`ad.shop.example` 上的点击 ID 200498 导致了 `shop.example` 的购买”，其中“点击 ID 200498”是详细的来源数据，“购买”是粗略的触发器数据。详细的来源数据可能包含来源页面的第一方或上下文数据，而触发器数据可能编码来自触发器页面的事件。 - **汇总报告**：更详细的报告，结合来自来源和触发器侧的多个转化数据。例如“`news.example` 上的广告活动 ID 774653 导致了 `shop.example` 上来自意大利用户的 654 笔销售，总收入为 $9540。”汇总报告的编制需要使用聚合服务（例如 [Google 聚合服务](https://github.com/privacysandbox/aggregation-service)）。 @@ -68,8 +70,8 @@ slug: Web/API/Attribution_Reporting_API - : 当通过 {{domxref("Window/fetch", "fetch()")}} 生成请求时，这表示你希望响应能够注册归因来源或触发器。 - {{domxref("XMLHttpRequest.setAttributionReporting()")}} - : 当通过 {{domxref("XMLHttpRequest")}} 生成请求时，这表示你希望响应能够注册归因来源或触发器。 -- {{domxref("Window.open()")}} 中的 `attributionsrc` 功能关键字 - - : 当 `open()` 方法完成时，完成归因来源的注册*并*触发浏览器存储相关的来源数据（如 {{httpheader("Attribution-Reporting-Register-Source")}} 响应标头中提供）。请注意，`Window.open()` 调用不能用于注册归因触发器。 +- {{domxref("Window.open()")}} 中的 `attributionsrc` 特性关键字 + - : 当 `open()` 方法完成时，完成归因来源的注册*并*触发浏览器存储相关的来源数据（如 {{httpheader("Attribution-Reporting-Register-Source")}} 响应标头中提供的）。请注意，`Window.open()` 调用不能用于注册归因触发器。 ## HTML 元素 @@ -97,7 +99,7 @@ slug: Web/API/Attribution_Reporting_API ## 示例 -请参阅[示例：归因报告 API](https://arapi-home.web.app/) 以获取示例实现（也可查看[源代码](https://github.com/GoogleChromeLabs/trust-safety-demo/tree/main/attribution-reporting)）。 +请参阅[演示：归因报告 API](https://arapi-home.web.app/) 以获取示例实现（也可查看[源代码](https://github.com/GoogleChromeLabs/trust-safety-demo/tree/main/attribution-reporting)）。 ## 规范 @@ -110,6 +112,6 @@ slug: Web/API/Attribution_Reporting_API ## 参见 - [归因报告标头验证工具](https://wicg.github.io/attribution-reporting-api/validate-headers) -- [developers.google.com 上的归因报告](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/)（2023） -- [developers.google.com 上的启用转化测量](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/enable-conversion-measurement)（2023） -- [developers.google.com 上的隐私沙盒](https://developers.google.com/privacy-sandbox/)（2023） +- developers.google.com 上的[归因报告](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/)（2023） +- developers.google.com 上的[启用转化测量](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/enable-conversion-measurement)（2023） +- developers.google.com 上的[隐私沙盒](https://developers.google.com/privacy-sandbox/)（2023） diff --git a/files/zh-cn/web/api/attribution_reporting_api/registering_sources/index.md b/files/zh-cn/web/api/attribution_reporting_api/registering_sources/index.md index a5606651f741d6..a29cfa83d150b3 100644 --- a/files/zh-cn/web/api/attribution_reporting_api/registering_sources/index.md +++ b/files/zh-cn/web/api/attribution_reporting_api/registering_sources/index.md @@ -1,30 +1,32 @@ --- -title: 注册归因源 +title: 注册归因来源 slug: Web/API/Attribution_Reporting_API/Registering_sources +l10n: + sourceCommit: ec1006afdf68a5808a48ab6301f9ccff3cd7ecc2 --- {{SeeCompatTable}}{{DefaultAPISidebar("Attribution Reporting API")}} -本文解释了如何在使用[归因报告 API](/zh-CN/docs/Web/API/Attribution_Reporting_API) 时注册归因源。 +本文解释了如何在使用[归因报告 API](/zh-CN/docs/Web/API/Attribution_Reporting_API) 时注册归因来源。 ## 基本方法 -归因源的形式包括链接、图片或脚本，这些内容用于衡量与之交互的用户行为（例如，广告转化）。这些交互会导致浏览器将源数据存储在一个私有的本地缓存中（仅浏览器可访问）。不同的归因源类型有不同的注册方式和信号交互方式，它们可以分为以下几类： +归因来源的形式包括链接、图片或脚本，它们会被包含在你想要衡量交互行为的内容中（例如，想要衡量转化的广告）。当发生特定用户交互时，浏览器会将来源数据存储在一个私有的本地缓存中（仅浏览器可访问）。不同的归因来源类型有不同的注册和信号交互方式，它们可以分为以下几类： -- 导航源，指浏览器在响应导航时存储源数据。例如，当用户点击链接或用键盘激活它时，或者通过 {{domxref("Window.open()")}} 调用发生导航时。有关示例，请参见[基于导航的归因源](#基于导航的归因源)。 -- 事件源，指浏览器在事件触发时存储源数据。有关示例，请参见[基于事件的归因源](#基于事件的归因源)。 +- 导航来源，指浏览器在响应导航时存储源数据。例如，当用户点击链接或用键盘激活它时，或者通过 {{domxref("Window.open()")}} 调用发生导航时。有关示例，请参见[基于导航的归因来源](#基于导航的归因来源)。 +- 事件来源，指浏览器在事件触发时存储源数据。有关示例，请参见[基于事件的归因来源](#基于事件的归因来源)。 -注册源和检索、存储源数据的过程在这两种情况下是相同的： +注册来源和检索、存储来源数据的过程在这两种情况下是相同的： -1. 当用户与归因源进行交互时，它会在请求中发送一个 {{httpheader("Attribution-Reporting-Eligible")}} 标头给测量交互的服务器（通常是广告主的服务器），以表明响应有资格注册源。例如： +1. 当用户与归因来源进行交互时，它会在请求中发送 {{httpheader("Attribution-Reporting-Eligible")}} 标头给测量交互的服务器（通常是广告主的服务器），以表明响应有资格注册来源。例如： ```http Attribution-Reporting-Eligible: navigation-source ``` -2. 当服务器接收到包含 `Attribution-Reporting-Eligible` 标头的请求时，它可以在响应中包含一个 {{httpheader("Attribution-Reporting-Register-Source")}} 标头以完成源注册。其值是一个 JSON 字符串，提供了浏览器应存储的有关归因源的信息。该标头中包含的信息还决定了浏览器生成哪些类型的报告： +2. 当服务器接收到包含 `Attribution-Reporting-Eligible` 标头的请求时，它可以在响应中包含 {{httpheader("Attribution-Reporting-Register-Source")}} 标头以完成来源注册。其值是一个 JSON 字符串，提供了浏览器应存储的有关与之交互的归因来源的信息。该标头中包含的信息还决定了浏览器生成哪些类型的报告： - - 以下示例将导致在[触发器](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_triggers)匹配到源时生成一个[事件级报告](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports#事件级报告)： + - 以下示例将导致在[触发器](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_triggers)与来源匹配时生成一个[事件级报告](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports#事件级报告)： ```js res.set( @@ -42,21 +44,21 @@ slug: Web/API/Attribution_Reporting_API/Registering_sources ); ``` - 在这种情况下，唯一必需的字段是 `destination`，它指定 1–3 个预期触发器发生的站点。这些用于在触发器与源匹配时。上述指定的其他字段功能如下： + 在这种情况下，唯一必需的字段是 `destination`，它指定 1–3 个触发器预期触发的站点。它们用于在与触发器交互时将归因触发器与来源进行匹配。上述指定的其他字段如下： - - `"source_event_id"`：一个表示归因源的 ID 的字符串，可以用于在归因源被交互时将其映射到其他信息，或在报告端点（见[生成报告 > 基本流程](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports#基本流程)获取端点信息）聚合信息。 - - `"trigger_data"`：一个 32 位无符号整数数组，表示可能匹配此源的不同触发事件的数据。例如，“用户将商品添加到购物车”或“用户注册了邮件列表”可以是触发站点上发生的事件，这些事件可以匹配此源并表示广告主试图衡量的某种转化。这些必须与[触发器](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Trigger#trigger_data)中指定的 `"trigger_data"` 匹配，以便进行事件级归因。 + - `"source_event_id"`：一个表示归因来源的 ID 的字符串，可以用于在归因来源被交互时将其映射到其他信息，或在报告端点（见[生成报告 > 基本流程](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports#基本流程)获取端点信息）聚合信息。 + - `"trigger_data"`：一个 32 位无符号整数数组，表示可能匹配此来源的不同触发事件的数据。例如，“用户将商品添加到购物车”或“用户注册了邮件列表”可以是触发站点上发生的事件，这些事件可以匹配此来源并表示广告主试图衡量的某种转化。它们必须与[触发器](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Trigger#trigger_data)中指定的 `"trigger_data"` 匹配，以便进行事件级归因。 > [!NOTE] - > 用于表示每个事件的值，以及数组中的元素数量，都是完全任意的，由你作为开发者定义。数组中可以包含未使用的值，但必须存在值，以便浏览器在触发器注册时将其归因于源。 - - `"trigger_data_matching"`：一个字符串，指定如何将触发器的 `"trigger_data"` 与源的 `"trigger_data"` 匹配。`"exact"` 是你几乎总是会使用的值，它匹配精确值。 - - `"expiry"`：一个表示归因源过期时间的字符串，以秒为单位，过期后该源将不再有效（即，后续触发器将无法归因于此源）。 - - `"priority"`：一个表示归因源优先级的字符串值。有关更多信息，请参见[报告优先级和限制](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports#报告优先级和限制)。 + > 用于表示每个事件的值，以及数组中的元素数量，都是完全任意的，由作为开发者的你定义。数组中可以包含未使用的值，但必须存在值，以便浏览器在触发器注册时将其归因于来源。 + - `"trigger_data_matching"`：一个字符串，指定如何将触发器的 `"trigger_data"` 与来源的 `"trigger_data"` 匹配。`"exact"` 是你几乎总是会使用的值，它匹配精确值。 + - `"expiry"`：一个表示归因来源过期时间的字符串，以秒为单位，过期后该源将不再有效（即，后续触发器将无法归因到此来源）。 + - `"priority"`：一个表示归因来源优先级的字符串值。有关更多信息，请参见[报告优先级和限制](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports#报告优先级和限制)。 - `"debug_key"`：一个以十进制格式表示的 64 位无符号整数，表示调试密钥。如果你希望生成一个[调试报告](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports#调试报告)以配合关联的归因报告，则设置此项。 - - `"event_report_window"`：一个表示时间的字符串（以秒为单位），在此时间后，后续触发器将无法归因于此源，以生成事件级报告。 + - `"event_report_window"`：一个表示时间的字符串（以秒为单位），在此时间后，后续触发器将无法归因到此来源（以生成事件级报告）。 - 参见 {{httpheader("Attribution-Reporting-Register-Source")}} 以获取此标头中所有字段的详细描述。 + 参见 {{httpheader("Attribution-Reporting-Register-Source")}} 以获取此标头中所有可用字段的详细描述。 - - 要使浏览器在触发器匹配到源时生成一个[汇总报告](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports#汇总报告)，需要在生成事件级报告所需的字段之外，额外包含一些字段。 + - 要使浏览器在触发器匹配到来源时生成[汇总报告](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports#汇总报告)，需要在生成事件级报告所需的字段*之外*，额外包含一些字段。 ```js res.set( @@ -85,23 +87,23 @@ slug: Web/API/Attribution_Reporting_API/Registering_sources - `"aggregation_keys"`：一个包含用户提供的键的对象，表示在生成的报告值下汇总不同数据点。 - `"aggregatable_report_window"`：一个表示时间的字符串（以秒为单位），在此时间后，触发数据将不再包含在生成的可汇总报告中。 - 再次参见 {{httpheader("Attribution-Reporting-Register-Source")}} 以获取此标头中所有字段的详细描述。 + 同样，请参见 {{httpheader("Attribution-Reporting-Register-Source")}} 以获取此标头中所有字段的详细描述。 -3. 成功注册源后，浏览器将提供的源数据存储在其私有本地缓存中。 +3. 成功注册来源后，浏览器将提供的来源数据存储在其私有本地缓存中。 -## 基于导航的归因源 +## 基于导航的归因来源 -导航源对于测量与链接的交互非常有用——例如，用户可能在发布者页面上看到广告，然后点击它以导航到广告主的页面，在那里希望发生转化。 +导航来源对于测量与链接的交互非常有用——例如，用户可能在发布者页面上看到广告，然后点击它以导航到希望发生转化的广告主的页面。 -有几种不同类型的基于导航的归因源（例如，点击广告）可以注册——那些基于 HTML 的（使用 `attributionsrc` 属性）和那些基于 {{domxref("Window.open()")}} 调用的（使用 `attributionsrc` 窗口特性）。 +有几种不同类型的基于导航的归因来源（例如，点击广告）可以注册——基于 HTML 的（使用 `attributionsrc` 属性）和基于 {{domxref("Window.open()")}} 调用的（使用 `attributionsrc` 窗口特性）。 -### 基于 HTML 的导航源 +### 基于 HTML 的导航来源 -要注册基于导航的归因源，你可以将 `attributionsrc` 属性添加到适当的 {{htmlelement("a")}} 元素中，这指定了注册请求将被发送到的位置。 +要注册基于导航的归因来源，你可以将 `attributionsrc` 属性添加到适当的 {{htmlelement("a")}} 元素中，这指定了注册请求将被发送到的位置。 如果你将属性值留空，则注册请求将发送到链接到的位置。也可以在值中指定一个或多个额外的 URL 以发送注册请求；有关详细信息，请参见[在 attributionsrc 中指定 URL](#在_attributionsrc_中指定_url)。 -`attributionsrc` 可以通过声明方式添加： +`attributionsrc` 可以通过声明的方式添加： ```html @@ -116,9 +118,9 @@ const aElem = document.querySelector("a"); aElem.attributionSrc = ""; ``` -在这种情况下，交互发生时，浏览器在用户点击链接并且浏览器接收到响应时，会存储与基于导航的归因源相关的源数据（如在 {{httpheader("Attribution-Reporting-Register-Source")}} 响应标头中提供的）。 +在这种情况下，交互发生时，浏览器在用户点击链接并且浏览器接收到响应时，会存储与基于导航的归因来源（如在 {{httpheader("Attribution-Reporting-Register-Source")}} 响应标头中提供的）相关的来源数据。 -### 基于 Window.open() 的导航源 +### 基于 Window.open() 的导航来源 你还可以将 `attributionsrc` 特性关键字添加到 {{domxref("Window.open()")}} 调用的特性属性中。在此示例中，我们在响应 `click` 事件时运行它： @@ -129,18 +131,18 @@ elem.addEventListener("click", () => { ``` > [!NOTE] -> 在设置像上面示例中的[`click`](/zh-CN/docs/Web/API/Element/click_event)事件时，建议将其设置在预期会点击的控件上，例如 {{htmlelement("button")}} 或 {{htmlelement("a")}} 元素上。这在语义上更合理，并且对屏幕阅读器和键盘用户更友好。 +> 在设置像上面示例中的 [`click`](/zh-CN/docs/Web/API/Element/click_event) 事件时，建议将其设置在预期会点击的控件上，例如 {{htmlelement("button")}} 或 {{htmlelement("a")}} 元素上。这在语义上更合理，并且对屏幕阅读器和键盘用户更友好。 > [!NOTE] -> 要通过 `open()` 注册归因源，必须在[瞬态激活](/zh-CN/docs/Glossary/Transient_activation)（即用户交互事件处理程序内部，如 `click`）中调用，并且必须在用户交互后的五秒内完成。 +> 要通过 `open()` 注册归因来源，必须在[瞬态激活](/zh-CN/docs/Glossary/Transient_activation)（即用户交互事件处理程序内部，如 `click`）中调用，并且必须在用户交互后的五秒内完成。 -## 基于事件的归因源 +## 基于事件的归因来源 -基于事件的归因源会在某些事件触发时让浏览器存储源数据，例如在 `` 或 `