此页面由 Cloud Translation API 翻译。

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 中称为汇总键）中用户的数据汇总。直方图调用会累积值，并以摘要报告的形式返回添加噪声的汇总结果。例如，该报告可能会显示每位用户在多少个网站上看到了您的内容，或者在您的第三方脚本中遇到了 bug。此操作在另一个 API 的 Worklet 内执行。

例如，如果您之前在共享存储空间中记录了人口统计和地理数据，则可以使用 Private Aggregation API 构建一个直方图，以告诉您大约有多少纽约市的用户跨网站看过您的内容。若要进行此衡量的汇总，您可以将地理位置维度编码为汇总键，然后在可汇总值中统计用户数。

主要概念

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

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

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

与 Attribution Reporting 的区别

Private Aggregation API 与 Attribution Reporting API 有许多相似之处。Attribution Reporting 是一个旨在衡量转化情况的独立 API，而私下汇总则是与 Protected Audience API 和共享存储空间等 API 结合使用的跨网站衡量功能构建的。这两个 API 都会生成可汇总报告，汇总服务后端可以使用这些报告生成摘要报告。

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

测试此 API

如需在本地测试 Private Aggregation API，请在 chrome://settings/adPrivacy 下启用所有 Ad Privacy API。

如需详细了解测试，请参阅实验和参与。

使用演示版

如需查看适用于共享存储空间的 Private Aggregation API 演示，请访问 goo.gle/shared-storage-demo；您可以访问 GitHub，获取其代码。该演示实现客户端操作并生成可汇总报告，该报告将发送到您的服务器。

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

用例

Private Aggregation 是一种用于跨网站衡量的通用 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 的特殊扩展）根据触发器报告数据。

可用的函数

共享存储空间和 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 使用已转换为汇总键（存储分区）的内容 ID 调用 Private Aggregation API。

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() 会启用调试模式，该模式会导致可汇总报告包含未加密（明文）载荷。然后，您可以使用 Aggregation Service 的本地测试工具处理这些载荷。

调试模式仅适用于有权访问第三方 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 并有反馈意见，我们非常期待收到您的反馈意见。

GitHub：阅读说明文档，提出问题并参与讨论。
开发者支持：在 Privacy Sandbox 开发者支持代码库中提问并参与讨论。
您可以加入 Shared Storage API 群组和 Protected Audience API 群组，以了解与不公开汇总有关的最新公告。