Private Aggregation API 的主要概念
本文档的适用对象
Private Aggregation API 支持从具有跨网站数据的 Worklet 收集数据。 本文中介绍的概念对于制作报告的开发者非常重要 和 Protected Audience API 中的函数。
- 如果您是开发者,要构建跨网站报告系统 衡量。
- 如果您是营销人员、数据科学家或其他摘要报告 消费者,了解这些机制有助于您设计 检索优化摘要报告的相关决策。
关键词
在阅读本文档之前,建议您先熟悉 关键术语和概念。本文将更详细地介绍上述每个术语。
- 汇总键(也称为“存储分区”)是 预先确定的数据点集合。例如,您可能希望 收集位置数据存储分区,浏览器报告其所在国家/地区 名称。一个汇总键可以包含多个维度(例如, 内容微件的国家/地区和 ID)。
- 可汇总值是单个数据点
汇总到一个汇总键中如果您想衡量
来自法国的用户看过您的内容,那么
France
就是以下维度中的一个维度: 汇总键,1
的viewCount
是可汇总的值。 - 可汇总的报告会在浏览器中生成并加密。对于 Private Aggregation API,包含有关单个事件的数据。
- 汇总服务 处理可汇总报告中的数据,以创建摘要报告。
- 摘要报告是汇总服务的最终输出,而 包含嘈杂的汇总用户数据和详细转化数据。
- worklet 就是 可让您运行特定的 JavaScript 函数 将信息返回给请求者。在 Worklet 中 JavaScript,但无法与外部页面交互或通信。
不公开汇总工作流
当您使用汇总键和 可汇总值时,浏览器会生成可汇总报告。报告 发送到您用于对报告进行批量处理的服务器分批生成的报告为 汇总服务稍后处理并生成摘要报告。
![数据从客户端流向收集器,然后再流向聚合
用于生成摘要报告的服务。](https://developers.google.cn/static/privacy-sandbox/assets/images/data-flows-the-client-t-ebd6f5c55d92f.png?authuser=9&hl=lv)
- 当您调用 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 |
汇总键也可以使用哈希机制生成,例如
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 小时的时间范围。如果新的 汇总报告会导致超出预算, 创建。
捐赠预算由参数 L1 表示,为 设置为每天每十分钟 216 (65,536),后退 220
(1,048,576)。请参阅 解释器 详细了解这些参数
捐赠预算的值是任意的,但噪声会按比例调整。 您可以使用此预算来最大限度地提升摘要值的信噪比 (噪声和缩放部分进一步讨论了相关内容)。
如需详细了解贡献预算,请参阅 explainer。 另请参阅贡献 预算 ,获取更多指导。
可汇总的报告
用户调用 Private Aggregation API 后,浏览器会生成
要由汇总服务稍后处理的可汇总报告
从而及时生成摘要
报告。一个
可汇总的报告采用 JSON 格式,其中包含
每个贡献都是一个 {aggregation key, aggregatable value}
对。
可汇总报告最多会随机延迟一小时发送。
贡献内容会经过加密处理,无法在汇总服务之外读取。 汇总服务对报告进行解密并生成摘要报告。通过 用于浏览器的加密密钥和用于聚合的解密密钥 服务由协调者发布,协调者充当密钥管理服务。 协调器会保存服务映像的二进制哈希列表以进行验证 调用方可以接收解密密钥。
"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 内部设置”页面的屏幕截图](https://developers.google.cn/static/privacy-sandbox/assets/images/screenshot-the-private-a-132a69aaab759.png?authuser=9&hl=lv)
出于测试目的,按钮可用于发送 立即向服务器报告
收集并批量汇总报告
浏览器将可汇总报告发送到 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 中运行,对可汇总报告进行解密并将
以创建最终摘要报告。](https://developers.google.cn/static/privacy-sandbox/assets/images/the-service-runs-a-tee-746adddcc2c6.png?authuser=9&hl=lv)
汇总服务 接收来自收集器的加密可汇总报告,并生成摘要 报告。
汇总服务需要提取解密密钥才能对报告载荷进行解密 协调员的协助该服务在可信执行环境 (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 的信噪比要高得多。
因此,将可汇总值乘以缩放比例会有所帮助 来降低噪声。缩放比例表示您希望对指定的缩放比例 可汇总的值。
![无论汇总值如何,噪声都是恒定的。](https://developers.google.cn/static/privacy-sandbox/assets/images/noise-is-constant-regardl-6c311a31c1292.png?authuser=9&hl=lv)
通过选择更大的缩放比例放大值, 噪声。不过,这也会导致所有分桶的所有贡献的总和 更快地达到捐赠预算限额将值缩减 选择较小的缩放比例常数会增加相对噪声,但会降低 达到预算上限的风险。
![根据捐赠预算调整可汇总值。](https://developers.google.cn/static/privacy-sandbox/assets/images/scale-aggregatable-value-b7347ae673f12.png?authuser=9&hl=lv)
要计算合适的缩放系数,请将贡献预算除以 所有键的可汇总值的最大总和。
请参阅捐赠预算 文档 了解详情。
互动和分享反馈
Private Aggregation API 正在积极讨论中,可能会在 未来。如果您试用此 API 并有反馈意见,我们非常期待收到您的反馈意见。
- GitHub:阅读 explainer, 提出问题并参与 讨论。 * 开发者支持:提出问题并加入 Privacy Sandbox 开发者支持 代码库。 * 加入 Shared Storage API 群组 和 Protected Audience API 群组 ,了解有关非公开聚合的最新公告。