Topics API 开发者指南

了解如何使用该 API,包括如何使用 Chrome 标志进行测试。

实现状态

试用演示

我们提供了两个 Topics API 演示,可让您以单个用户身份试用 Topics。

您还可以运行 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:连接 configVersiontaxonomyVersionmodelVersion 的字符串,例如 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,查看有关其浏览器在当前周期和之前的周期中观察到的主题的信息。

<ph type="x-smartling-placeholder">
</ph> 选中了“Topics State”面板的 chrome://topics-internals 页面。
chrome://topics-internals 页面中的“主题状态”面板会显示主题 ID、随机和真实的主题分配,以及分类和模型版本。

此屏幕截图显示最近访问过的网站包括 topics-demo-cats.glitch.mecats-cats-cats-cats.glitch.me。这会使 Topics API 选择 PetsCats 作为当前周期的两个热门主题。其余三个主题是随机选择的,因为(在观察主题的网站上)没有足够的浏览记录来提供 5 个主题。

观测到的上下文网域(经过哈希处理)列提供观测到主题的主机名的哈希值。

查看系统根据主机名推断的主题

您还可以查看 chrome://topics-internals 中的主题分类器模型为一个或多个主机名推断的主题。

<ph type="x-smartling-placeholder">
</ph> 已选中“Classifier”面板的 chrome://topics-internals 页面。
chrome://topics-internals 页面“分类器”面板会显示所选主题、访问过的主机以及模型版本和路径。

Topics API 的当前实现仅根据主机名推断主题;而不是来自网址的任何其他部分

仅使用主机名(不带协议或路径)可查看通过 chrome://topics-internals 分类器推断出的主题。如果您尝试添加“/”,chrome://topics-internals 会显示错误输入新名称

查看 Topics API 信息

您可以在 chrome://topics-internals 中找到有关 Topics API 实现和设置的信息,例如分类版本和周期时长。这些值反映了 API 的默认设置或从命令行成功设置的参数。这可能有助于确认命令行标志是否已按预期运行。

在此示例中,time_period_per_epoch 设为 15 秒(默认为 7 天)。

<ph type="x-smartling-placeholder">
</ph> chrome://topics-internals 页面,其中已选择“功能和参数”面板。
chrome://topics-internals 功能和参数面板会显示已启用的功能、每个周期的时间、用于计算主题的周期数、分类版本和其他设置。

屏幕截图中显示的参数对应于从命令行运行 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")

后续步骤

了解详情

互动和分享反馈