本文档是关于使用共享存储空间和专用存储空间的快速入门指南 汇总。您需要了解这两个 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。
使用 JavaScript 广告技术平台可以执行特定的共享存储空间功能 例如在 JavaScript 外部设置、附加和删除值 Worklet。不过,读取共享存储空间和执行 私有聚合必须通过 JavaScript Worklet 完成。 可在 JavaScript Worklet 外部使用的方法 提议的 API 途径 - 外部 worklet。
操作期间 Worklet 中使用的方法可以在 提议的 API Surface - 在 worklet。
使用响应标头
与 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
。
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 和文档的反馈。