Private Aggregation API 概览

使用 Protected Audience 中的数据和 Shared Storage 中跨网站数据生成汇总数据报告。

为了提供 Web 所依赖的重要功能，我们构建了 Private Aggregation API，以便以可保护隐私的方式汇总和报告跨网站数据。

实现状态

什么是 Private Aggregation API

借助 Private Aggregation API，开发者可以使用 Protected Audience API 中的数据和 Shared Storage 中的跨网站数据生成汇总数据报告。

此 API 的主要函数称为 contributeToHistogram()。借助直方图操作，您可以汇总您定义的每个存储分区（在 API 中称为汇总键）中的用户数据。直方图调用会累积值，并以摘要报告的形式返回带噪声的汇总结果。例如，该报告可能会显示每位用户在多少个网站上看到过您的内容，或者在第三方脚本中发现 bug。此操作在另一个 API 的工作流中执行。

例如，如果您之前在共享存储空间中记录了受众特征和地理位置数据，则可以使用 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 都会生成可汇总报告，汇总服务后端会使用这些报告来生成摘要报告。

归因报告会将发生在不同时间的展示事件和转化事件收集的数据相关联。不公开汇总功能可衡量单个跨网站事件。

测试此 API

如需在本地测试 Private Aggregation API，请启用 chrome://settings/adPrivacy 下的所有广告隐私权 API。

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

使用演示

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

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

使用场景

Private Aggregation 是一个用于跨网站衡量的通用 API，可在 Shared Storage 和 Protected Audience API 工作台中使用。第一步是明确确定您要收集哪些信息。这些数据点是汇总键的基础。

使用共享存储空间

借助 Shared Storage，您可以在安全的环境中读取和写入跨网站数据，以防止数据泄露；借助 Private Aggregation API，您可以衡量存储在 Shared Storage 中的跨网站数据。

唯一身份用户覆盖面衡量

您可能想要衡量有多少唯一身份用户观看了其内容。Private Aggregation API 可以提供回答，例如“大约有 317 位唯一身份用户观看了内容 ID 861”。

您可以在共享存储空间中设置一个标志，以指明用户是否已看过相应内容。在首次访问时，如果不存在该标志，系统会调用“不公开汇总”，然后设置该标志。在用户的后续访问（包括跨网站访问）中，如果已设置该标志，您可以检查 Shared Storage，并跳过向 Private Aggregation 提交报告。如需详细了解实现这些衡量的方法，请参阅我们的覆盖面白皮书。

受众特征衡量

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

不公开汇总功能可以提供答案，例如“大约有 317 名来自德国的 18-45 周岁唯一身份用户”。使用 Shared Storage 访问第三方情境中的受众特征数据。稍后，您可以通过在汇总键中对年龄段和国家/地区维度进行编码，使用“不公开汇总”功能生成报告。

衡量 K 次以上频次

您可能需要衡量在给定浏览器中至少看到某项内容或广告 K 次的用户数量（其中 K 为预先选择的值）。

不公开汇总功能可以提供回答，例如“大约有 89 位用户至少观看了内容 ID 581 三次”。计数器可以在来自不同网站的共享存储空间中递增，并且可以在 worklet 中读取。当计数达到 K 时，您可以使用“不公开汇总”功能提交报告。

多接触点归因

营销归因是广告客户用来确定营销策略和后续广告互动对销售或转化所做的贡献的方法。

使用 Protected Audience API

Protected Audience API 支持再定位和自定义受众群体用例，Private Aggregation 则可让您报告买方和卖方 Worklet 中的事件。该 API 可用于衡量竞价出价的分布情况等任务。

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

可用的函数

Shared Storage API 和 Protected Audience API 工作流中提供的 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';

    // Don't 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 内容时，上述代码示例都会调用 Private Aggregation。iframe 代码会加载 worklet，而 worklet 会调用 Private Aggregation API，并将内容 ID 转换为汇总键 (bucket)。

contributeToHistogramOnEvent()

仅在 Protected Audience API 工作件中，我们提供了一种基于触发器的机制，以便仅在发生特定事件时发送报告。此函数还允许令牌桶和值取决于竞价过程中此时尚不可用的信号。

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 的衡量结果与 Private Aggregation 衡量结果进行比较，还可让您快速验证 API 集成。

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

调试模式仅适用于允许访问第三方 Cookie 的调用方。如果调用方无权访问第三方 Cookie，enableDebugMode() 将静默失败。

您还可以通过调用 privateAggregation.enableDebugMode({ <debugKey: debugKey> }) 来设置调试密钥，其中 BigInt 可用作调试密钥。调试键可用于关联基于 Cookie 的衡量数据与 Private Aggregation 衡量数据。

每个上下文只能调用一次这些方法。任何后续调用都会抛出异常。

// Enables debug mode
privateAggregation.enableDebugMode();

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

报告验证

Private Aggregation API 可在保护用户隐私的同时实现跨网站衡量。不过，不法分子可能会试图操纵这些衡量结果的准确性。为防止这种情况，您可以使用情境 ID 来验证报告的真实性。

设置情境 ID 有助于确保数据在贡献最终汇总结果时准确无误。具体方法如下：

• 防范非法或虚假报告：确保报告是通过合法且真实的 API 调用生成的，让恶意行为者难以伪造报告。
• 防止报告重放：检测并拒绝任何重复使用旧报告的尝试，确保每份报告只对汇总结果做出一次贡献。

共享存储空间

使用共享存储空间运行可发送可汇总报告的操作时，您可以在 worklet 之外设置不可预测的 ID。

此 ID 会嵌入到通过工作流创建的报告中。您可以在调用 run() 或 selectURL() 共享存储空间方法时，在 privateAggregationConfig 键下的 options 对象中指定它。

例如：

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

设置此 ID 后，您可以使用它来验证报告是否是从共享存储空间操作发送的。为防止信息泄露，无论 contributeToHistogram() 调用的次数如何，系统都会为每项共享存储空间操作发送一项报告（即使没有贡献）。

Private Aggregation API 发送可汇总报告时会随机延迟，最长可达 1 小时。不过，设置上下文 ID 来验证报告可以缩短此延迟时间。在这种情况下，从共享存储空间操作开始起，会有较短的固定延迟时间（5 秒）。

工作流示例（如上图所示）：

1. 使用指定上下文 ID 的 Private Aggregation 配置运行 Shared Storage 操作，并生成可汇总的报告。
2. 情境 ID 会嵌入到发送到您服务器的生成的可汇总报告中。
3. 您的服务器会收集生成的可汇总报告。
4. 服务器上的进程会将每个可汇总报告中的情境 ID 与您存储的情境 ID 进行比对，以确保其有效性，然后再将报告批量处理并发送到汇总服务。

上下文 ID 验证

您可以通过几种不同的方式验证发送到收集器服务器的传入报告，然后再将其发送到汇总服务。如果上下文 ID 存在以下情况，系统可能会拒绝包含无效上下文 ID 的报告：

• 未知：如果收到的报告包含您的系统未创建的情境 ID，您可以将其舍弃。这样可以防止未知或恶意行为者向汇总流水线注入数据。
• 重复报告：如果您收到两个（或更多）具有相同情境 ID 的报告，则表示您需要选择要舍弃哪个报告。
• 在垃圾内容检测中被标记：
  • 如果您在处理用户的报告时检测到可疑活动（例如用户活动突然发生变化），可以将其舍弃。
  • 您可以将报告与其情境 ID 和任何相关信号（例如用户代理、引荐来源等）一起存储。之后，在分析用户行为并识别新的垃圾内容指标时，您可以根据其关联的情境 ID 和信号重新评估已存储的报告。这样，您就可以舍弃来自显示可疑活动的用户的报告，即使这些用户最初未被标记为可疑也是如此。

互动和分享反馈

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

• GitHub：阅读说明文档，提出问题并参与讨论。
• 开发者支持：在 Privacy Sandbox 开发者支持代码库中提问和参与讨论。
• 加入 Shared Storage API 群组和 Protected Audience API 群组，及时了解与 Private Aggregation 相关的最新公告。