适用于移动设备的 Topics API：概览

了解 Android 上的 Topics API 以及实现该 API 的步骤。您也可以直接实现主题。

Topics API 的运作方式

Topics API 可用于根据用户的活动，观察和提供对用户可能感兴趣的主题的访问权限。然后，Topics API 可以向 API 调用方（例如广告技术平台）授予对用户感兴趣的主题的访问权限，但不会泄露有关用户活动的其他信息。

主要概念

• “主题”是指简单易懂的当前用户兴趣主题，是“主题”分类的一部分。
• 调用方是指向 Topics API 发出请求以观察或访问用户兴趣的实体，例如应用、第三方 SDK、网站或服务。
• 如果某个调用方在过去 3 个周期内通过与某个主题相关联的网页或应用发出了 Topics API 请求，此调用方就会观察该主题。
• “周期”是指主题计算期限，默认为一周。
• 分类法是类别的层次结构列表，例如，其中包含 /Arts & Entertainment/Music & Audio/Soul & R&B 和 /Business & Industrial/Business Services/Corporate Events 等类别。
• 系统使用分类器模型派生主题，该模型会将用户活动映射到零个或多个主题。

Topics API 流程核心步骤

Topics API 生命周期包含三个主要步骤：

• 观察用户活动，例如用户访问网页 https://cats.example/tabby/index.html 或下载应用 cats 的情况。
• 从用户活动中派生主题，例如 /Pets & Animals/Pets/Cats。
• 访问之前为用户观察到的主题，例如作为选择相关广告（例如猫粮促销广告）的信号。

观察主题

调用方只能访问他们观察到的感兴趣的主题。当调用方从与某个主题相关联的情境中发出 Topics API 请求时，就会观察该主题。为了说明这一概念，请参考以下简化示例。

• 假设有两个 Topics API 调用方：A 和 B。
• 有两个上下文：
  • Greenhouse，例如与主题 Home & Garden 相关联的名为 Greenhouse 的应用或网站 greenhouse.example。
  • 网球练习，例如与主题 Sports/Tennis 相关联的名为“网球练习”的应用或网站 tennis.example。
• 调用方 A 和 B 都存在于 Greenhouse 上下文中。
• 网球练习上下文中只有调用方 B。
• 为简单起见，假设在第 1 个时段之前，系统未观察到该用户感兴趣的任何主题。
• 用户访问 Greenhouse 应用，调用方 A 和 B 会调用 Topics API 来记录用户对相应网页或应用的访问（如需了解如何调用 Topics API，请参阅后续步骤中建议的实现指南）。此记录（主机名或应用数据）稍后将用于派生感兴趣的主题。Topics API 稍后会将主题 Home & Garden 标记为同时被调用方 A 和 B 观察到。
• 用户访问 Tennis exercises 应用。只有调用方 B 会发送 Topics API 请求。Topics API 稍后会将主题 Sports/Tennis 标记为调用方 B 观察到的主题。
• 在周期结束时，Topics API 会刷新用户的热门主题，并根据用户活动确定观察到这些主题的调用方。
• 稍后，当调用方 B 再次调用 Topics API 时，它可以在响应数组中为此用户获取 Home & Garden 或 Sports/Tennis 主题（或 5% 的概率获取随机主题）。
• 调用方 A 只能访问主题 Home & Garden，因为它从未观察到主题 Sports/Tennis。这意味着，第三方只能在用户感兴趣的特定情境（应用或网站）中了解用户的兴趣主题。

派生主题

“主题”摘要卡会根据用户活动推断出用户感兴趣的主题。主题是从预定义的开源分类中选择的。Topics 会在每个周期内刷新一次用户的五大热门主题，以及在该周期内观察到这些主题的调用方。Topics 分类器模型会根据用户活动派生主题：网页访问的主机名、Android 设备上的应用信息。

调用方访问用户感兴趣的主题

该 API 仅会返回调用方在最近三个周期内观察到的主题。最多可向调用方返回三个主题，每个最近三个周期（如果调用方观察到该周期的主题）对应一个主题。调用方可以使用返回的主题来补充任何情境信息，也可组合使用这些主题来帮助为用户找到更相关的广告。

周期数

Topics API 必须确保它提供的感兴趣主题始终是最新的。系统会根据用户在某个时间段（称为“周期”，默认为一周）内的活动来推断他们感兴趣的主题。每个用户都有自己的时段（时段是“按用户”），初始开始时间是随机的。

Topics API 会在每个周期计算一次用户的 5 个热门主题，并确定哪些调用方使用设备端信息观察到这些主题。系统会从用户在每个周期内最感兴趣的前五个主题中随机挑选一个主题作为该时间段的主题。为了进一步加强隐私保护并确保所有主题都有代表性，从兴趣分类所有可能的主题中随机选择一个主题的概率为 5%。

Android 主题的实际应用

Topics API on Android 旨在支持通常在多个应用中运行的第三方广告 SDK。Topics 会根据用户的应用使用情况，为调用方提供粗略的兴趣主题以用于投放广告，而无需依赖跨应用标识符。这些主题可用于补充与想要展示广告的应用相关的任何情境信息，也可组合在一起以帮助为用户选择合适的广告。

在 Topics API 中，买方和广告客户依赖于卖方。 卖方在发布商的应用中广泛展示广告，并观察用户的兴趣主题，然后与买方分享这些主题，以帮助他们选择更相关的广告。若要获取主题，卖方应用和 SDK 必须至少在一个周期内成为 Topics API 的观察者，从而建立足迹。

请参阅 Topics API 实现指南中的相关代码示例，了解如何为“针对用户兴趣投放广告”设置主题提取功能。

按业务类型的主题集成

使用 Topics API 启用IBA（针对用户兴趣投放广告）。根据您的广告技术业务类型，按照相应步骤集成 Topics API，为发布做好准备。

适用于所有广告技术平台

• 查看主题分类并提供反馈。
• 尝试使用 Topics API 示例应用，查看设备端分类器会返回哪些主题数据。
• 更新应用和 SDK 流程以开始调用 Topics API。
• 更新方案以开始在广告请求中发送主题。
• 在 Privacy Sandbox 中注册您的广告技术平台。

适用于卖方广告技术平台

• 成为观察者，建立 Topics API 足迹。Topics API 提供了一个新信号，因此您需要更新 SDK 才能开始调用 Topics API。为了以一致的方式检索主题，您的 SDK 必须每个周期至少从发布商应用调用一次该 API。系统最多要用 4 个周期来获取随广告请求一同发送的最大数量的主题（3 个主题）。
• 在广告请求中包含 Topics API 信息。针对每个广告请求，开始与买方合作伙伴共享您的 Topics API 数据。Topics API 计划对其他信号（例如情境信号）进行补充，以帮助为指定访问者找到合适的广告。
• 通过协作创建与您的买方合作伙伴共享主题的方案。Topics API 要求每个 SDK 与下游合作伙伴就如何共享 Topics API 数据达成一致。

适用于买方广告技术平台

• 与卖方合作伙伴联系，确认他们观察主题并建立足迹的计划。若要接收主题，卖方提供者必须在每个周期至少调用一次 Topics API。
• 通过协作创建从卖方合作伙伴接收主题的方案。主题是一个新的信号，卖方合作伙伴将在广告请求中共享该信号。买方消费者需要确保与上游合作伙伴就如何分享主题开展合作。
• 将主题整合到出价和优化模型中。Topics API 应对内容相关等其他信号进行补充，以便帮助为访问者找到合适的广告。

Topics API 如何为应用推断主题

在 Android 上，Topics API 会使用分类器模型根据应用信息推断应用的主题。在当前实现中，Topics 使用应用和软件包名称为应用分配兴趣主题，但日后可能会扩展为包含应用说明等其他信息。

主题分类器

兴趣主题衍生自基于公开的应用信息进行训练的分类器模型。

• 在使用分类器模型进行推理以计算给定周期的主题时，所用的那组信号会保留在设备上。这组信号可能包含已安装的应用或最近使用过的应用，之后还可能会进行扩展，以包含其他信号。
• V5 模型由 Google 使用来自 Google Play 商店等应用商店的 54 万条人工标记的公开应用信息和 1700 万条机器学习标记的公开应用信息进行训练。该模型使用应用名称和软件包名称作为输入信号，可供应用开发者免费使用，以便测试其应用会归类为哪些主题。
• 应用可能会映射到多个主题，可能未映射到任何主题，也可能未向用户的主题历史记录添加任何内容。如果某个应用映射到分类中的多个主题，为此应用选择的主题数量将按上限限定为 3 个。

如需更好地了解分类器模型的工作原理，您可以使用 Android Topics 分类器 Colab 测试不同应用数据对分类的影响

分类

主题是从预定义的开源分类中选择的。分类是公开的，可能会发生变化。您可以使用此页面顶部的反馈按钮提交建议。此分类由人工挑选，以确保其中不含敏感主题。我们会根据可在 Android 移动应用中展示的广告类别调整此分类。

Android 主题的实际应用

假设用户在设备上安装了 7 个应用：A、B、C、D、E、F 和 G。假设应用的主题分类以及这些应用中的广告技术 SDK 如下所示：

应用	主题分类	广告技术 SDK
A	T1、T5	ad-sdk1、ad-sdk2
B	T2	ad-sdk2
C	T3、T6	ad-sdk3、ad-sdk4
D	T1、T4	ad-sdk1
E	T5	ad-sdk4、ad-sdk5
F	T6	ad-sdk2、ad-sdk3、ad-sdk4
G	T7	ad-sdk2

第 1 周结束时：Topics API 会针对此周期生成用户的 5 个首要主题。

首要主题	可获悉此主题的调用方
T1	ad-sdk1、ad-sdk2
T2	ad-sdk2
T3	ad-sdk3、ad-sdk4
T4	ad-sdk1
T5	ad-sdk1、ad-sdk2、ad-sdk4、ad-sdk5

在第 2 周，如果任何应用中的某个调用方调用此 API，返回的主题列表将仅包含符合以下条件的主题：该调用方包含在主题在相应周期内针对相关应用的“可获取此主题的调用方”列中。

• 计算每个调用方可用的主题时用到的历史期限为 3 个周期（或 3 周）。
• 仅使用与通过广告 SDK 调用 Topics API 的应用相关联的主题。这意味着，如果某个应用不包含任何调用 Topics API 的广告 SDK，与该应用相关联的主题便不会纳入广告 SDK 可访问的主题池。
• 应用还可以明确停用 Topics API。每周主题的计算不会考虑与选择停用的应用相关联的主题。本文档的内容会进行更新，以包含相关实现详情。

如果应用使用情况数据不足，导致平台无法推断出 5 个主题，平台可能会考虑随机生成剩余主题等选项。

返回的主题的加密

调用 Topics API 的已注册广告技术平台还必须提供加密密钥，以确保只有调用方可以读取返回的主题。

Privacy Sandbox 将从广告技术平台提供的端点提取这些密钥。我们建议的最佳实践是，密钥应定期更新，但间隔时间不长于每 6 个月一次。

在注册过程中，Privacy Sandbox 会要求广告技术平台确认其提供的端点是否可用。如需详细了解当前注册的和新注册的广告技术平台要求采取的操作，请参阅注册指南

后续步骤

另请参阅

查看我们的资源，更好地了解 Android 上的 Topics API。

• 查看 Topics 示例应用、协作和演示视频。
• 了解用户和开发者如何控制该 API。
• 查看支持资源，提问、互动和分享反馈。