Private Aggregation API 基础知识

Private Aggregation API 的主要概念

本文档的适用对象

Private Aggregation API 支持通过 Worklet 访问跨网站数据来收集汇总数据。本文介绍的概念对于在 Shared Storage 和 Protected Audience API 中构建报告功能的开发者来说非常重要。

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

关键术语

在阅读本文档之前，熟悉关键术语和概念会很有帮助。下文将对其中每个术语进行详细说明。

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

不公开汇总工作流程

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

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

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

汇总键

汇总键（简称“键”）表示将累积可汇总值的分桶。一个或多个维度可以编码到键中。维度表示您希望进一步了解的方面，例如用户的年龄段或广告系列的展示次数。

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

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

假设该键表示查看过 widget ID 3276 的法国（国家/地区 ID 为 061）的用户数量，汇总键为 3276061。

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

您也可以使用哈希机制（例如 SHA-256）生成汇总键。例如，字符串 {"WidgetId":3276,"CountryID":67} 可以进行哈希处理，然后转换为 42943797454801331377966796057547478208888578253058197330928948081739249096287n 的 BigInt 值。如果哈希值超过 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 小时的滚动窗口。如果新的可汇总报告会导致超出预算，则不会生成报告。

贡献预算由参数 L1 表示，设置为每天每十分钟 216 (65,536) 次，往返为 220

(1,048,576)。如需详细了解这些参数，请参阅说明。

贡献预算的值是任意的，但系统会针对该值调整噪声。您可以使用此预算最大限度地提高汇总值的信噪比（噪声和缩放部分将对此进行详细介绍）。

如需详细了解贡献预算，请参阅说明。此外，如需更多指导，请参阅贡献预算。

可汇总的报告

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

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

下面是启用了调试模式的可汇总报告示例：

  "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 内部架构页面的屏幕截图

出于测试目的，您可以使用“发送所选报告”按钮将报告立即发送到服务器。

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

浏览器使用列出的已知路径将可汇总报告发送到包含 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) 中运行，为数据完整性、数据机密性和代码完整性提供一定程度的保证。虽然您拥有并运营该服务，但您无法查看 TEE 内正在处理的数据。

摘要报告

摘要报告可让您查看在添加了噪声的情况下收集的数据。您可以请求针对一组给定键的摘要报告。

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

  • bucket：作为二进制数字字符串的汇总键。如果使用的汇总键为“123”，则存储分区为“1111011”。
  • value：特定衡量目标的汇总值，根据添加了噪声的所有可用可汇总报告进行求和。

例如：

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

噪声和缩放

为保护用户隐私，汇总服务会在每次请求摘要报告时向每个摘要值添加一次噪声。噪声值从拉普拉斯概率分布中随机抽取。虽然您无法直接控制噪声的添加方式，但可以影响噪声对其测量数据的影响。

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

例如，假设噪声分布的标准差为 100，并以 0 为中心。如果收集的可汇总报告值（或“可汇总值”）仅为 200，则噪声的标准差将为汇总值的 50%。但是，如果可汇总值为 20,000，则噪声的标准差将仅为聚合值的 0.5%。因此，可汇总值 20,000 具有更高的信噪比。

因此，将可汇总值乘以缩放比例有助于降低噪声。缩放比例表示您要对给定的可汇总值的缩放程度。

无论汇总值如何，噪声都是恒定的。

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

根据贡献预算调整可汇总的值。

如需计算适当的扩缩系数，请将贡献预算除以所有键的可汇总值的最大总和。

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

互动和分享反馈

Private Aggregation API 仍在积极讨论中，将来可能会发生变化。如果您在试用此 API 时有反馈意见，我们非常期待。