Topics API 开发者指南

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

要点：Privacy Sandbox Relevance and Measurement 源试用已于 2023 年 9 月 20 日结束，相关 API 现已面向 99% 的 Chrome 用户提供，源试用注册现已结束。如需了解已启用每个 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。

• 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');

注意：当前页面上的功能支持并不能保证 API 一定可以使用：可能是用户已在浏览器设置中停用了 API，也可能是他们有其他设置导致 API 无法使用。为保护用户隐私，您无法以程序化方式检查其他上述设置。

通过 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 标头访问主题。

注意：在 XHR 请求中包含 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。

。

要点：CSP 指令可能会禁止执行网页中包含的第三方代码，例如广告技术脚本中的 fetch() 调用。

关于标头的一些其他说明：

• 将遵循重定向，并且在重定向请求中发送的主题是重定向网址专用的。
• 除非有相应的响应标头，否则请求标头不会修改调用方的状态。也就是说，如果没有响应标头，网页访问将不会记录为观察到，因此不会影响用户针对下一个周期的主题计算。
• 只有当相应的请求包含主题标头时，响应标头才有效。
• 请求的网址会提供被记录为调用方网域的可注册网域。

调试 API 实现

启用 Topics API 后，您便可通过桌面版 Chrome 访问 chrome://topics-internals 页面。这会显示针对当前用户的主题、根据主机名推断出的主题，以及有关 API 实现的技术信息。我们会根据开发者的反馈不断迭代和改进页面设计：请在 bugs.chromium.org 上添加您的反馈。

查看针对您的浏览器计算得出的主题

用户可以通过查看 chrome://topics-internals，查看有关其浏览器在当前周期和之前的周期中观察到的主题的信息。

<ph type="x-smartling-placeholder">

</ph>

chrome://topics-internals 页面中的“主题状态”面板会显示主题 ID、随机和真实的主题分配，以及分类和模型版本。

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

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

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

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

<ph type="x-smartling-placeholder">

</ph>

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

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

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

查看 Topics API 信息

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

注意：自 2023 年 6 月起，Topics 便开始使用经过改进的分类，其中我们添加了 280 个商业重点类别，例如“运动服装”“床垫”和“豪华旅游”，同时移除了包括“民用工程”和“马术”等主题的 160 个类别。此处的一些示例使用的是分类的版本 1。

在此示例中，time_period_per_epoch 设为 15 秒（默认为 7 天）。

<ph type="x-smartling-placeholder">

</ph>

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")

后续步骤

• 详细了解什么是主题及其工作原理。
• 试用演示版。

了解详情

• Topics API 技术说明
• 深入了解 Privacy Sandbox

互动和分享反馈

• GitHub：阅读 Topics API 说明，以及在 API 代码库中提出问题和关注相关问题的讨论。
• W3C：在 Improving Web Advertising Business Group（改进网络广告业务小组）中讨论行业用例。
• 通告：加入或查看邮寄名单。
• Privacy Sandbox 开发者支持：在 Privacy Sandbox 开发者支持代码库中提问并加入讨论。
• Chromium：提交 Chromium 错误，以询问有关目前可在 Chrome 中测试的实现的问题。