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 基础知识文档。

与 Attribution Reporting 的区别

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。

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

使用演示版

您可访问 goo.gle/shared-storage-demo 来查看共享存储空间专用汇总 API 的演示，并可在 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 位唯一身份用户看过 Content ID 861”之类的答案。

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

受众特征衡量

您可能希望衡量在不同网站上看到您内容的用户的人口统计信息。

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

K+ 频次衡量

您可能希望衡量在给定浏览器上至少看到过某内容或广告 K 次的用户数量，其中 K 是预先选择的值。

私密汇总可以提供“大约有 89 位用户至少 3 次观看过内容 ID 581”之类的答案。计数器可以在共享存储空间中从不同网站递增，并且可以在工作单元中读取。当数量达到 K 时，可以使用私密聚合提交报告。

多接触点归因

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

借助 Protected Audience API

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

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

可用函数

以下函数可在 Shared Storage 和 Protected Audience API 工作程序中提供的 privateAggregation 对象中使用。

contributeToHistogram()

您可以调用 privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })，其中聚合键为 bucket，可聚合的值为 value。对于 bucket 参数，需要提供 BigInt。对于 value 参数，需要提供整数值。

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

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 会使用转换为汇总键（存储分区）的内容 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 的衡量与 Private Aggregation 衡量，还可让您快速验证 API 集成。

在工作程序中调用 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 调用生成，从而使不良行为者难以伪造报告。
• 防止报告重放：检测并拒绝任何重复使用旧报告的尝试，确保每份报告只对汇总结果做出一次贡献。

Shared Storage

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

此 ID 嵌入在根据工作单元创建的报告中。您可以在调用 run() 或 selectURL() 共享存储方法时，在 privateAggregationConfig 键下的 options 对象中指定该参数。

例如：

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

设置此 ID 后，您可以使用它来验证报告是否是从您的共享存储区操作发送的。为防止信息泄露，每个共享存储空间操作（即使未做出任何贡献）仅发送一份报告，无论 contributeToHistogram() 调用次数是多少。

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

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

1. 运行 Shared Storage 操作，其中包含指定了上下文 ID 的 Private Aggregation 配置，并生成可汇总的报告。
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 相关的最新公告。