此页面由 Cloud Translation API 翻译。

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

提供反馈

关于 Topics API

在移动广告领域，广告客户自然希望投放与用户兴趣相关的广告。例如，如果用户对与烹饪相关的信息感兴趣，他们可能会发现与烹饪相关的广告比与自己兴趣无关的广告更贴合自己的需求。

内容相关广告完全以用户来自于当前用户正在观看（以及广告）的内容。使用 Topics API 的特点在于，它允许应用对用户有用但也许很难通过内容相关广告创收，从而为用户提供更多收入。

Topics API 可根据用户的应用使用情况来粗略推断设备上的兴趣信号。这些信号（即主题）将与广告主共享支持连续信号和其他第一方信号，而无需跟踪各个用户的访问行为

Topics API 旨在支持通常跨多个应用运行。这项支持包括这些 SDK 通常会显示一些跨应用兴趣，观察。个别应用开发者不应期望了解用户的相关信息

主要概念

“主题”是指简单易懂的用户兴趣主题，是“主题”分类的一部分。
如果某个调用方（应用或应用中使用的第三方 SDK）在过去 3 个周期内向与某个主题相关联的应用发出了 Topics API 请求，此调用方就会观测到该主题。
“周期”是指主题计算期限，例如一周。

运作方式

在此提案中，Topics API 会根据用户的应用使用情况，为调用方提供粗略的兴趣主题以用于投放广告。这些主题可用于补充与想要展示广告的应用相关的任何情境信息，也可组合在一起以帮助为用户找到合适的广告。

请参阅 Topics API 开发者指南中的相关代码示例，了解如何为“针对用户兴趣投放广告”设置主题提取功能。注：API 还不是最终版本。

主题是从预定义的开源分类中选择的。

平台使用分类器模型来推断主题。Topics API 实现及其对分类器的使用将包含在 Android 开源项目中，并将随着时间的推移而不断改进。

为便于说明，以下代码示例演示了如何使用主题来提取针对用户兴趣的广告。此处使用的 API 并非最终版本。

// Initialize the Topics API.
…
topicsFuture = AdvertisingTopicsClient.getTopics();

// Retrieve Topics and use them in Ad request.
Futures.addCallback(
    topicsFuture,
    new FutureCallback<AdvertisingTopicsInfo>() {
        @Override
        public void onSuccess(@Nullable AdvertisingTopicsInfo topicsInfo) {
            // Sanitize Topics result.
            ...
            // Initialize ad request with Topics obtained.
            AdRequest adRequest = AdRequest.initialize(topicsInfo);
        }

        @Override
        public void onFailure(Throwable t) {
            // Handle error.
            ...
        }
});

如需更好地了解分类器模型的工作原理，您可以通过 Android Topics 分类器 Colab 测试不同应用数据在系统中是如何响应的。

获取对 Topics API 的访问权限

广告技术平台需要注册才能访问 Topics API。如需了解详情，请参阅注册 Privacy Sandbox 账号。

具体说明

系统会使用设备端信息来计算用户的 5 个首要主题，这种计算每个周期进行一次（例如，每周一次）。
- 调用 Topics API 后，平台会检查是否已为调用此 API 的应用分配主题。如果未分配任何主题，系统会按以下方式选择一个主题，并将所选主题分配给该应用，且有效期为相应周期的剩余时间。
  - 系统从为此周期计算的 5 个首要主题的列表中随机选择一个主题的概率为 95%。
  - 系统从分类中随机选择一个主题的概率为 5%。
  - 调用方可以使用 shouldRecordObservation = false 参数调用 getTopics，以指定希望检索主题而不修改状态。这意味着可以返回主题，但该调用不会包含在每周一次的周期计算中，也不会为调用方更新观测到的主题列表。
- 之所以让每个应用分别获取多个主题中的一个，是为了确保不同的应用能够获得不同的主题，从而让应用更难对同一用户进行互相关分析。
  - 例如，应用 A 可能会观测到用户的主题为 T1，但应用 B 可能会观测到主题 T2。这样一来，这两个应用就更加难以确定这些信息是与同一用户相关联的了。
Topics API 会返回一个最多包含 3 个主题的列表，过去 3 个周期在此列表中分别有 1 个主题。
- 通过提供最多 3 个主题，不常用的应用将有足够的主题来找到相关的广告，但常用的应用每周最多可以获悉 1 个新主题。
- 返回的主题信息包含与分类中的条目相对应的主题 ID (int)、分类版本和分类器模型版本。
- 只有在过去 3 个周期内观察到用户使用了与主题相关联的应用的调用方才能接收此主题。
- 返回的所有主题都表示用户的兴趣，您可以选择其中任何或所有主题，以用于在广告请求中进行广告个性化。

将某个主题分配给调用 Topics API 的应用后，平台会确定调用方是否可以接收此主题。

只有在过去 3 个周期内观察到用户与主题的关联应用进行了互动的调用方才能接收此主题。
如果调用方过去未在与此主题有关的应用中针对相应用户调用该 API，此主题就不会包含在该 API 返回的列表中。
如果调用方在过去 3 个周期内未收到任何主题，Topics API 将返回空列表。

例如，假设用户在设备上安装了 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 周）。
仅限与通过广告调用 Topics API 的应用相关联的主题使用 SDK。这意味着，如果应用不含任何广告 SDK 调用 Topics API 时，与该应用关联的主题不会为广告 SDK 可访问的主题库做出贡献。
应用还可以通过新的清单和 XML 元素明确停用 Topics API，以禁止广告 SDK 针对该应用使用此 API。每周主题的计算不会考虑与选择停用的应用相关联的主题。本文档的内容会进行更新，以包含相关实现详情。

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

主题分类器

兴趣主题衍生自基于公开的应用信息（例如应用名称、说明和软件包名称）进行训练的分类器模型。

在使用分类器模型进行推理以计算给定周期的主题时，所用的那组信号会保留在设备上。这组信号可能包含已安装的应用或最近使用过的应用，之后还可能会进行扩展，以包含其他信号。
初始模型将由 Google 进行训练，其训练数据包含人工挑选的公开的应用信息标签。应用开发者可免费使用此模型进行测试，以了解其应用会归类为哪些主题。
初始模型将基于来自一组有限的应用商店（例如 Google Play 商店）的公开应用信息进行训练。
应用可能会映射到多个主题，可能未映射到任何主题，也可能未向用户的主题历史记录添加任何内容。如果某个应用映射到分类中的多个主题，为此应用选择的主题数量将按上限限定为 3 个。

用户控制功能

此设计旨在让用户能够查看和移除与其应用使用情况相关联的主题。此用户控制功能正处于实现阶段，将包含在未来的更新中。
如果用户卸载了某个应用，而此应用在过去 3 个周期的推断主题的选择过程中贡献过数据，系统不会从针对过去 3 个周期返回的主题列表中移除相应主题，以避免泄露与卸载相关的信息。

为了方便测试最终用户体验，您还可以启动一个应用内 intent，以便查看 Topics 的设置界面（与最终用户看到的界面类似）。以下为该调用的示例：

//Button that launches settings UI
private Button mSettingsAppButton;
private static final String RB_SETTING_APP_INTENT = "android.adservices.ui.SETTINGS";


//Does setup for button on screen that will launch settings UI to observe Topics
private void registerLaunchSettingsAppButton() {
    mSettingsAppButton.setOnClickListener(
        new View.OnClickListener() {

            @Override
            public void onClick(View view) {
                Context context = getApplicationContext();
                Intent activity2Intent = new Intent(RB_SETTING_APP_INTENT);
                activity2Intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
                context.startActivity(activity2Intent);
            }
        });
}

注册广告技术平台

如需访问 Topics API，所有广告技术平台（包括 Google 的广告技术平台平台）都需要完成注册流程。

应用开发者可以管理哪些广告技术开发者可以访问 Topics API，方法是应用清单中包含广告技术开发者的注册 ID。

返回的主题的加密

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

Privacy Sandbox 将从广告技术平台提供的端点提取这些密钥。周三我们建议的最佳实践是，键必须经常更新，但不能以后再更新每 6 个月更新一次。

Privacy Sandbox 会要求广告技术平台确认端点是否可用由广告技术平台在注册流程中提供。如需详细了解需要执行哪些操作，请参阅“注册” 开发者指南。

加密详细信息

引入加密后，对“GetTopics()”的调用现在将生成包含“EncryptedTopic”列表的响应对象的操作。解密这些结果将会生成的对象与前一个 Topic 对象具有相同的 JSON 格式。

Topics API 支持 HPKE（混合公钥）的一次性实现加密）。我们希望注册的调用方在注册期间提供的公开加密网址端点。这些键分别是预计为 Base64 编码。

EncryptedTopic 对象的 3 个字段。返回的主题列表可以是获取此值。

出于开发目的，您可以通过停用注册检查。这会强制 API 为加密您的响应。您可以使用相应的私钥。

为您推荐

注意：当 JavaScript 处于关闭状态时，系统会显示链接文字
版本说明
Protected Audience API on Android 开发者指南
Topics API 开发者指南