文档：browsingTopics() 方法

实验性： 这是一个实验性技术

在生产环境中使用此功能前，请仔细查看浏览器兼容性表格。

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

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

注意：您的应用程序需要进行注册流程才能使用此功能。

Document 接口的 browsingTopics() 方法返回一个 Promise，该 Promise 会解析为一个对象数组，表示用户的热门主题，每个主题来自过去三个时段中的一个。然后，这些主题可以在后续的 fetch 请求中返回到广告技术平台。默认情况下，此方法还会导致浏览器记录调用方观察到的当前页面访问，以便稍后在主题计算中使用页面的主机名。

有关更多详细信息，请参阅使用主题 API。

注意：browsingTopics() 不依赖于 HTTP 标头来发送主题并将主题标记为已观察，如其他启用主题 API 的功能，但它的性能略差。建议您使用其中一个使用 HTTP 标头的功能，仅在无法修改标头的情况下回退到 browsingTopics()。

语法

browsingTopics()
browsingTopics(options)

参数

options 可选

一个选项对象，可以包含以下属性

skipObservation: 一个布尔值，如果设置为 true，则会导致浏览器在调用 browsingTopics() 时不观察主题。默认为 false，这会导致观察主题。

返回值

一个Promise，它会解析为最多包含三个对象的数组，这些对象表示当前用户在过去三个时段中选择的主题。每个对象包含以下属性

configVersion: 一个字符串，用于标识用于计算主题的算法（模型部分除外）。
modelVersion: 一个字符串，表示用于将字符串（例如网页的主机名）分类为主题 ID 的模型。
taxonomyVersion: 一个字符串，表示使用的分类版本。
topic: 一个数字，表示主题的 ID，浏览器可以使用它从分类中检索主题（请参阅示例兴趣分类）。
version: configVersion、modelVersion 和 taxonomyVersion，每个之间用冒号 (:) 连接。

确切的属性值可能因浏览器实现而异。来自 Chrome 的示例对象可能如下所示

{
  configVersion: "chrome.1",
  modelVersion: "1",
  taxonomyVersion: "1",
  topic: 43,
  version: "chrome.1:1:1"
}

异常

NotAllowedError DOMException

如果以下情况发生，则抛出

主题 API 的使用被browsing-topics权限策略禁止。
调用站点在成功的隐私沙箱注册流程中未包含主题 API。

示例

// Get an array of top topics for this user
const topics = await document.browsingTopics();

// Request an ad creative
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

主题 API

文档：browsingTopics() 方法

语法

参数

返回值

异常

示例

规范

浏览器兼容性

另请参阅