了解如何使用该 API,包括如何使用 Chrome 标志进行测试。
实现状态
- Topics API 已完成公开讨论阶段,目前可供 99% 的用户使用,扩容到可以达到 100%。
- 如需提供关于 Topics API 的反馈,请在 Topics 铺垫消息中创建一个问题,或参与改进网络广告业务群组中的讨论。解释器中有一些尚未解决的问题,但仍需进一步定义。
- Privacy Sandbox 时间表提供了 Topics API 和其他 Privacy Sandbox 提案的实现时间表。
- Topics API:最新更新详细介绍了 Topics API 和实现的相关变更和增强功能。
体验演示
我们提供两个 Topics API 演示,可让您以单个用户的身份试用 Topics。
- JavaScript API 演示:topics-demo.glitch.me。
- 标头演示:topics-fetch-demo.glitch.me
您还可以运行 Topics Colab 来试用 Topics 分类器模型。
使用 JavaScript API 访问主题并将其记录为观察对象
Topics JavaScript API 有一种方法:document.browsingTopics()
。这样做有两个目的:
- 告知浏览器将当前网页访问记录为已观察到调用方,以便稍后为用户计算主题(针对调用方)。
- 访问调用方已观察到的用户主题。
该方法会返回一个 promise,可解析为最多包含三个主题的数组,最近的三个 epoch 各一个,按随机顺序排列。周期是指在 Chrome 实现中设为一周的时间段。
document.browsingTopics()
返回的数组中的每个主题对象都具有以下属性:
configVersion
:标识当前 Topics API 配置的字符串,例如chrome.2
modelVersion
:标识用于推断网站主题的机器学习分类器的字符串,例如4
taxonomyVersion
:标识浏览器使用的一组主题的字符串,例如2
topic
:用于标识分类中的主题的数字,例如309
version
:将configVersion
、taxonomyVersion
和modelVersion
串联的字符串,例如chrome.2:2:4
随着我们采纳生态系统反馈并对 API 进行迭代,本指南中介绍的参数和该 API 的详细信息(例如分类规模、每周计算的主题数以及每次调用返回的主题数)可能会发生变化。
检测对 document.browsingTopics 的支持
在使用该 API 之前,请检查浏览器是否支持该 API,以及该 API 是否在文档中可用:
'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
console.log('document.browsingTopics() is supported on this page') :
console.log('document.browsingTopics() is not supported on this page');
使用 JavaScript API 访问主题
下面是一个基本示例,展示了当前用户访问主题时可能使用的 API。
try {
// Get the array of top topics for this user.
const topics = await document.browsingTopics();
// Request an ad creative, providing topics information.
const response = await fetch('https://ads.example/get-creative', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(topics)
})
// Get the JSON from the response.
const creative = await response.json();
// Display ad.
} catch (error) {
// Handle error.
}
访问主题而不修改状态
document.browsingTopics()
会返回调用方针对当前用户观察到的主题。默认情况下,该方法还会使浏览器记录调用方所观察到的当前网页访问,以便稍后用于主题计算。从 Chrome 108 开始,可以向该方法传递一个可选参数,用于跳过记录网页访问操作:{skipObservation:true}
。
也就是说,{skipObservation:true}
表示方法调用不会导致当前网页被纳入主题的计算中。
使用标头访问主题并将其标记为观察对象
借助请求和响应标头,您可以访问主题,还可以将网页浏览标记为“已观察”。
使用标头方法比使用 JavaScript API 的性能要高得多,因为此 API 需要创建一个跨源 iframe 并从中调用 document.browsingTopics()
。(对于此调用,必须使用跨源 iframe,因为调用此 API 的上下文将用于确保浏览器返回适合调用方的主题。)Topics 解释器进一步讨论了以下内容:是否应该有办法使用“抓取”作为请求标头来发送主题?.
您可以通过 fetch()
或 XHR
请求的 Sec-Browsing-Topics
标头访问主题。
在对请求的响应上设置 Observe-Browsing-Topics: ?1
标头会导致浏览器记录调用方观察到的当前页面访问,以便稍后用于主题计算。
可以通过两种方式使用 HTTP 标头访问和观察主题:
fetch()
:将{browsingTopics: true}
添加到fetch()
请求的 options 参数中。Topics 标题演示展示了一个简单的示例。- iframe 属性:将
browsingtopics
属性添加到<iframe>
元素,或设置等效的 JavaScript 属性iframe.browsingTopics = true
。iframe 来源的可注册网域是调用方网域:例如,对于<iframe src="https://example.com" browsingtopics></iframe>
,调用方为example.com
。
关于标题的一些其他说明:
- 系统将跟踪重定向,并且在重定向请求中发送的主题将特定于重定向网址。
- 除非有相应的响应标头,否则请求标头不会修改调用方的状态。也就是说,如果没有响应标头,系统就不会将网页访问记录为已观察,因此不会影响用户下一个周期的主题计算。
- 只有当相应请求包含主题标头时,系统才会支持响应标头。
- 请求的网址会提供记录为调用方网域的可注册网域。
调试 API 实现
启用 Topics API 后,您便可在桌面版 Chrome 中使用 chrome://topics-internals
页面。系统会显示当前用户的主题、为主机名推断出的主题以及有关 API 实现的技术信息。我们会根据开发者的反馈对该网页设计进行迭代和改进:请前往 bugs.chromium.org 添加反馈意见。
查看针对浏览器计算出的主题
用户可以通过查看 chrome://topics-internals
,查看其浏览器在当前和上一个周期中观察到的主题的相关信息。
![已选择“Topics State”面板的 chrome://topics-internals 页面。](https://developers.google.cn/static/privacy-sandbox/assets/images/the-chrometopics-inter-0a0a54332c409.png?authuser=5&hl=hu)
此屏幕截图显示最近访问过的网站包括 topics-demo-cats.glitch.me
和 cats-cats-cats-cats.glitch.me
。这会导致 Topics API 选择 Pets
和 Cats
作为当前周期的两个热门主题。由于没有足够的浏览记录(在观察主题的网站上),无法提供五个主题,因此其余 3 个主题是随机选择的。
“观察对象的上下文域名(经过哈希处理)”列会提供被观察到主题的主机名的哈希值。
查看系统推断的主机名主题
您还可以查看 chrome://topics-internals
中一个或多个主机名由 Topics 分类器模型推断出的主题。
![已选中“分类器”面板的 chrome://topics-internals 页面。](https://developers.google.cn/static/privacy-sandbox/assets/images/the-chrometopics-inter-680196727dbe8.png?authuser=5&hl=hu)
Topics API 的当前实现仅根据主机名推断主题,而不会根据网址的任何其他部分推断主题。
仅使用主机名(不带协议或路径)可查看从 chrome://topics-internals
分类器中推断出的主题。如果您尝试在“Host”字段中添加“/”,chrome://topics-internals
会显示错误。
查看 Topics API 信息
您可以在 chrome://topics-internals
中找到有关 Topics API 实现和设置(例如分类版本和纪元时长)的信息。这些值反映的是 API 的默认设置或从命令行成功设置的参数。这可能有助于确认命令行标志按预期运行。
在此示例中,time_period_per_epoch
设置为 15 秒(默认为 7 天)。
![已选中“功能和参数”面板的 chrome://topics-internals 页面。](https://developers.google.cn/static/privacy-sandbox/assets/images/chrometopics-internals-a56a143c41aa1.png?authuser=5&hl=hu)
屏幕截图中显示的参数对应于从命令行运行 Chrome 时可设置的标志。例如,topics-fetch-demo.glitch.me 中的演示建议使用以下标志:
--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting
以下列表介绍了每个参数、其默认值和用途。
Chrome flag
BrowsingTopics
- 默认值:已启用
- 是否启用 Topics API。
PrivacySandboxAdsAPIsOverride
- 默认值:启用
- 启用广告 API:Attribution Reporting、Protected Audience、Topics、Fenced Frame。
PrivacySandboxSettings4
- 默认值:disabled
- 启用第 4 个版本的 Privacy Sandbox 界面设置。
OverridePrivacySandboxSettingsLocalTesting
- 默认值:已启用
- 启用后,浏览器便不再需要启用底层设置即可启用 Privacy Sandbox 功能。
BrowsingTopicsBypassIPIsPubliclyRoutableCheck
- 默认值:停用
- 启用后,在确定页面是否有资格纳入主题计算时,系统会绕过 IP 地址是否可公开路由的检查。
BrowsingTopics:number_of_epochs_to_expose
- 默认值:3
- 用于计算主题的周期数,以向请求上下文提供主题。浏览器将在内部最多保留 N+1 个周期。
BrowsingTopics:time_period_per_epoch
- 默认值:7d-0h-0m-0s
- 每个周期的时长。 对于调试,将此设置为(例如)15 秒(而不是默认的 7 天)会很有用。
BrowsingTopics:number_of_top_topics_per_epoch
- 默认值:5
- 每个周期计算的主题数。
BrowsingTopics:use_random_topic_probability_percent
- 默认值:5
- 一个周期内的单个主题从整个主题分类中随机返回的概率。随机性取决于周期和网站。
BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
- 默认值:3
- 将用于针对调用上下文过滤主题的 API 使用情况数据(即主题观察)的周期数。
BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
- 默认值:1000
- 为每个热门主题保留的观察对象上下文网域数上限。这样做的目的是限制使用的内存。
BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
- 默认值:100000
- 对于 API 使用情境的每个查询,允许从数据库中检索到的条目数上限。系统会在每个周期的主题计算时执行一次查询。这样做的目的是限制峰值内存用量。
BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
- 默认值:30
- 每次网页加载时允许存储的 API 使用情况上下文网域数量上限。
BrowsingTopics:config_version
- 默认值:1
- 对 Topics API 配置参数进行编码。每个版本号应仅映射到一个配置集。对于本地测试而言,在不更新
config_version
的情况下更新配置参数通常应该没有问题,但在某些情况下,可能会使浏览器处于不一致的状态,并可能导致浏览器崩溃,例如更新number_of_top_topics_per_epoch
。 BrowsingTopics:taxonomy_version
- 默认值:1
- API 使用的分类版本。
选择退出您的网站
要停止针对网站上的特定网页计算主题,您可以在某个网页上添加 Permissions-Policy: browsing-topics=()
Permissions-Policy 标头,以防止该网页上的所有用户计算主题。对您网站上其他网页的后续访问不会受到影响:如果您设置了一项政策来屏蔽某个网页上的 Topics API,其他网页不会受到影响。
您还可以使用 Permissions-Policy
标头控制第三方对 Topics API 的访问权限,从而控制哪些第三方有权访问您网页上的主题。使用 self
以及您要允许访问该 API 的任何网域作为标头的参数。例如,如需在除您自己的来源和 https://example.com
之外的所有浏览上下文中完全禁止使用 Topics API,请设置以下 HTTP 响应标头:
Permissions-Policy: browsing-topics=(self "https://example.com")
后续步骤
- 详细了解具体主题及其工作原理。
- 试用演示。
了解详情
互动和分享反馈
- GitHub:阅读 Topics API 说明,以及在 API 代码库中提出问题和关注相关问题的讨论。
- W3C:在 Improving Web Advertising Business Group(改进网络广告业务小组)中讨论行业用例。
- 通告:加入或查看邮寄名单。
- Privacy Sandbox 开发者支持:在 Privacy Sandbox 开发者支持代码库中提问并加入讨论。
- Chromium:提交 Chromium 错误,以询问有关目前可在 Chrome 中测试的实现的问题。