此页面由 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。
（推荐）使用 Chromium 标志使用 Topics API 专用参数从命令行运行 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 机制。

如需查看 Topics API，请访问 chrome://topics-internals。 — chrome://topics-internals 工具“主题状态”标签页。

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

通过此工具，您可以查看：

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

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

API 如何返回主题

如果 Chrome 因观察到的主题数量不足而无法创建周期（一周）内排名前五位的主题，那么 Topics API 会添加随机主题，以统计前五位。标题为 Real 或 Random 的 Topics 内部数据列指明了该特定主题是基于真实观察结果还是基于额外的随机“填充”来填充前 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 时）或提取请求的网址（使用标头时）视为调用方，并根据该调用方计算主题。

下图说明了此方法：

Topics API 在用户访问使用该 API 的网站时执行的步骤。 — API 如何观察和访问主题。

在此图中：

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

调用 Topics API

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

在 iframe 中使用 JavaScript API：
- 在包含使用 document.browsingTopics() 调用 Topics API 的 JavaScript 代码的目标网站（发布商网站）上添加 iframe。
标头选项：
- 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 以及该 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();

您应该会收到过去三周内针对此用户观察到的主题的列表。请注意，此列表可以为空，也可以包含最多过去 3 周的 1、2 或 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 实现添加到部分目标网站（目前不超过 5 个）。
6. 功能测试和验证。
[可选] 使用 Topics 数据作为情境信号（通过网址、标记等）（预计用时：3 天左右）。
1. 收到主题列表后，您可以结合其他上下文信号将其发送到后端。

部署到某些目标网站

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

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

获得少量的每月访问次数（少于每月约 100 万次访问）：您应先为少量受众群体部署 API。
您拥有和控制：如有必要，您可以快速停用相应实施，而无需进行复杂的审批。
对业务不重要：由于这种植入方式可能会干扰用户体验，请从风险较低的目标网站入手。
总计不超过五个网站：您目前不需要那么多的流量或曝光率。
呈现不同的主题：选择网站时，应体现不同类别（例如，体育类网站、新闻类网站，餐饮类网站等）。您可以使用 Chrome 中的内部主题工具来验证网域以及 Topics 机器学习分类器对这些网域的分类方式。如需详细了解调试，请参阅 Topics API 开发者指南。

功能测试和验证

在这种有限的环境中调用 Topics API 时，可能会发生以下情况：

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

衡量用户体验的效果和指标。

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

问题排查

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

重要建议

测试您的前端代码，确保您的 JavaScript 能按预期运行。
测试您的后端以接收主题结果。
1. 请务必确保正确配置数据类型和后端 API 参数。
2. 确保您的后端配置为适当扩缩。
根据我们的经验，在开始获得相关程度更高的主题结果前，至少需要等待 3 周。
并非所有用户都会启用 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()` 实现