此页面由 Cloud Translation API 翻译。

Private Aggregation API 基础知识

Private Aggregation API 的主要概念

本文档的适用对象

Private Aggregation API 支持从具有跨网站数据访问权限的工作流中收集汇总数据。本文中介绍的概念对于制作报告的开发者非常重要和 Protected Audience API 中的函数。

如果您是开发者，正在构建用于跨网站衡量的报告系统。
如果您是营销者、数据科学家或其他摘要报告使用者，了解这些机制有助于您做出设计决策，以检索经过优化的摘要报告。

关键词

在阅读本文档之前，熟悉关键术语和概念。本文将更详细地介绍上述每个术语。

汇总键（也称为“存储分区”）是一组预先确定的数据点。例如，您可能需要收集一个存储浏览器报告的国家/地区名称的位置数据存储桶。汇总键可以包含多个维度（例如，国家/地区和内容微件的 ID）。
可汇总值是单个数据点汇总到一个汇总键中如果您想衡量来自法国的用户看过您的内容，那么“France”是以下维度中的一个维度：汇总键，1 的 viewCount 是可汇总的值。
可汇总的报告会在浏览器中生成并加密。对于 Private Aggregation API，包含有关单个事件的数据。
汇总服务会处理可汇总报告中的数据，以创建摘要报告。
摘要报告是汇总服务的最终输出，而包含嘈杂的汇总用户数据和详细转化数据。
worklet 就是可让您运行特定的 JavaScript 函数将信息返回给请求者。您可以在 worklet 中执行 JavaScript，但无法与外部网页互动或通信。

不公开汇总工作流程

当您使用汇总键和可汇总的值调用 Private Aggregation API 时，浏览器会生成可汇总的报告。报告会发送到您的服务器，由服务器进行批量处理。汇总服务稍后会处理批量报告，并生成摘要报告。

当您调用 Private Aggregation API 时，客户端（浏览器）会生成并将可汇总报告发送到您的服务器进行收集。
您的服务器会从客户端收集报告，并将其分批发送到汇总服务。
收集足够的报告后，您将对其进行分批处理，并将其发送到在可信执行环境中运行的汇总服务，以生成摘要报告。

本部分介绍的工作流与 Attribution Reporting API 类似。不过，归因报告会将发生在不同时间的展示事件和转化事件收集的数据相关联。不公开汇总功能可衡量单个跨网站事件。

汇总键

汇总键（简称“key”）表示存储将累积可汇总的值。您可以将一个或多个维度编码到键中。维度表示您希望获得更多例如用户年龄段或广告的展示次数广告系列。

例如，您可能在多个网站上嵌入了 widget，并希望分析查看过该 widget 的用户所在的国家/地区。您正在查看回答诸如“有多少看到我的微件的用户来自 X 国吗？”若要针对此问题生成报告，您可以设置汇总键对两个维度进行编码：微件 ID 和国家/地区 ID。

向 Private Aggregation API 提供的键是 BigInt，它由多个维度组成。在此示例中，维度是 widget ID 和国家/地区 ID。假设 widget ID 最多可包含 4 位数字，例如 1234，并且每个国家/地区都映射到一个按字母顺序排列的数字，例如阿富汗是 1、法国是 61，津巴布韦是“195”。因此，可汇总的键的长度为 7 位，其中前 4 位保留用于 WidgetID，后 3 位保留用于 CountryID。

假设键表示来自法国（国家/地区 ID 061）的用户数量看到过微件 ID 3276 的用户，汇总键为 3276061。

汇总键
微件 ID	国家/地区 ID
3276	061

示例：如果维度具有可用的键空间但输入的位数较少，请添加前导零。例如：如果国家/地区 ID 允许 3 位数字，则阿尔及利亚的国家/地区 ID 为 003。

您还可以使用哈希机制（例如 SHA-256）生成汇总键。例如，字符串可以对 {"WidgetId":3276,"CountryID":67} 进行哈希处理，然后将其转换为 BigInt的 42943797454801331377966796057547478208888578253058197330928948081739249096287n。如果哈希值超过 128 位，您可以对其进行截断，以确保其不会超过允许的最大分桶值 2^128−1。

在共享存储空间 Worklet 中，您可以访问 crypto和 TextEncoder 个模块来生成哈希。如需详细了解如何生成哈希，请参阅 MDN 上的 SubtleCrypto.digest()。

以下示例介绍如何根据经过哈希处理的值：

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

可汇总的值

系统会按键从许多用户中对可汇总的值求和，以生成汇总值在摘要报告中以摘要值的形式提供数据洞见。

现在，我们回到之前提出的示例问题：“查看过我 widget 的用户中有多少来自法国？”此问题的答案将类似于“查看了我的微件 ID 3276 的用户中有大约 4881 位来自法国”。每个用户的可汇总值为 1，而“4881 位用户”是汇总值，即该汇总键的所有可汇总值的总和。

汇总键		可汇总的值
微件 ID	国家/地区 ID	观看次数
3276	061	1

在此示例中，对于看到该 widget 的每一位用户，我们将值加 1。在实践中，可汇总的值可以进行缩放，以提高信噪比。

贡献预算

对 Private Aggregation API 的每次调用都称为一次贡献。为保护用户隐私，我们限制了可从个人收集的贡献数量。

对所有汇总键中的所有可汇总值求和时，总和必须低于捐赠预算预算范围为每个 Worklet origin、每日和与 Protected Audience API 和共享存储空间 Worklet 相互独立。滚动一天内使用大约过去 24 小时的时间范围。如果新的可汇总报告会导致超出预算，系统将不会创建该报告。

贡献预算由参数 L₁ 表示，并设置为每天每 10 分钟 2¹⁶ (65,536)，回退值为 2²⁰

(1,048,576)。请参阅解释器详细了解这些参数

捐赠预算的值是任意的，但噪声会按比例调整。您可以使用此预算来最大限度地提升摘要值的信噪比（噪声和缩放部分进一步讨论了相关内容）。

如需详细了解贡献预算，请参阅 explainer。另请参阅贡献预算，获取更多指导。

每个报告的贡献次数上限

捐赠上限可能因调用者而异。目前，报告为 Shared Storage API 调用方生成的每个报告最多提供 20 次贡献。另一方面，Protected Audience API 调用方每份报告的贡献次数上限为 100 次。我们选择这些限制是为了平衡可以嵌入载荷大小

对于共享存储空间，单个 run() 或 selectURL() 操作中贡献的数据会批量汇总到一个报告中。对于 Protected Audience，做出的贡献进行批量处理

带内边距的贡献

我们还使用了内边距功能进一步修改了贡献内容。对载荷进行填充可保护嵌入在可汇总报告中的贡献真实数量的信息。填充通过 null 贡献来增强载荷（即值为 0）以达到固定长度。

可汇总的报告

用户调用 Private Aggregation API 后，浏览器会生成要由汇总服务稍后处理的可汇总报告从而及时生成摘要报告。可汇总的报告采用 JSON 格式，包含加密的贡献列表，每个贡献都是一个 {aggregation key, aggregatable value} 对。可汇总报告的发送会随机延迟，最长延迟一小时。

贡献内容会经过加密处理，无法在汇总服务之外读取。汇总服务对报告进行解密并生成摘要报告。通过用于浏览器的加密密钥和用于汇总的解密密钥服务由协调者发布，协调者充当密钥管理服务。协调器会保存服务映像的二进制哈希列表以进行验证调用方可以接收解密密钥。

带有 debug 的可汇总报告示例模式：

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

您可以在以下位置查看可汇总的报告： chrome://private-aggregation-internals 信息页：

出于测试目的，按钮可用于发送立即向服务器报告

收集和批量处理可汇总报告

浏览器使用列出的已知路径，将可聚合的报告发送到包含对 Private Aggregation API 的调用的 worklet 的来源：

对于共享存储空间：/.well-known/private-aggregation/report-shared-storage
对于 Protected Audience： /.well-known/private-aggregation/report-protected-audience

在这些端点上，您需要运行一台服务器（充当收集器），用于接收从客户端发送的可汇总报告。

然后，服务器应将报告分批并将批量数据发送到汇总服务。根据可汇总报告的未加密载荷中提供的信息（例如 shared_info 字段）创建批次。理想情况下，每个批次应包含 100 份或更多报告。

您可以选择每天或每周批量处理。此策略非常灵活，您可以针对预计会有更多流量的特定事件（例如预计会有更多展示次数的年份日期）更改批量处理策略。批次应包含来自同一 API 版本、报告来源和安排报告时间。

汇总服务

汇总服务会从收集器接收经过加密的可汇总报告，并生成摘要报告。

如需解密报告载荷，汇总服务会从协调者提取解密密钥。该服务在可信执行环境 (TEE) 中运行，可确保数据完整性、数据机密性和代码完整性。虽然您是该服务的所有者和运营者，但您不会拥有在 TEE 内处理的数据的可见性。

摘要报告

摘要报告可以查看在添加噪声后收集的数据。您可以请求一组给定键的摘要报告。

摘要报告包含一组 JSON 字典式键值对。每个对包含：

bucket：以二进制数字字符串表示的汇总键。如果使用的汇总键为“123”，则范围为“1111011”。
value：给定衡量目标的摘要值，是从所有可汇总的报告中汇总得出，并添加了噪声。

例如：

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

噪声和缩放

为保护用户隐私，汇总服务会向每次请求添加一次噪声， summary 值。噪声值从拉普拉斯概率分发。虽然您无法直接控制添加噪声的方式，但可以影响噪声对衡量数据的影响。

无论所有可汇总值的总和如何，噪声分布都是相同的。因此，可汇总的值越高，噪声的影响就越小概率

例如，假设噪声分布的标准偏差为 100 以 0 为中心。如果收集的可汇总报告值（或“可汇总值”）仅为 200，则噪声的标准差将为汇总值的 50%。但是，如果可汇总的值为 2 万，则噪声的标准差只会占汇总值的 0.5%。因此，可汇总的值为 2 万时，信噪比会高得多。

因此，将可汇总的值乘以缩放比例有助于减少噪声。缩放比例表示您希望对指定的缩放比例可汇总的值。

通过选择较大的放大系数来放大值可以减少相对噪声。不过，这也会导致所有广告系列所带来的贡献总和更快达到贡献预算上限。通过选择较小的缩放系数常量来缩小值会增加相对噪声，但会降低达到预算上限的风险。

要计算合适的缩放系数，请将贡献预算除以所有键的可汇总值的最大总和。

如需了解详情，请参阅贡献预算文档。

互动和分享反馈

不公开汇总 API 正在积极讨论中，未来可能会发生变化。如果您试用此 API 并有反馈意见，我们非常期待收到您的反馈意见。

GitHub：阅读说明文档，提出问题并参与讨论。 * 开发者支持：在 Privacy Sandbox 开发者支持代码库中提问和参与讨论。 * 加入 Shared Storage API 群组和 Protected Audience API 群组，及时了解与“不公开汇总”功能相关的最新动态。