此页面由 Cloud Translation API 翻译。

Private Aggregation API 概览

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

为了提供网络所依赖的关键功能，“不公开汇总” API 旨在汇总和报告一种可保护隐私的方式

实现状态

提案	状态
通过共享存储空间的报告验证防止无效的 Private Aggregation API 报告说明者	在 Chrome 中提供
不公开汇总调试模式的可用性取决于第三方 Cookie 的使用资格 GitHub 问题	适用于 Chrome M119
缩短报告延迟时间说明	适用于 Chrome M119
支持 Google Cloud 专用汇总 API 和汇总服务说明	适用于 Chrome M121
可汇总报告载荷的填充说明	适用于 Chrome M119
私密汇总调试模式适用于 auctionReportBuyers 报告说明	适用于 Chrome M123
支持过滤 ID 解说	适用于 Chrome M128
客户端贡献合并解说	适用于 Chrome M129

什么是 Private Aggregation API

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

此 API 的主要函数称为 contributeToHistogram()。直方图运算可用来汇总数据（在 API 中称为“汇总键”）。直方图调用会累积值，并在以摘要报告的形式呈现例如，报告可能会显示或在您的第三方脚本中遇到错误。此操作在另一个 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 时，可以通过“不公开汇总”提交报告。

多接触点归因

本指南将在开发网站上发布，以便广告技术平台可以了解如何在“共享存储空间 + 私密聚合”中实现 MTA。

使用 Protected Audience API

Protected Audience API 支持重访定位和自定义受众群体用例，而私密汇总可让您报告来自买方和卖方 Worklet 的事件。该 API 可用于执行多种任务，例如衡量竞价出价的分布情况。

通过 Protected Audience API Worklet，您可以直接使用 contributeToHistogram() 汇总数据，也可以使用 contributeToHistogramOnEvent()（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 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 sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

每当有跨网站 iframe 内容加载时，上述代码示例都会调用不公开汇总。iframe 代码加载该 Worklet，而该 Worklet 使用已转换为汇总键（存储分区）的内容 ID 调用 Private Aggregation API。

contributeToHistogramOnEvent()

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

privateAggregation.contributeToHistogramOnEvent(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 来验证报告是否通过共享存储空间操作发送。

如需了解详情，请参阅举报验证说明。

互动和分享反馈

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

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