Private Aggregation API 概览

使用 Protected Audience 中的数据和共享存储空间中的跨网站数据生成汇总数据报告。

为了提供网络所依赖的关键功能，Private Aggregation API 是以可保护隐私的方式汇总和报告跨网站数据而构建的。

实现状态

建议 状态
使用共享存储空间的报告验证功能防止出现无效的 Private Aggregation API 报告
说明		 适用于 Chrome
不公开汇总调试模式的可用性取决于第三方的资格条件
GitHub 问题		 适用于 Chrome M119
缩短报告延迟时间
说明		 适用于 Chrome M119
对 Private Aggregation API 和 Google Cloud 汇总服务的支持
说明		 在 Chrome M121 中提供
可汇总报告载荷的内边距
说明		 适用于 Chrome M119
为 challengeReportBuyers 报告提供的不公开汇总调试模式
说明		 预计会在 Chrome M123 中推出
对过滤 ID 的支持
说明		 预计于 2024 年第 2 季度在 Chrome 中首次推出。

什么是 Private Aggregation API

借助 Private Aggregation API，开发者可以使用 Protected Audience API 中的数据和共享存储空间中的跨网站数据生成汇总数据报告。

此 API 目前仅提供一项操作，即 sendHistogramReport()，但未来可能会支持更多操作。通过直方图操作，您可以汇总自己定义的每个存储分区中用户的数据（在 API 中称为汇总键）。直方图调用会累积值，并以摘要报告的形式返回添加噪声的汇总结果。例如，报告可能会显示每位用户在其上看到了您的内容的网站数量，或者在您的第三方脚本中遇到错误的网站数量。此操作在另一个 API 的 Worklet 内执行。

例如，如果您之前在共享存储空间中记录了受众特征和地理位置数据，则可以使用 Private Aggregation API 构造直方图，了解纽约市大约有多少用户跨网站看到了您的内容。若要针对此类衡量进行汇总，您可以将地理位置维度编码为汇总键，并统计可汇总值中的用户数。

主要概念

当您使用汇总键和可汇总的值调用 Private Aggregation API 时，浏览器会生成可汇总报告。

系统会将可汇总报告发送到您的服务器进行收集和批处理。批量报告稍后由汇总服务进行处理，并生成摘要报告。

如需详细了解 Private Aggregation API 涉及的关键概念，请参阅 Private Aggregation API 基础知识文档。

与归因报告的差异

Private Aggregation API 与 Attribution Reporting API 有许多相似之处。Attribution Reporting 是一个独立的 API，旨在衡量转化情况，而 Private Aggregation 是结合 Protected Audience API 和 Shared Storage 等 API 实现的跨网站衡量。这两个 API 都会生成可汇总报告，汇总服务后端可使用这些报告生成摘要报告。

Attribution Reporting 会将从展示事件收集的数据与在不同时间发生的转化事件相关联。不公开汇总可衡量单个跨网站事件。

测试此 API

您可以在本地测试 Private Aggregation API，方法是在 chrome://flags/#privacy-sandbox-ads-apis 中启用 Privacy Sandbox Ads API 实验标志。

将 Privacy Sandbox 广告 API 实验设为“已启用”，以便使用这些 API
将 Privacy Sandbox 广告 API 实验设置为启用，以便使用这些 API

详细了解如何参与实验并参与测试。

使用演示

如需访问适用于共享存储空间的 Private Aggregation API 演示，请访问 goo.gle/shared-storage-demo 和 GitHub 上获取相关代码。该演示版会实现客户端操作，并生成一份可汇总的报告并发送至您的服务器。

日后还会发布适用于 Protected Audience API 的 Private Aggregation API 演示。

用例

不公开汇总是一种用于跨网站衡量的通用 API，可在共享存储空间和 Protected Audience API Worklet 中使用。第一步是具体确定要收集哪些信息。这些数据点是汇总键的基础。

带共享存储空间

共享存储空间可让您在安全环境中读取和写入跨网站数据，以防止泄露；您还可以利用 Private Aggregation API 衡量存储在共享存储空间中的跨网站数据。

唯一身份用户覆盖面衡量

您可能想要衡量有多少唯一身份用户看过他们的内容。Private Aggregation API 可以给出回答，例如“大约 317 位唯一身份用户看过 Content ID 861”。

您可以在共享存储空间中设置标记，以表明用户是否已看到相应内容。首次访问不存在此标记时，系统会调用不公开汇总，然后设置此标记。在用户后续访问（包括跨网站访问）时，您可以查看共享存储空间；如果已设置了相应标记，则无需向不公开汇总报告提交报告。

受众特征衡量

您可能希望衡量在不同网站上观看过您的内容的用户的受众特征。

不公开汇总可提供答案，例如“大约 317 位 18-45 岁的唯一身份用户来自德国”。使用共享存储空间可从第三方环境访问受众特征数据。稍后，您可以通过对汇总键中的年龄段和国家/地区维度进行编码，生成包含不公开汇总的报告。

K+ 频次衡量

您可能希望衡量有多少用户在特定浏览器上观看了一段内容或广告至少 K 次，将预先选择的值为 K。

不公开汇总可提供答案，例如“大约 89 位用户已经看到 Content ID 581 至少 3 次”。可以在不同站点的共享存储空间中递增计数器，并且可以在 Worklet 中读取计数器。当计数达到 K 时，可以通过不公开汇总提交报告。

使用 Protected Audience API

Protected Audience API 支持重访定位和自定义受众群体用例，而不公开汇总则可让您报告来自买方和卖方 Worklet 的事件。该 API 可用于衡量竞价出价分布等任务。

在 Protected Audience API Worklet 中，您可以使用 sendHistogramReport() 直接汇总数据，并使用 reportContributionForEvent()（Protected Audience API 的特殊扩展程序）根据触发器报告数据。

可用的函数

Shared Storage 和 Protected Audience API Worklet 中的 privateAggregation 对象提供以下函数。

contributeToHistogram()

您可以调用 privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })，其中汇总键为 bucket，可汇总值为 value。对于 bucket 参数，必须提供 BigInt。对于 value 参数，必须提供整数。

以下示例展示了在共享存储空间中如何调用它来进行覆盖面衡量：

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', { 
  data: { contentId: '1234' } 
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){ 
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling" 
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await this.sharedStorage.get(key) === 'true';

    // Do not send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId), 
      value: 1 * SCALE_FACTOR 
    });

    // Set the flag in Shared Storage
    await this.sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

无论何时加载跨网站 iframe 内容，上述代码示例都会调用不公开汇总。iframe 代码加载 Worklet，Worklet 调用 Private Aggregation API 并将内容 ID 转换为汇总键（存储分区）。

contributeToHistogramOnEvent()

仅在 Protected Audience API Worklet 中，我们提供基于触发器的机制，以便仅在发生特定事件时发送报告。此外，此函数还允许范围和值取决于竞价中的该时间点尚不可用的信号。

privateAggregation.reportContributionForEvent(eventType, contribution) 方法接受一个 eventType（用于指定触发事件），以及要在事件触发时提交的 contribution。触发事件可能来自竞价结束后的竞价本身（例如竞价胜出或落败事件），也可能来自呈现广告的围栏框架。 要发送竞价事件的报告，您可以使用 reserved.win、reserved.loss 和 reserved.always 这两个预留关键字。若要提交由围栏框架中的事件触发的报告，请定义自定义事件类型。如需从围栏帧触发事件，请使用 Fenced Frames Ads Reporting API 中提供的 fence.reportEvent() 方法。

以下示例会在竞价胜出事件触发时发送展示次数报告，如果呈现广告的围栏框架触发了 click 事件，则发送点击报告。这两个值可用于计算点击率。

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

如需了解详情，请参阅扩展不公开汇总报告说明。

enableDebugMode()

尽管第三方 Cookie 仍然可用，但我们会提供一种临时机制，让您可以通过启用调试模式更轻松地进行调试和测试。调试报告有助于将基于 Cookie 的衡量结果与不公开汇总的衡量结果进行对比，还可让您快速验证 API 集成情况。

在 Worklet 中调用 privateAggregation.enableDebugMode() 会启用调试模式，该模式会导致可汇总报告包含未加密（明文）载荷。然后，您可以使用汇总服务本地测试工具处理这些载荷。

调试模式仅适用于有权访问第三方 Cookie 的调用方。如果调用方无权访问第三方 Cookie，enableDebugMode() 将静默失败。这意味着，弃用第三方 Cookie 后，调试模式将不再可用。

您还可以通过调用 privateAggregation.enableDebugMode({ <debugKey: debugKey> }) 来设置调试键，其中 BigInt 可用作调试键。调试密钥可用于将基于 Cookie 的衡量数据与来自不公开汇总衡量的数据相关联。每个上下文只能调用一次这些函数。所有后续调用都将被忽略。

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

报告验证

对于共享存储空间，您可以通过在共享存储操作调用中添加上下文 ID 来验证您收到的可汇总报告是否合法。该 ID 会附加到发送的报告中，之后，您可以使用该 ID 验证报告是否是通过共享存储操作发送的。

此功能可在 Chrome M114 及更高版本中进行测试。目前，Protected Audience API 的报告验证功能尚不可用于测试。

如需了解详情，请参阅报告验证铺垫。

互动和分享反馈

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