适用于移动设备的 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 API 才会将主题标记为观察到的主题。
Topics API 仅标记在这些主题情境中存在的调用方观察到的主题。调用方只能访问他们观察到的主题。

派生主题

“主题”摘要卡会根据用户活动推断出用户感兴趣的主题。主题是从预定义的开源分类中选择的。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 个周期才能获取随广告请求一起发送的最大数量的主题（三个主题）。
  • 在广告请求中包含 Topics API 信息。针对每个广告请求，开始与买方合作伙伴共享您的 Topics API 数据。Topics API 计划对其他信号（例如情境信号）进行补充，以帮助针对特定访问者找到合适的广告。
  • 通过协作创建与您的买方合作伙伴共享主题的方案。Topics API 需要每个 SDK 与下游合作伙伴就如何共享 Topics API 数据达成一致。

适用于买方广告技术平台

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

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
答 T1、T5 ad-sdk1、ad-sdk2
亿 T2 ad-sdk2
C T3、T6 ad-sdk3、ad-sdk4
D T1、T4 ad-sdk1
东 T5 ad-sdk4、ad-sdk5
周五 T6 ad-sdk2、ad-sdk3、ad-sdk4
G T7 ad-sdk2

第一周结束：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

第二周，如果任何应用中的某个调用方调用该 API，返回的主题列表将仅包含该调用方位于“可获知该主题的调用方”中的主题。该主题对应的列。

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

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

返回的主题的加密

调用 Topics API 的已注册广告技术平台也必须提供 加密密钥，以确保返回的主题仅对 调用方。

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

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

Next steps

Check out implementation details and code samples for callers to observe and access topics.
Learn how users and developers can manage and customize the Topics API to suit user's preferences and needs.

See also

Check out our resources to better understand the Topics API on Android.