Topics API 开发者指南

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

实现状态

试用演示版

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

您还可以运行 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 的性能要高得多。

您可以通过 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 页面。
chrome://topics-internals 页面“Topics State”面板显示了主题 ID、随机和真实的主题分配，以及分类和模型版本。

此屏幕截图显示最近访问过的网站包括 topics-demo-cats.glitch.me 和 cats-cats-cats-cats.glitch.me。这会导致 Topics API 选择 Pets 和 Cats 作为当前周期的两个热门主题。由于没有足够的浏览记录（在观察主题的网站上），无法提供五个主题，因此其余 3 个主题是随机选择的。

“观察对象的上下文域名（经过哈希处理）”列会提供被观察到主题的主机名的哈希值。

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

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

已选中“分类器”面板的 chrome://topics-internals 页面。
chrome://topics-internals 页面分类器面板显示了所选的主题、访问过的主机以及模型版本和路径。

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 页面。
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 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")

后续步骤

了解详情

互动和分享反馈