共享存储空间和私有聚合实现快速入门

本文档是关于使用共享存储空间和专用存储空间的快速入门指南 汇总。您需要了解这两个 API，因为共享存储空间 存储值，“私密汇总”会创建可汇总报告。

目标受众群体：广告技术平台和衡量服务提供商。

试用演示

试用现场演示。按照相关步骤操作 在演示说明中了解如何启用 Privacy Sandbox API。正在打开 Chrome 开发者工具可帮助您直观呈现不同用例的结果。应用场景 提供：

• 不公开汇总
  • Unique Reach 衡量
  • 受众特征衡量
  • K+ 频次衡量
• 一般用法
  • 测量围栏框架内的悬停事件
  • 顶级导航
  • 控制第三方可写入的位置

如何查看共享的存储空间

如需查看存储在共享存储空间中的内容，请使用 Chrome 开发者工具。存储的数据 位于 Application -> Shared Storage 中。

查看“不公开汇总”报告

如需查看发送的可汇总报告，请前往 chrome://private-aggregation-internals。启用调试模式后，报告 会立即（无延迟）发送到 [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage 以及要发送至 [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage。

如需启用调试功能，请按照调试一文中的说明进行操作。 部分。

Shared Storage API

为防止跨网站跟踪，浏览器已经开始对 包括本地存储、Cookie 等。但还有一些应用场景 需要未分区存储的工作负载Shared Storage API 提供 跨不同的顶级网站无限写入权限，同时可保护隐私 读取权限。

共享存储空间仅限于上下文源（ sharedStorage）。

共享存储空间对每个来源都有容量限制，每个条目限于一个 最多 个字符。如果达到该限制，系统将不再继续输入 存储的数据。有关数据存储限制的说明，请参阅共享存储空间 铺垫消息。

调用共享存储空间

广告技术平台可以使用 JavaScript 或响应标头向共享存储空间写入数据。 从共享存储空间读取数据只能在隔离的 JavaScript 中进行 称为 Worklet。

借助 worklet，您可以运行特定的 JavaScript 函数并将信息返回给请求者。在 Worklet 中，您可以执行 JavaScript，但无法与外部页面进行交互或通信。

Worklet 通过 Shared Storage API 存储和提取数据。

• 使用 JavaScript 广告技术平台可以执行特定的共享存储空间功能 例如在 JavaScript 外部设置、附加和删除值 Worklet。不过，读取共享存储空间和执行 私有聚合必须通过 JavaScript Worklet 完成。 可在 JavaScript Worklet 外部使用的方法 提议的 API 途径 - 外部 worklet。

  操作期间 Worklet 中使用的方法可以在 提议的 API Surface - 在 worklet。

• 使用响应标头

  此功能在 M119 中开始提供。

  与 JavaScript 类似，只有设置、附加、 和删除共享存储空间中的值可以使用响应标头。接收者 在响应标头 Shared-Storage-Writable: ?1 中使用共享存储空间 必须包含在请求标头中

  如需从客户端发起请求，请运行以下代码，具体取决于 您选择的方法：

  • 使用 fetch()

      fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
  

  • 使用 iframe 或 img 标记

      <iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
  

  • 将 IDL 属性与 iframe 或 img 标记结合使用

      let iframe = document.getElementById("my-iframe");
      iframe.sharedStorageWritable = true;
      iframe.src = "https://a.example/path/for/updates";
  

有关更多信息，请参阅共享存储空间：响应 标头。

写入共享存储空间

要写入共享存储空间，请从外部或外部调用 sharedStorage.set() JavaScript worklet。如果从 Worklet 外部调用，数据将写入 发出调用的浏览上下文的来源。如果调用自 在 Worklet 内，数据会写入浏览上下文的原点 加载该 Worklet。所设置的密钥的失效日期为 30 天（自上次更新后）。

ignoreIfPresent 字段为可选字段。如果存在并设置为 true，则密钥 如果已存在，则不会更新。密钥有效期从以下日期续订为 30 天： 调用 set()。

如果在同一网页加载过程中以相同的 键，系统会覆盖键的值。建议您最好使用 如果键需要保留之前的值，则为 sharedStorage.append()。

• 使用 JavaScript

  在 Worklet 之外：

  window.sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: true });
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: false });
  // Shared Storage: {'myKey': 'myValue2'}
  

  同样，在 Worklet 内：

  sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
  

• 使用响应标头

  您还可以使用响应标头向共享存储空间写入数据。为此，请使用 Shared-Storage-Write 以及以下内容 命令：

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
  

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
  

  多项内容之间可以以英文逗号分隔，也可以组合使用 set、append、 delete和clear。

  Shared-Storage-Write :
  set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
  

附加值

您可以使用附加方法为现有键附加值。如果密钥 不存在，则调用 append() 会创建键并设置值。这可以 使用 JavaScript 或响应标头完成。

• 使用 JavaScript

  如需更新现有键的值，请使用 sharedStorage.append() 内部或外部。

  window.sharedStorage.append('myKey', 'myValue1');
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.append('myKey', 'myValue2');
  // Shared Storage: {'myKey': 'myValue1myValue2'}
  window.sharedStorage.append('anotherKey', 'hello');
  // Shared Storage: {'myKey': 'myValue1myValue2', 'anotherKey': 'hello'}
  

  如需在 Worklet 内附加内容，请执行以下操作：

  sharedStorage.append('myKey', 'myValue1');
  

• 使用响应标头

  与在共享存储空间中设置值类似，您可以使用 响应标头中的 Shared-Storage-Write，以传入键值对。

  Shared-Storage-Write : append;key="myKey";value="myValue2"
  

从共享存储空间读取内容

您只能从 Worklet 中读取共享存储空间。

await sharedStorage.get('mykey');

加载 Worklet 模块的浏览上下文的来源 决定要读取谁的共享存储空间

从共享存储空间中删除

您可以使用 JavaScript 从共享存储空间 也可以在 Worklet 外部使用，或者将响应标头与 delete() 搭配使用。删除 同时对所有键使用 clear()。

• 使用 JavaScript

  要从 Worklet 外部从共享存储空间删除，请执行以下操作：

  window.sharedStorage.delete('myKey');
  

  如需从 Worklet 内部从共享存储空间中删除，请执行以下操作：

  sharedStorage.delete('myKey');
  

  如需从 Worklet 外部一次性删除所有键，请运行以下命令：

  window.sharedStorage.clear();
  

  如需从 Worklet 内一次性删除所有键，请执行以下操作：

  sharedStorage.clear();
  

• 使用响应标头

  如要使用响应标头删除值，您还可以使用 Shared-Storage-Write 来传递要删除的密钥。

  delete;key="myKey"
  

  如需使用响应标头删除所有键，请执行以下操作：

  clear;
  

上下文切换

共享存储空间数据会写入 origin （例如 https://example.adtech.com） 来源。

当您使用 <script> 代码加载第三方代码时，系统会执行代码 在嵌入器的浏览上下文中。因此，如果第三方代码 调用 sharedStorage.set() 后，数据会写入嵌入器的共享 存储空间。当您在 iframe 中加载第三方代码时，该代码会收到 新的浏览上下文，其来源就是 iframe 的来源。因此， 从 iframe 进行的 sharedStorage.set() 调用会将数据存储在 iframe 源的共享存储空间。

第一方环境

如果第一方网页嵌入了调用 sharedStorage.set() 或 sharedStorage.delete()：存储键值对 在第一方环境中出现的情况

第三方情境

可以通过以下方式将键值对存储在广告技术平台或第三方情境中： 创建 iframe 并在 JavaScript 代码中调用 set() 或 delete()： 。

Private Aggregation API

如需衡量共享存储空间中存储的可汇总数据，您可以使用私有存储空间 Aggregation API。

如需创建报告，请在包含如下参数的 Worklet 内调用 contributeToHistogram()： 范围和值。桶由一个无符号的 128 位整数表示，该整数 必须作为 BigInt 传入函数。该值是一个正整数。

为保护隐私，报告的载荷（其中包含存储分区和值） 是在传输过程中加密的，只能使用 汇总服务。

浏览器还会限制网站可对输出做出的贡献 查询。具体而言，贡献 预算 用于限制给定浏览器针对单个网站的所有报告的总和 所有时间段的预测。如果超出当前预算， 系统将不会生成报告。

privateAggregation.contributeToHistogram({
  bucket: BigInt(myBucket),
  value: parseInt(myBucketValue)
});

执行共享存储空间和专用聚合

使用跨源 iframe

调用共享存储空间 Worklet 需要使用 iframe。

在广告的 iframe 中，通过调用 addModule() 加载 Worklet 模块。要运行 在 sharedStorageWorklet.js worklet 文件中注册的方法，位于 同一个广告 iframe JavaScript，调用 sharedStorage.run()。

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

在 Worklet 脚本中，您需要创建一个具有异步 run 的类 方法。register 此类要在广告的 iframe 中运行。内部 sharedStorageWorklet.js:

class SharedStorageReportOperation {
  async run(data) {
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket: bucket,
      value: value
    });
  }
}
register('shared-storage-report',
  SharedStorageReportOperation);

使用跨源请求

共享存储空间和专用聚合支持创建跨源 Worklet 而无需使用跨源 iframe。

第一方网页可以调用对跨源的 createWorklet() 调用 JavaScript 端点。

async function crossOriginCall() {
  let privateAggregationWorklet = await sharedStorage.createWorklet(
    'https://cross-origin.dev/js/worklet.js',
  );
  await privateAggregationWorklet.run('pa-worklet');
}
crossOriginCall();

跨源 JavaScript 端点必须使用标头进行响应 Shared-Storage-Cross-Origin-Worklet-Allowed并允许使用以下内容进行跨域访问： Access-Control-Allow-Origin。

警告 ：worklet 脚本响应标头需要使用 CORS Access-Control-Allow-Origin和 Shared-Storage-Cross-Origin-Worklet-Allowed 标头。谨慎提供 访问您的 Worklet，因为请求您的 Worklet 的不是您的文档 Worklet。

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1
Access-Control-Allow-Origin : https://first-party.dev

使用 createWorklet() 创建的 Worklet 将具有 selectURL 和 run()。 addModule()无法用于此目的。

class CrossOriginWorklet {
  async run(data){
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket: bucket,
      value: value
    });
  }
}

调试

如需启用调试功能，请在同一页面调用 enableDebugMode() JavaScript 方法， 使用共享存储空间和专用聚合的上下文。这将是 在同一背景下用于将来的报告。

privateAggregation.enableDebugMode();

若要将报告与触发它们的上下文相关联，您可以设置 传递给 JavaScript 调用的 64 位无符号整数调试密钥。通过 debugKey的会员级别为BigInt。

privateAggregation.enableDebugMode({debugKey: 1234});

调试共享存储空间

共享存储空间返回一条常规错误消息：

Promise is rejected without and explicit error message

您可以通过使用以下代码封装调用来调试共享存储空间： try-catch 。

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

调试不公开汇总

报告会发送至 /.well-known/private-aggregation/report-shared-storage 和 /.well-known/private-aggregation/debug/report-shared-storage。调试报告 会收到类似于以下 JSON 的载荷。此载荷定义了 api 设置为“shared-storage”

{
   "aggregation_coordinator_origin": "https://publickeyservice.msmt.gcp.privacysandboxservices.com",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhlKJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAB1vNFaJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAGlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "1569ab37-da44-4a26-80d9-5ed6524ab2a7",
      "payload": "/9nHrWn1MnJWRxFvanbubciWE9mPyIij6uYLi5k351eQCd3/TZpe2knaatUNcniq4a4e61tmKebv50OmMRZFnnCfcAwIdIgLHu1a3en97PojqWJBfO52RiVMIcP7KQTLzMxq2LhvPSdV4zjXo1Teu/JuIK3LIyis3vUMpS+tUAX0QV+I6X5SVmZFiNW9aMb8DwLOtqrBy5JJ/EkOIY0G+1Fi1/3R7UtKsqM1o71A/OzdmlNkwO7EV/VUNinGvWnd19FvDHe/kqkNdTHKbhAnMmbZzHW9bsEQS81leElCla6BTdbdbeeFU/jbTj0AOaoNOIe5r7FU5NG6nW4ULXTCbLLjTQ1mtl3id3IP41Zin1JvABCDC/HUSgLFz8EUqkmbMIOlMfNYA79aURq6FqE0GO0HtICYf0GPNdVv7p4jY3FNn6+JS4l5F3t+3lP9ceo4IpCE+31jzMtYJ+19xFh6C5ufteBR/iknZFcc1w3caQBhgRl5jt8DbaOzYcW4690H8Ul4Oh2wRO+6/njifk+pExLay/O5swLi2lUUph5OUEaaztwwzh2mnhwIBxMkPnfsGihiF+5KDEajVfMZ3NLsIDoZO+l4RTZrkqE+jVkAqaZGBiCIx42Edp/JV0DXfrryypCdQBZr8iEbSzCM9hKsMfLN7S/VkPe5rDwOZbhKCn5XXgfGz5tSx/KbZgsQf4OCEhwAyNPHAh3MHU7xmkQ3pKg4EIUC/WOtKAlVDOtDMmPPoQY1eAwJhw9SxZaYF1kHjUkTm3EnGhgXgOwCRWqeboNenSFaCyp6DbFNI3+ImONMi2oswrrZO+54Tyhca5mnLIiInI+C3SlP4Sv1jFECIUdf/mifJRM5hMj6OChzHf4sEifjqtD4A30c4OzGexWarie2xakdQej9Go4Lm0GZEDBfcAdWLT9HwmpeI2u4HDAblXDvLN8jYFDOOtzOl90oU7AwdhkumUCFLRadXAccXW9SvLfDswRkXMffMJLFqkRKVE1GPonFFtlzaRqp7IgE8L6AOtz6NDcxAjHnEuzDPPMcWMl1AFH0gq7h"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"80d93c0a-a94e-4ab7-aeb5-a4ecd4bfc598\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1717784740\",\"version\":\"0.1\"}"
}

调试明文载荷

debug_cleartext_payload为 Base64 采用 CBOR 编码。您可以查看存储分区 值或使用解码器，或使用 JavaScript 代码位于共享存储空间 解码器。

后续步骤

以下页面介绍了共享存储空间和专用存储空间的 Aggregation API。

• 共享存储空间简介（Chrome 开发者版）
• 共享存储空间用例（Chrome 开发者）
• 不公开汇总简介（Chrome 开发者版）
• 共享存储空间说明 (GitHub)
• 不公开汇总说明 (GitHub)
• 共享存储空间和专用聚合演示

熟悉 API 后，您就可以开始收集报告 它们以 POST 请求的形式发送到以下端点： 请求正文。

• 调试报告 - context-origin/.well-known/private-aggregation/debug/report-shared-storage
• 报告 - context-origin/.well-known/private-aggregation/report-shared-storage

收集报告后，您可以使用本地测试 工具 或设置用于汇总的可信执行环境 服务 即可获取汇总报告

欢迎分享反馈

您可以在 GitHub 上分享您对 API 和文档的反馈。

• 共享存储空间
• 不公开汇总