Topics API 开发者指南

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

实现状态

  • The Topics API has completed the public discussion phase and is currently available to 99 percent of users, scaling up to 100 percent.
  • To provide your feedback on the Topics API, create an Issue on the Topics explainer or participate in discussions in the Improving Web Advertising Business Group. The explainer has a number of open questions that still require further definition.
  • The Privacy Sandbox timeline provides implementation timelines for the Topics API and other Privacy Sandbox proposals.
  • Topics API: latest updates details changes and enhancements to the Topics API and implementations.

试用演示版

我们提供两个 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")

后续步骤

了解详情

Engage and share feedback