此页面由 Cloud Translation API 翻译。

Private Aggregation API 基础知识

Private Aggregation API 的主要概念

本文档的适用对象

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

如果您是开发者，要构建跨网站报告系统衡量。
如果您是营销人员、数据科学家或其他摘要报告消费者，了解这些机制有助于您设计检索优化摘要报告的相关决策。

关键词

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

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

不公开汇总工作流

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

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

。

本部分介绍的工作流程与Attribution Reporting API。然而，归因工具报告会将从展示事件收集的数据与从转化中收集的数据关联起来事件在不同时间发生不公开汇总测量的是单个跨网站事件

汇总键

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

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

提供给 Private Aggregation API 的密钥是 BigInt、由多个维度组成在本示例中，维度为小部件 ID 和国家/地区 ID。假设微件 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 个模块来生成哈希。如需详细了解如何生成哈希，请参阅已开启 SubtleCrypto.digest() MDN。

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

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

可汇总的值

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

现在，回到之前提出的示例问题：“有多少用户 “谁看过我的微件来自法国？”问题的答案将出现在例如“大约 4881 位看到我的微件 ID 3276 的用户来自法国。”每位用户的可汇总值为 1，“4881 位用户”为 汇总值，即其所有可汇总值的总和 汇总键。

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

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

捐赠预算

对 Private Aggregation API 的每次调用都称为一次贡献。保护用户隐私是指可从是非常有限的。

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

捐赠预算由参数 L₁ 表示，为设置为每天每十分钟 2¹⁶ (65,536)，后退 2²⁰

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

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

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

可汇总的报告

用户调用 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 信息页：

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

收集并批量汇总报告

浏览器将可汇总报告发送到 Worklet 的来源包含对 Private Aggregation API 的调用，使用所列的路径：

对于共享存储空间：/.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 为中心。如果收集的可汇总报告值（或 “aggregatable value”）为 200，则噪声的标准偏差为汇总值的 50%。但是，如果可汇总值为 20,000，则则噪声的标准差仅为汇总值的 0.5%。因此，可汇总值 20000 的信噪比要高得多。

因此，将可汇总值乘以缩放比例会有所帮助来降低噪声。缩放比例表示您希望对指定的缩放比例可汇总的值。

通过选择更大的缩放比例放大值，噪声。不过，这也会导致所有分桶的所有贡献的总和更快地达到捐赠预算限额将值缩减选择较小的缩放比例常数会增加相对噪声，但会降低达到预算上限的风险。

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

请参阅捐赠预算文档了解详情。

互动和分享反馈

Private Aggregation API 正在积极讨论中，可能会在未来。如果您试用此 API 并有反馈意见，我们非常期待收到您的反馈意见。

GitHub：阅读 explainer，提出问题并参与讨论。 * 开发者支持：提出问题并加入 Privacy Sandbox 开发者支持代码库。 * 加入 Shared Storage API 群组和 Protected Audience API 群组，了解有关非公开聚合的最新公告。