使用 Topics API

高层概览

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

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

如果 ad-tech1.example 中的 <iframe> 内容实现了支持 Topics API 的功能，那么当每个网站加载时，浏览器将：

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

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

浏览器将持续地：

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 功能支持 Topics API？

以下功能均具有双重目的——它们将用户最受欢迎的主题返回给调用方，并触发浏览器将当前页面访问记录为调用方已观察到的，以便以后可以使用该页面的主机名进行主题计算。为此，它们需要包含在调用广告技术的 <iframe> 中；然后，该 <iframe> 必须嵌入到您希望观察主题的页面上。

• 您可以在对广告技术平台的 fetch() 调用中的选项对象中指定 browsingTopics: true 选项。

• 您也可以将 browsingTopics: true 传递给 Request() 构造函数调用的选项对象中，然后将生成的 Request 对象传递给 fetch() 调用。

• 您可以在 <iframe> 上设置 browsingtopics 属性，同时或在设置 src 属性以加载源之前。这可以这样完成：

  • 在 HTML 中声明式设置
  html

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

  • 通过将等效的 HTMLIFrameElement.browsingTopics 属性设置为 true 来以编程方式设置
  js

  const iframeElem = document.querySelector("iframe");
  iframeElem.browsingTopics = true;
  

发送与上述功能之一相关的请求时：

1. 将发送一个 Sec-Browsing-Topics 头信息，其中包含当前用户最受欢迎的主题。

2. 广告技术服务器根据这些主题选择一个相关的广告来显示在 <iframe> 中，并将显示它所需的响应数据发送回来。

3. 应在对请求的响应中设置一个 Observe-Browsing-Topics 头信息 — 这会使浏览器将当前页面访问记录为调用广告技术提供商已观察到的，因此相关主题将被记录在主题历史记录条目中，并随后用于主题选择。

   注意： 重要的是要澄清，这并不会记录在 Sec-Browsing-Topics 头信息中发送的最受欢迎的主题作为已观察到的。它记录的是从调用方网站的 URL（即嵌入广告技术 <iframe> 的网站）推断出的已观察到的主题。

browsingTopics() 方法

或者，嵌入的 <iframe> 可以调用 Document.browsingTopics() 来返回用户当前最受欢迎的主题，然后可以在后续的 fetch 请求中将其返回给广告技术平台。这不依赖于 HTTP 头信息，但性能稍差。建议您使用上面列出的 HTTP 头信息方法之一，仅在无法修改头信息的情况下回退到 browsingTopics()。

私有主题集

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

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

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

换句话说，诸如广告技术平台之类的调用方只能获得他们在某个页面上有存在的主题。更重要的是，记录的兴趣主题是该 API 可访问的唯一信息 — 与跟踪 cookie 不同，无法泄露任何其他信息。

示例

使用 Document.browsingTopics()

// 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()

// 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 属性

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

测试提示

Chrome

观察主题的默认时期长度为一周，这对于测试使用 Topics API 的代码来说太长了。为了在测试目的下缩短这个时间，在 Chrome 中，您可以通过如下方式使用功能标志打开浏览器：

BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s

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

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

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

另见

• Topics API on privacysandbox.google.com (2023)