了解如何使用该 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,该 promise 可解析为最多包含三个主题的数组,最近的三个周期分别对应一个主题(按随机顺序)。“周期”是指 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}
意味着方法调用不会导致当前页面计入主题计算。
使用标头访问主题并将其标记为已观察
您可以访问主题,还可以借助以下工具将网页访问标记为观察到: request 和 响应标头。
使用标头方法的性能比使用 JavaScript API 高得多,因为该 API 需要创建跨源 iframe 并从中进行 document.browsingTopics()
调用。(调用必须使用跨源 iframe,因为调用 API 的上下文将用于确保浏览器返回适合调用方的主题。)Topics 解释器中进一步讨论了:应该有办法使用“抓取方式”请求标头来发送主题吗?.
您可以从 fetch()
或 XHR
请求的 Sec-Browsing-Topics
标头访问主题。
在请求的响应中设置 Observe-Browsing-Topics: ?1
标头
使浏览器记录调用方观察到的当前网页访问情况;
以便稍后在主题计算中使用。
您可以通过以下两种方式使用 HTTP 标头来访问和观察主题:
fetch()
:将{browsingTopics: true}
添加到fetch()
请求的 options 参数中。主题标头演示展示了这方面的简化示例。- 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=7&hl=bg)
此屏幕截图显示最近访问过的网站包括 topics-demo-cats.glitch.me
和 cats-cats-cats-cats.glitch.me
。这会使 Topics API 选择 Pets
和 Cats
作为当前周期的两个热门主题。其余三个主题是随机选择的,因为(在观察主题的网站上)没有足够的浏览记录来提供 5 个主题。
观测到的上下文网域(经过哈希处理)列提供观测到主题的主机名的哈希值。
查看系统根据主机名推断的主题
您还可以查看 chrome://topics-internals
中的主题分类器模型为一个或多个主机名推断的主题。
![已选中“Classifier”面板的 chrome://topics-internals 页面。](https://developers.google.cn/static/privacy-sandbox/assets/images/the-chrometopics-inter-680196727dbe8.png?authuser=7&hl=bg)
Topics API 的当前实现仅根据主机名推断主题;而不是来自网址的任何其他部分
仅使用主机名(不带协议或路径)可查看通过 chrome://topics-internals
分类器推断出的主题。如果您尝试添加“/”,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=7&hl=bg)
屏幕截图中显示的参数对应于从命令行运行 Chrome 时可以设置的标志。例如,topics-fetch-demo.glitch.me 中的演示建议使用以下标记:
--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting
以下列表介绍了每个参数、其默认值及其用途。
Chrome 旗帜
BrowsingTopics
- 默认值:已启用
- 确定是否已启用 Topics API。
PrivacySandboxAdsAPIsOverride
- 默认值:已启用
- 支持各种广告 API:Attribution Reporting、Protected Audience、Topics、Fenced Frames。
PrivacySandboxSettings4
- 默认值:已停用
- 启用 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
- 分类 版本
在您的网站中停用该功能
通过在网页上添加 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 中测试的实现的问题。