使用主题 API

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

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

此页面解释了主题 API 的工作原理及其如何用于创建基于兴趣的广告 (IBA) 解决方案。

高级概述

假设我们有一个广告技术平台 ad-tech1.example，它通过 <iframe> 将广告嵌入到以下发布商网站

  • yoga.example
  • knitting.example
  • football.example

如果 ad-tech1.example 的 <iframe> 内容实现了支持主题 API 的功能，则加载每个网站时，浏览器将

  1. 从网站 URL 推断出兴趣主题。这些主题来自标准分类法；对于上述 URL 示例，主题将分别是“健身”、“纤维和纺织艺术”以及“足球”。
  2. 将主题标记为已观察，这涉及在私有主题历史记录存储中为每个主题记录一个主题历史记录条目。每个主题历史记录条目包括以下信息
    • 文档 ID（即当前页面的标识符）。
    • 主题计算输入数据（即页面主机名）。
    • 首次观察到页面时的时间（自 Unix 纪元起）。
    • 观察到主题的域（称为主题调用者域）。

选择兴趣主题以影响广告选择

注意： 不同的浏览器实现可能以不同的方式选择主题。以下文本基于 Chrome 目前选择主题的方式，仅供演示之用。

浏览器将持续

  1. 跟踪用户在每个新的纪元期间观察到每个主题的频率。默认情况下，纪元为一周，但可以为测试目的更改长度（请参阅 测试提示）。Chrome 将分类法中的 22 个根主题（没有祖先的主题）中的每一个都放入两个桶之一，表示对整个广告技术生态系统的较高或标准效用。根主题的所有后代都从其父主题继承相同的桶分配。根主题到桶的分配基于 Google 从生态系统中的公司收到的关于效用的输入。
  2. 在每个纪元结束时，为每个用户选择顶级主题
    1. Chrome 将用户浏览历史记录中的调用者域主机名转换为主题。
    2. 这些主题首先按桶排序，然后按频率（在主机名中匹配的次数）排序。也就是说，如果两个主题在同一个桶中但频率不同，则频率更高的主题排序更高。
    3. Chrome 选择前五个主题作为用户在该纪元内的顶级主题，这些主题有资格与调用者共享。
  3. 只有当 ad-tech1.example 出现在每个主题的调用者域列表中（如主题历史记录条目中存储的那样）时，顶级主题才会返回给 ad-tech1.example。

    注意： 最初，不会返回任何主题，因此 <iframe> 可能会显示默认的非定向广告。但是，一旦第一个纪元结束，API 将开始返回主题，ad-tech1.example 可以开始根据当前用户的观察主题显示更相关的广告。

然后，ad-tech1.example 根据返回的主题选择要向用户提供的相关广告。

哪些 API 功能支持主题 API？

以下所有功能都具有双重用途 - 它们将用户的顶级主题返回给调用者，并且会触发浏览器将当前页面访问记录为调用者观察到，以便稍后在主题计算中使用页面的主机名。为此，它们需要包含在调用广告技术的 <iframe> 中；然后，<iframe> 必须嵌入到您希望观察主题的页面上。

  • 您可以在 fetch() 调用到广告技术平台的选项对象的选项对象中指定 browsingTopics: true。
  • 您还可以将 browsingTopics: true 传递到 Request() 构造函数调用的选项对象中，并将生成的 Request 对象传递到 fetch() 调用中。
  • 您可以在 <iframe> 上设置 browsingtopics 属性，在设置或之前设置 src 属性以加载源。这可以通过以下方式完成
    • 在 HTML 上声明性地
    html
    <iframe browsingtopics src="ad-tech1.example"> ... </iframe>
    js
    const iframeElem = document.querySelector("iframe");
iframeElem.browsingTopics = true;

当与上述功能之一相关联的请求被发送时

  1. Sec-Browsing-Topics 标头将与请求一起发送，该标头包含当前用户的顶级主题（s）。
  2. 广告技术服务器根据这些主题选择要显示在 <iframe> 中的相关广告，并在响应中发送显示该广告所需的数据。
  3. 应该在对请求的响应中设置 Observe-Browsing-Topics 标头 - 这将使浏览器将当前页面访问记录为调用广告技术提供商观察到的，因此相关主题（s）将被记录在主题历史记录条目中，并在随后用于主题选择。

    注意： 重要的是要澄清，这不会将发送到 Sec-Browsing-Topics 标头的顶级主题记录为已观察到。它会将从调用网站的 URL 推断出的主题记录为已观察到（即广告技术 <iframe> 嵌入的网站）。

browsingTopics() 方法

或者，嵌入的 <iframe> 可以调用 Document.browsingTopics() 以返回用户的当前顶级主题（s），然后可以在随后的获取请求中将其返回到广告技术平台。这并不依赖于 HTTP 标头，但性能略低。建议您使用上面列出的 HTTP 标头方法之一，只有在无法修改标头的情况下才回退到 browsingTopics()。

注意： 因为 browsingTopics() 方法不依赖于 HTTP 标头，所以 Observe-Browsing-Topics 标头不用于将主题设置为已观察到并记录/更新主题历史记录条目；浏览器在调用该方法时会自动执行此操作。

私有主题集

调用者只能访问他们自己为用户观察到的主题 - 而不是其他调用者观察到的主题。例如

  • 如果 ad-tech1.example 平台在 tennis.example 上嵌入一个 <iframe>，其中包含主题 API 功能，他们将观察到访问该网站的用户的一些主题，例如“体育”和“网球”。
  • 如果另一个广告技术平台 ad-tech2.example 在“gardening.example”上嵌入一个主题 API <iframe>，他们将观察到主题“园艺”。

这些广告技术平台只会获得他们观察到的用户的主题。在这个例子中，ad-tech1.example 不会获得“园艺”，ad-tech2.example 不会获得“网球”。

换句话说，广告技术平台之类的调用者只会获得他们存在于其中的页面的主题。更重要的是，记录的兴趣主题是唯一可以通过此 API 访问的信息 - 与跟踪 Cookie 不同，不会泄露其他任何信息。

示例

使用 Document.browsingTopics()

js
// Get an array of 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

将 browsingTopics 选项传递到 fetch() 中

js
// Request an ad creative
const response = await fetch("https://ads.example/get-creative", {
  browsingTopics: true,
});

// Get the JSON from the response
const creative = await response.json();

// Display ad

在 <iframe> 中包含 browsingtopics 属性

html
<iframe browsingtopics src="ad-tech1.example"> ... </iframe>

完整示例

测试提示

Chrome

观察主题的默认纪元长度为一周，这对于测试使用主题 API 的代码来说太长了。为了缩短测试目的，在 Chrome 中，您可以使用以下类似的命令行标志打开浏览器

bash
BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s

有关如何执行此操作的更多信息，请参阅 使用命令行开关运行 Chromium。

您还可以通过启用以下 Chrome 开发者标志在本地测试您的主题 API 代码，而无需注册

chrome://flags/#privacy-sandbox-enrollment-overrides

另请参见