Topics API for Web

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Topics API 可在不使用第三方 Cookie 的情况下实现针对用户兴趣投放广告。

How the Topics API works

The Topics API can be used to observe and provide access to topics that appear to be of interest to the user, based on their activity. The Topics API can then give API callers (such as ad tech platforms) access to a user's topics of interest, but without revealing additional information about the user's activity.

Key concepts

• A topic is a human-readable topic of interest for the current user and is part of the Topics taxonomy.
• A caller is an entity, such as an app, a third-party SDK, a website, or service, that makes a request to the Topics API to observe or access a user's interests.
• A topic is observed by a caller, if the caller made a Topics API request from a web page or app associated with this topic during the past three epochs.
• An epoch is a period of topic computation, which defaults to one week.
• A taxonomy is a hierarchical list of categories, which includes, for example, such categories as /Arts & Entertainment/Music & Audio/Soul & R&B and /Business & Industrial/Business Services/Corporate Events.
• Topics are derived using a classifier model that maps user activity to zero or more topics.

Topics API flow core steps

The Topics API lifecycle has three main steps:

• Observe user activity, such as when they visit the web page https://cats.example/tabby/index.html or download the app cats.
• Derive topics from user activity, for example /Pets & Animals/Pets/Cats.
• Access topics previously observed for the user, for example as a signal to select relevant advertising (such as a cat food promotion).

Observe topics

Callers can only access topics of interest that they've observed. A caller observes a topic when they make a Topics API request from a context associated with this topic. To illustrate this concept, consider the following simplified example.

• Suppose there are two Topics API callers: A and B.
• There are two contexts:
  • Greenhouse, for example an app named Greenhouse or a website greenhouse.example, associated with the topic Home & Garden.
  • Tennis exercises, for example an app named Tennis Exercises or a website tennis.example, associated with the topic Sports/Tennis.
• Both caller A and B are present in the context of Greenhouse.
• Only the caller B is present in the context of Tennis exercises.
• Assume that no topics were observed for the user before epoch 1, for the sake of simplification.
• The user visits the Greenhouse app, and callers A and B make a Topics API call to record the user visit to the page or app (see the implementation guide suggested in Next steps to find out how to call the Topics API). This record (a hostname or app data) is later used to derive topics of interest. The Topics API will later mark the topic Home & Garden as observed by both callers A and B.
• The user visits the Tennis exercises app. Only the caller B sends a Topics API request. The Topics API will later mark the topic Sports/Tennis as observed by the caller B.
• By the end of the epoch, the Topics API refreshes the user's top topics and determines the callers that observed these topics based on user activity.
• Later, when the caller B makes another Topics API call, it can get either Home & Garden or Sports/Tennis topic (or, with a 5% chance, a random topic) for this user in the response array.
• Caller A can only access the topic Home & Garden, as it has never observed the topic Sports/Tennis. This means that a third-party will only learn about a user's topic of interest within the specific context (app or website) where it is present.

Derive topics

Topics derives topics of interest from user activity. The topics are selected from a predefined open-source taxonomy. Once per epoch, Topics refreshes the user's top five topics and the callers that observed them during the epoch. The Topics classifier model derives topics from user activity: hostname for a web page visit, app information on Android.

Caller accesses user's topics of interest

The API returns only topics that have been observed by the caller within the most recent three epochs. A maximum of three topics may be returned to a caller,one topic for each of the three recent epochs (if the caller observed topics for that epoch). The returned topics can be used by the caller to supplement any contextual information and can be combined to help find a more relevant ad for the user.

Epochs

The Topics API must ensure that the topics of interest it provides are kept up to date. The topics are inferred for a user based on their activity during a period of time known as an epoch, one week by default. Each user has their own epochs (epochs are "per user") and the initial start time is randomized.

Once each epoch, the Topics API computes the user's top five topics and determines which callers observed those topics using on-device information. The topic selected for each epoch is randomly selected from the user's top five topics for that time period. To further enhance privacy and ensure that all topics may be represented, there is a 5% chance the topic is randomly selected from all possible topics in the taxonomy of interests.

网站主题的实际应用

在网站上，系统会根据用户访问的网页的主机名推断主题。例如，为网站 dogs.example 推断出的主题可能是/宠物与动物/宠物/狗。

下图展示了一个经过简化的示例，演示了 Topics API 如何帮助广告技术平台选择适当的广告。此示例假定用户的浏览器已有可将网站主机名映射到主题的模型。

浏览器会根据调用 Topics API 的代码上下文确定调用方的来源。在实践中，这意味着 Topics 用户从其来源在 iframe 中调用 API，或者在对其来源的提取中添加主题。

例如，供应方平台 (SSP) 可嵌入到多个发布商网站中。然后，SSP 便可从其来源在 iframe 中调用 Topics API，以便观察与这些发布商网站上的用户相关联的主题。然后，这些主题可与需求方平台 (DSP) 共享，以帮助其为用户选择相关广告。

API 如何确定哪些调用方可以看到哪些主题

API 调用方仅会接收最近观察到的主题，而用户感兴趣的主题在每个周期刷新一次：在 Chrome 实现中，此时间段设为 1 周。这意味着，该 API 会提供一个滚动窗口，在该时段内，给定调用方可以接收观察到的主题。

下表概述了单个时段内用户假设的浏览记录示例（虽然不太现实，但规模较小），其中显示了与用户访问的网站相关联的主题，以及每个网站上存在的 API 调用方（在网站上包含的 JavaScript 代码中调用 document.browsingTopics() 的实体）。

网站	主题	网站上的 API 调用方
running.example	Running & Walking Athletic Shoes	adtech1.example adtech2.example
dogs.example	Dogs	adtech1.example
holiday.example	Hotels & Accommodations	adtech2.example
sunglasses.example	Sunglasses	[none]

该周期结束时（默认为一周），Topics API 会生成浏览器在这周内的热门主题。

• adtech1.example 现在符合接收 Running & Walking、Athletic Shoes 和 Dogs 主题的条件，因为它在 running.example 和 dogs.example 上观察到这些主题。
• adtech1.example 不符合针对该用户接收 Hotels & Accommodations 主题的条件，因为它未出现在用户最近访问的与该主题相关的任何网站上。
• adtech2.example 看到了 Running & Walking、Athletic Shoes 和 Hotels & Accommodations 主题，但没有看到 Dogs 主题。

该用户访问了 sunglasses.example，其中包含 Sunglasses 主题，但该网站并未调用 Topics API。这意味着，此时该 API 不会针对任何调用方返回 Sunglasses 主题。

在第二周，该用户访问了另一个网站：

网站	主题	网站上的 API 调用方
cameras.example	Camera & Photo Equipment	adtech2.example

此外，系统会将 adtech2.example 中的代码添加到 sunglasses.example 中：

网站	主题	网站上的 API 调用方
sunglasses.example	Sunglasses	adtech2.example

这意味着，除了第 1 周的 Running & Walking、Athletic Shoes 和 Hotels & Accommodations 外，adtech2.example 现在还能收到 Camera & Photo Equipment 和 Sunglasses 主题，但直到下一个周期（第 3 周）才能收到。这样可确保第三方能够了解到的用户过往详情（在本例中，是对时尚感兴趣）不会比通过 Cookie 了解到的多。

又过了两周，如果该用户未访问包含 adtech2.example 中的代码且涵盖这些主题的任何网站，那么 Running & Walking、Athletic Shoes 和 Hotels & Accommodations 可能会从 adtech2.example 的符合条件的主题列表中删除。

分类器模型

Topics 使用分类器模型将网站主机名映射到零个或多个主题（分析其他信息，例如完整网址或网页内容，可能有助于投放更具相关性的广告，但也可能会降低隐私保护）。

分类

主题是从分类中选择的。这些主题是由 Chrome 精心挑选出来的，但我们的目标是将分类变成由可信的生态系统贡献者维护的资源。分类需要足够小，以便许多用户的浏览器都与每个主题相关联。最终目标是，将分类法从外部来源获取，并纳入来自整个行业的反馈和想法。

为避免敏感类别，主题必须公开、经过人工挑选，并且及时更新。Chrome 使用的分类已经过人工挑选，排除了通常被视为敏感的类别，例如种族或性取向。

主题分类

我们为 5 万个热门网站手动挑选了主题，并将这个由主机名和主题组成的人工挑选替换列表用于训练分类器模型。对于热门网站，系统会从替换列表中获取主题，而不是使用分类器模型。您可以在计算机上本地查看替换列表。

Chrome 对 Topics API 的实现会下载表示模型的 TensorFlow Lite 文件，以便在用户设备上本地使用该模型。

如何选择用户最感兴趣的前五个热门主题

该 API 会为每个周期返回一个主题，最多返回三个。如果返回了三个，其中会包含当前周期和之前两个周期的主题。

1. 在每个周期结束时，浏览器会整理出一个包含满足以下条件的网页的列表：
   • 用户在周期内访问了该网页。
   • 该网页包含调用 document.browsingTopics() 的代码。
   • 该 API 已启用（例如，未被用户或响应标头禁止）。
2. 用户设备上的浏览器使用 Topics API 提供的分类器模型将每个网页的主机名映射到主题列表。

3. 浏览器会生成最热门的前五个主题的列表。

   • 分类法中的 22 个根主题中的每个主题都会根据广告生态系统的反馈，分配到“高实用性”或“标准实用性”存储分区。浏览器首先会按主题分配的分桶对主题进行排序。所有子主题都会继承其父级根主题的存储分区分配。系统会优先处理“实用性高”的主题。
   • 然后，浏览器会按每个令牌桶内的频率对主题进行排序。
   • 系统会从此排序列表中选择前五个主题，作为用户在该时间段内的热门主题。

然后，document.browsingTopics() 方法从每个周期的前五个热门主题中返回一个随机主题，并且从主题的完整分类中随机选择其中任一个主题的概率为 5%。在 Chrome 中，用户也可以移除各个主题，或清除其浏览记录，以减少该 API 返回的主题数。用户也可以选择停用该 API。

您可以通过 chrome://topics-internals 页面查看当前时段内观察到的主题的相关信息。

Next steps

See also

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

• Check out Topics demos, collab and walkthrough videos.
• See the list of Chrome flags that allow developers to customize the Topics API for testing.
• See how users and developers can control the API.
• Check out the resources for technical explainers and support. Ask questions, engage and share feedback.