此页面由 Cloud Translation API 翻译。

Topics API 集成指南

了解如何使用 Topics API 来满足特定的广告技术应用场景。

准备工作

第一步是熟悉 Topics API 和服务。

查看开发者文档：
1. 首先阅读概览，快速了解 Topics API 及其功能。
2. 观看 Topics 演示演示（视频）。
3. 不妨观看 Topics 标头和 JavaScript API 演示。
4. 复制演示（它们都提供指向其代码的链接），并在您自己的网站上运行。
5. 如需了解更多详情，请参阅 API 说明。
查看 Topics API 的实现状态和时间轴。
了解该 API 在在无 Cookie 的未来为提升广告相关性提供支持方面发挥的作用。
若要接收有关 API 状态变更的通知，请加入开发者邮寄名单，并关注最新的 Topics 更新。
及时了解有关 Topics API 的最新资讯。
通过 GitHub 问题或 W3C 调用为讨论做出贡献。
如果您遇到不熟悉的术语，请参阅 Privacy Sandbox 术语库。
如需详细了解 Chrome 概念（例如 Chrome 标志），请访问 goo.gle/cc 观看短视频和文章。

在本地构建和测试

本部分将介绍如何以个人开发者身份试用 Topics API。

本地测试和部署（预计时间：2 天左右）
1. 使用功能标志在本地浏览器从命令行启用该 API。测试 Header 和 JavaScript API 演示，了解 Topics 的实际运用（演示视频）。
2. 运行 Topics Colab，以使用 Topics 机器学习模型测试主题推断。

在浏览器中启用 Topics

要在您自己的 Chrome 实例中启用 Topics API 以进行本地测试，您有两种选择：

打开 chrome://flags/#privacy-sandbox-ads-apis 并启用 Privacy Sandbox API。
（推荐）使用 Topics API 专用参数，根据需要进行配置，通过带有 Chromium 标志的命令行运行 Chrome。

前往 chrome://flags/#privacy-sandbox-ads-apis 启用 Privacy Sandbox API。 — 启用 Privacy Sandbox API。

通过从命令行运行 Chrome，您可以更精细地控制 Topics 功能。例如，您可以设置 Topics 周期（API 用于计算用户兴趣的时间范围），并根据需要配置该 API 的行为。

请务必注意，如果启用了 chrome://flags/#privacy-sandbox-ads-apis，此操作会替换您的命令行纪元设置，并将其恢复为默认值（当前为一周）。

预览 Topics API 机制

您可以使用 chrome://topics-internals 工具在本地了解底层 Topics API 机制。

访问 chrome://topics-internals，深入了解 Topics API。 — chrome://topics-internals tools “Topics”状态标签页。

使用 Topics API 内部构建工具，根据您访问的网站在本地测试分类器。

借助此工具，您可以查看：

Topics State：显示当前用户观察到的主题。
分类器：针对主机名推断出的预览主题。
功能和参数：查看 API 参数值，检查功能标志是否按预期运行。

了解如何使用 Internals 工具调试 Topics。

API 如何返回主题

如果 Chrome 观察到的主题数量不足，无法为某个周期（一周）创建前五个主题，Topics API 将添加随机主题来完成前五个主题。标题为真实或随机的 Topics Internals 列会指明该特定主题是基于真实的观察结果，还是基于额外的随机“填充”来完成前五名。如需详细了解此机制，请参阅说明。

系统会从用户在每个周期内最感兴趣的前五个主题中随机挑选一个主题作为该时间段的主题。如果在相应周期内观察到的主题数量不足，那么将随机选择更多主题，使总共 5 个主题。这些随机选择的主题会经过过滤。

为了进一步加强隐私保护并确保所有主题都有代表性，为一个周期选择的主题有 5% 的几率是从所有主题中随机选择的，而不是从观测到的主题中选择。正如上面情况一样，由于观察到的主题太少，这些随机选择的主题不予过滤。

如需详细了解如何选择主题，请参阅主题分类。

重要建议

请务必先关闭（和停止）所有 Chrome 进程，然后再启动新进程。
如果在本地环境中进行测试，您应停用 chrome://flags/#privacy-sandbox-ads-apis，因为它会覆盖命令行设置，并还原为默认值。
使用调试页面了解 Topics 在本地的运行情况。
如果您有任何疑问，请查看有关解释器的 GitHub 问题。
如果 API 无法正常运行，请尝试按照我们的问题排查提示进行操作。

规划 MVP 部署

通过 Topics API，您可以访问用户观察到的兴趣主题，而无需跟踪用户访问的网站或公开用户的导航历史记录。

Topics API 调用方是调用 document.browsingTopics() JavaScript 方法或者使用 HTTP 请求标头观察和访问主题的实体。在这种情况下，调用方是您的代码及从中调用该代码的 eTLD+1。调用 Topics API 即可指示用户的浏览器在用户访问网站时观察其感兴趣的主题。然后，系统会将此次访问纳入下一个周期的主题计算中。

Topics API 旨在根据调用上下文的每个调用方或每个 eTLD+1 过滤结果。换言之，系统会将 iframe 的来源（当使用 JavaScript API 时）或提取请求的网址（当使用标头时）视为调用方，并根据该调用方计算主题。

下图说明了此方法：

当用户访问使用该 API 的网站时，Topics API 会采取的步骤。 — API 如何观察和访问主题。

在此图中：

用户打开 Chrome 并访问了多个网站（customerA.example、customerB.example.br 等），这些网站包含您的广告技术平台的 iframe（来源：iframe.adtech.example）或传递标头的提取调用。
- Chrome 会记录此用户感兴趣的主题。
导航 7 天后，Topics API 会观察到感兴趣的主题，使用同一设备上的同一用户访问目标网站 (publisher-e.example)。Topics API 会返回一个主题列表，在此特定示例中，系统将返回一个根据此用户上周的观察结果计算得出的主题。
- 只有访问过 adtech.example 在第 1 步中观察到的网站的用户的浏览器才会在步骤 2 中返回主题结果（我们称之为观察过滤，您无法看到以前从未见过的用户主题）。
利用此列表（目前包含一个主题），您可以调用后端 API (ads.adtech.example/topics-backend)，将主题数据用作上下文数据集的一部分。
现在，根据您的使用情形，您可以访问您在过去几周内观察到的兴趣主题，为用户打造更加个性化的体验。

调用 Topics API

有两种方法可以为用户观察和访问主题。您可以使用

在 iframe 中使用 JavaScript API：
- 在目标网站（发布商的网站）上添加 iframe，其中包含使用 document.browsingTopics() 调用 Topics API 的 JavaScript 代码。
“标头”选项：
- Fetch（推荐）或 XHR（不推荐，仅在已完成的源试用期间可用）：
  - 您可以在向广告技术后端发送的请求中，通过 Sec-Browsing-Topics 标头访问主题。这是性能最佳的选项（观察同一特定用户的主题时延迟时间较短）。
- 使用具有 browsingtopics 属性的 iframe 代码：
  - 您可以使用 browsingtopics 属性添加 iframe，然后 Chrome 将在针对 iframe 的请求的 Sec-Browsing-Topics 标头中添加主题（针对 iframe 的 eTLD+1 观察到）。

使用 JavaScript 和 iframe 实现

我们建议您创建 Topics JavaScript API 演示或标头演示分支，然后使用其中之一作为代码的基础。

您可以在 HTML 中添加 <iframe> 元素，也可以使用 JavaScript 动态添加 iframe。动态创建 iframe 的一种方式是使用以下 JavaScript：

const iframe = document.createElement('iframe');
iframe.setAttribute('src', 'https://...');
document.body.appendChild(iframe);

请通过功能检测来检查此设备是否支持 Topics 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');

在该 iframe 中调用 Topics API：

const topics = await document.browsingTopics();

您应该会收到用户在过去三周观察到的主题列表。请注意，此列表可以为空，也可能包含 1 个、2 个或 3 个主题（最多 3 周）。

以下是该 API 返回的内容示例：

[{'configVersion': String, 
  'modelVersion': String, 
  'taxonomyVersion': String, 
  'topic': Number, 
  'version': String}]

configVersion：用于标识当前配置的字符串。
modelVersion：一个字符串，用于标识用于推断主题的机器学习分类器。
taxonomyVersion：一个字符串，用于标识浏览器当前正在使用的一组主题。
topic：用于标识分类中主题的数字。
version：将 configVersion 和 modelVersion 组合在一起的字符串。

详细了解此实现方式。

使用 HTTP 标头实现

您可以通过 fetch()/XHR 请求或 iframe 请求的 Sec-Browsing-Topics 标头访问主题。

用于设置和检索主题的请求和响应标头。 — iframe 和 `fetch()` 的标头。

您可以通过在对请求的响应上设置 Observe-Browsing-Topics: ?1 标头，将请求标头提供的主题标记为观察对象。然后，浏览器会使用这些主题计算用户感兴趣的主题。

如果该 API 返回一个或多个主题，则向用来观察主题的 eTLD+1 发出的提取请求将包含如下所示的 Sec-Browsing-Topics 标头：

(325);v=chrome.1:1:1, ();p=P000000000

如果 API 未返回任何主题，则标头将如下所示：

();p=P0000000000000000000000000000000

系统会填充 Sec-Browsing-Topics 标头值，以降低攻击者根据标头长度了解到限定为调用方的主题数量的风险。

使用 `fetch()` 实现

在发布商网页上，添加用于抓取请求的代码，确保包含 {browsingTopics: true}。

fetch('<topics_caller_eTLD+1>', {browsingTopics: true})
    .then((response) => {
        // Process the response
 })

在支持该 API 的浏览器中，fetch() 请求将包含一个 Sec-Browsing-Topics 标头，其中列出了针对请求网址主机名观察到的主题。

使用 iframe 实现

与 fetch() 请求类似，在 iframe 上使用 browsingtopics 属性时，系统会发送 Sec-Browsing-Topics 标头。

<iframe src="<topics_caller_eTLD+1>" browsingtopics></iframe>

在本例中，将是调用方，类似于提取调用。

服务器端 - 适用于所有情况

若要将 Sec-Browsing-Topics 请求标头中的主题标记为观察对象，同时还要将当前网页访问包含在用户下一个周期的热门主题计算中，服务器的响应必须包含 Observe-Browsing-Topics: ?1。

下面是一个使用 setHeader() 的 JavaScript 示例：

res.setHeader('Observe-Browsing-Topics', '?1');

Topics 后端实现

为 Topics 添加后端是可选操作。您的选择取决于您希望以何种方式以及在何处使用设备端（在浏览器中）计算的主题。

// Use the language/framework/stack of your preference
function processTopicsBackendAPI(topics, user, domain, caller) {
  // Validate inputs
  // If the list is not empty, continue
  // Use topics as an additional contextual signal
}

将主题用作情境数据

您可将主题数据与网址、关键字甚至标签等其他信号结合使用，作为有关受众群体的额外信号。

如在使用第三方 Cookie 后尽可能提高广告相关性一文中所述，您可以通过多种方法利用 Topics 投放相关广告。其中一些方法涉及使用主题构建受众群体，还有一些方法建议将 Topics 用作其中一项信号来训练机器学习模型，用于推断受众群体的其他兴趣，甚至用于优化出价逻辑。

构建和部署

通过观察生产环境中的用户来收集主题（预计时间：大约 1 周）
1. 了解您可以选择的选项：iframe 和 JavaScript 或 HTTP 标头
2. 定义 iframe 的网域。
3. 使用演示版应用作为代码参考，构建 JavaScript 代码，或实现头文件选项。
4. 将 Topics 部署到您的受控环境（某些生产网站）。
5. 将 Topics 实现添加到一些目标网站（目前不超过五个网站）。
6. 功能测试和验证。
[可选] 使用主题数据作为情境信号（使用网址、标签等）（预计时间：3 天左右）。
1. 收到主题列表后，您可以将其连同其他情境信号一起发送到后端。

部署到一些目标网站

现在，您已经有了代码，接下来我们将其添加到一些目标网站以进行首次测试，并确保 API 稳定且在此受控环境中工作。

我们建议您选择符合以下条件的目标网站：

每月访问较少（少于 100 万次访问）：您应该先向一小部分受众群体部署该 API。
您拥有并控制：如有必要，您可以快速停用实现，而无需进行复杂审批。
非业务关键型：由于这种实现方式可能会中断用户体验，因此请从低风险的目标网站入手。
网站总数不超过 5 个：您目前不需要那么多流量或曝光。
代表不同的主题：选择代表不同类别（例如，一个与体育有关，另一个与新闻有关，另一个与餐饮有关的网站）的网站。您可以使用 Chrome 中的内部主题工具来验证网域及其分类方式（Topics 机器学习分类器）。如需详细了解调试，请参阅 Topics API 开发者指南。

功能测试和验证

在此受限环境中调用 Topics API 时，您会遇到以下情况：

一个主题为 [] 的空数组，如果这是此设备在过去七天内首次调用该网站及调用方。
一个包含零到三个主题的列表，表示此用户的兴趣。
经过 7 天的观察后，您应该会收到：
- 根据当周的导航历史记录计算得出的一个主题，代表该用户的兴趣。
  - 一个重要的细节是：如果您观察到的主题不足，导致 Topics API 无法计算当周前五个主题，Topics 将根据需要添加任意数量的随机主题，以得出总数为 5 个。详细了解该 API。
一个新的主题条目将取代三个主题之一（如果您在观察四周后才调用它）。
- 这是因为 Topics API 将在接下来的几周内保持稳定，不会暴露过多的用户兴趣。访问 GitHub 了解详情。
如果您超过三周未观察到用户主题，Topics API 将再次返回一个空数组 []。

衡量用户体验的表现和指标。

您应衡量跨源 iframe 内对 Topics API 的 JavaScript 调用的运行时间，以便在将来的性能分析中使用，请务必在后端正确收集和存储遥测数据。
- 收到主题后，创建 iframe 和 postMessage() 主题所花费的时间是另一个可能要计算的指标。

问题排查

我正在调用 Topics API，但收到 null。该怎么办？: 如果您在观察到用户后的第一周调用 Topics API，这种情况属于正常现象。

重要建议

测试前端代码，确保 JavaScript 按预期运行。
测试您的后端以接收主题结果。
1. 请务必确保正确配置数据类型和后端 API 参数。
2. 确保您的后端配置为适当扩缩。
根据我们的经验，在开始获得更相关的主题结果之前，您需要至少等待三周时间。
并非所有用户都会启用 Topics：
1. 用户可以明确停用 Topics API。
2. 发布商的网页可以控制权限政策。参阅 Topics API 开发者指南中的（选择停用）。
3. 如需了解详情，请访问 chromestatus.com。
向此环境添加指标和可观测性：您需要这些指标来分析初步结果。示例指标包括：
1. 调用延迟；
2. 主题调用出现 HTTP 错误；
尽量在最初三周内尽量减少对实施的更改。

扩展到生产环境

下面逐步概述了如何扩展到生产环境。具体步骤如下所述。

扩展实现（生产环境）如下所述。
1. 将 iframe 添加到多个发布商的网站。
处理和使用主题数据（预计时间：4 周左右）。
1. 将主题数据与其他数据一起作为附加信号。
2. 寻找实时出价测试合作伙伴。
3. 使用主题作为其他数据的附加信号来运行实用性测试。

扩大实施范围

此时，您应该能够在受控环境中从某些网站收集主题数据，并对整个解决方案更有信心。

现在，是时候通过将同一代码部署到更多目标网站来扩展此实现。这样，您就可以观察更多用户，收集更多主题数据，并加深对受众群体的了解。

我们建议您执行以下操作：

在您的网站中逐步部署，尤其是在流量较大时。
根据您的预期流量，对主题数据执行负载测试。
1. 确认您的后端可以处理大量调用。
2. 设置指标收集和日志以进行分析。
部署 Topics API 后，请立即检查您的指标，以检测是否存在任何严重的最终用户问题。请定期查看您的指标。
如果发生中断或意外行为，请回滚部署并分析日志，以了解并解决问题。

互动和分享反馈

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

Topics API 集成指南

准备工作

在本地构建和测试

在浏览器中启用 Topics

预览 Topics API 机制

API 如何返回主题

重要建议

规划 MVP 部署

调用 Topics API

使用 JavaScript 和 iframe 实现

使用 HTTP 标头实现

使用 fetch() 实现

使用 iframe 实现

服务器端 - 适用于所有情况

Topics 后端实现

将主题用作情境数据

构建和部署

部署到一些目标网站

功能测试和验证

问题排查

重要建议

扩展到生产环境

扩大实施范围

互动和分享反馈

使用 `fetch()` 实现