主题 API

实验性： 这是一个实验性技术
在生产环境中使用此功能之前，请仔细查看浏览器兼容性表。

非标准： 此功能是非标准的，并且不在标准轨道上。请勿在面向 Web 的生产网站上使用它：它不会对每个用户都起作用。实现之间也可能存在很大的不兼容性，并且行为将来可能会发生变化。

警告： 此功能目前遭到两家浏览器供应商的反对。有关反对意见的详细信息，请参阅下面的标准立场部分。

注意： 在您的应用程序中使用主题 API 需要进行注册流程。有关注册受哪些子功能限制的详细信息，请参阅注册部分。

主题 API 为开发人员提供了一种机制，可以根据浏览器在用户浏览不同页面时收集的主题来实现诸如基于兴趣的广告 (IBA) 等用例，而不是通过使用第三方 Cookie 跟踪用户在不同网站上的浏览路径来由开发人员收集。

概念和用法

Web 上的广告投放机制通常包括用户访问发布商网站，这些网站使用广告技术 (ad tech) 平台发布广告主产品或服务的广告。发布商因展示广告而获得报酬，这有助于为其内容提供资金，并且可以为广告主网站带来更多业务。

使用基于兴趣的广告 (IBA) 可以使上述流程更加有效。其理念是，当用户访问发布商网站时，他们会根据自己的兴趣获得个性化的广告选择。他们的兴趣是从他们之前访问过的网站推断出来的。过去，第三方 Cookie 用于收集用户兴趣信息，但所有浏览器都正在逐步淘汰第三方 Cookie 的使用。主题 API 为实现这一目标提供了一部分途径——一种不依赖于第三方 Cookie 来实现 IBA 的机制。

首先，浏览器会根据用户访问的包含嵌入式广告技术<iframe>的网站的 URL 推断用户的兴趣。这些兴趣会映射到特定的兴趣主题，并且浏览器会在每个时期结束时计算并记录用户的首要主题（即其兴趣最常映射到的主题）。时期默认为一周。首要主题每周更新一次，以便兴趣保持最新，并且用户不会开始看到他们不再感兴趣的主题的广告。

注意： 此过程仅在使用主题 API 功能的网站上发生（请参阅哪些 API 功能启用了主题 API？）。

一旦浏览器观察到用户的一个或多个主题，主题 API 就可以检索这些主题并将它们发送到广告技术平台。然后，平台可以使用这些主题来个性化他们向用户投放的广告。API 通过仅将已由他们在当前用户访问的页面上观察到的主题返回给 API 调用者来帮助保护隐私。

有关 API 工作原理的说明，请参阅使用主题 API。

Document.browsingTopics(): 返回一个 Promise，该 Promise 会完成并包含一个对象数组，表示用户的首要主题，每个主题来自过去三个时期中的一个。默认情况下，此方法还会导致浏览器将当前页面访问记录为调用者观察到的访问，以便稍后在主题计算中使用页面的主机名。
fetch() / Request()，browsingTopics 选项: 一个布尔值，指定是否应在与关联请求一起发送的 Sec-Browsing-Topics 标头中发送当前用户的选定主题。
HTMLIFrameElement.browsingTopics: 一个布尔值属性，指定是否应将当前用户的选定主题与关联 <iframe> 的源的请求一起发送。这反映了browsingtopics 内容属性值。

HTML 元素

<iframe>，browsingtopics 属性: 一个布尔值属性，如果存在，则指定是否应将当前用户的选定主题与 <iframe> 的源的请求一起发送。

HTTP 标头

Sec-Browsing-Topics: 将当前用户的选定主题与请求一起发送，广告技术平台使用这些主题来选择要显示的个性化广告。
Observe-Browsing-Topics: 用于将从调用站点 URL（即嵌入广告技术<iframe>的站点）推断出的兴趣主题标记为在对由启用主题 API 的功能生成的请求的响应中观察到。浏览器随后将使用这些主题来计算未来时期的当前用户的首要主题。
Permissions-Policy；browsing-topics 指令: 控制对主题 API 的访问。在策略明确禁止使用主题 API 的情况下，任何尝试调用Document.browsingTopics()方法或使用Sec-Browsing-Topics标头发送请求的操作都将失败，并出现NotAllowedError DOMException。

注册

要在您的网站中使用主题 API，您必须在隐私沙箱注册流程中指定它。如果您不这样做，以下子功能将无法使用

Document.browsingTopics() 方法返回的 Promise 将拒绝并出现NotAllowedError DOMException。
创建或修改 Sec-Browsing-Topics 标头将静默失败，并且任何现有的Sec-Browsing-Topics标头都将被删除。