L'API Topics permet de diffuser des annonces ciblées par centres d'intérêt sans utiliser de cookies tiers.
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 appcats
. - 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
.
- Greenhouse, for example an app named Greenhouse or a website greenhouse.example, associated with the topic
- 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
orSports/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 topicSports/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.
Thèmes sur le Web en pratique
Sur le Web, les thèmes sont déduits des noms d'hôte des pages que l'utilisateur consulte. Par exemple, le thème inféré pour le site Web dogs.example peut être /Animaux et animaux de compagnie/Animaux de compagnie/Chiens.
Le schéma suivant montre un exemple simplifié pour illustrer comment l'API Topics peut aider une plate-forme de technologie publicitaire à sélectionner une annonce appropriée. L'exemple suppose que le navigateur de l'utilisateur dispose déjà d'un modèle permettant de mapper les noms d'hôte de site Web aux sujets.

Le navigateur détermine l'origine de l'appelant à partir du contexte du code qui appelle l'API Topics. En pratique, cela signifie que les utilisateurs de Topics appellent l'API dans un iFrame à partir de leur origine ou qu'ils incluent des thèmes dans une requête à leur origine.
Par exemple, une plate-forme côté offre (SSP) peut être intégrée sur plusieurs sites de diffuseurs. Le SSP peut ensuite appeler l'API Topics dans un iFrame à partir de son origine, ce qui lui permet d'observer les thèmes associés à un utilisateur sur les sites de ces éditeurs. Ces thèmes peuvent ensuite être partagés avec une plate-forme côté demande (DSP) pour l'aider à sélectionner une annonce pertinente pour l'utilisateur.
Comment l'API détermine les sujets que les appelants peuvent voir
Les appelants de l'API ne reçoivent que les thèmes qu'ils ont récemment observés. Les thèmes d'un utilisateur sont actualisés une fois par epoch, une période définie sur une semaine dans l'implémentation de Chrome. Cela signifie que l'API fournit une fenêtre glissante dans laquelle un appelant donné peut recevoir des thèmes observés.
Le tableau suivant présente un exemple (bien que trop petit pour être réaliste) d'historique de navigation hypothétique d'un utilisateur au cours d'une seule époque. Il montre les thèmes associés aux sites qu'il a visités et les appelants d'API présents sur chaque site (les entités qui appellent document.browsingTopics()
dans le code JavaScript inclus sur le site).
Site | Thèmes | Appelants d'API sur le site |
---|---|---|
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] |
À la fin de l'epoch (par défaut, une semaine), l'API Topics génère les principaux thèmes du navigateur pour la semaine.
- adtech1.example peut désormais recevoir les thèmes
Running & Walking
,Athletic Shoes
etDogs
, car il les a observés sur running.example et dogs.example. - adtech1.example ne peut pas recevoir le thème
Hotels & Accommodations
pour cet utilisateur, car il n'est présent sur aucun des sites que l'utilisateur a récemment consultés et associés à ce thème. - adtech2.example a vu les sujets
Running & Walking
,Athletic Shoes
etHotels & Accommodations
, mais pas le sujetDogs
.
L'utilisateur a visité sunglasses.example, qui comporte le thème Sunglasses
, mais aucun appel à l'API Topics n'a été effectué sur ce site. À ce stade, cela signifie que le thème Sunglasses
ne sera pas renvoyé par l'API pour un appelant donné.
Au cours de la deuxième semaine, l'utilisateur visite un autre site:
Site | Thèmes | Appelants d'API sur le site |
---|---|---|
cameras.example | Camera & Photo Equipment |
adtech2.example |
De plus, le code de adtech2.example est ajouté à sunglasses.example
:
Site | Thèmes | Appelants d'API sur le site |
---|---|---|
sunglasses.example | Sunglasses |
adtech2.example |
En plus de Running & Walking
, Athletic Shoes
et Hotels & Accommodations
de la semaine 1, cela signifie qu'adtech2.example pourra désormais recevoir les sujets Camera & Photo Equipment
et Sunglasses
, mais pas avant l'époque suivante, la semaine 3. Cela garantit que les tiers ne peuvent pas en savoir plus sur le passé d'un utilisateur (dans ce cas, son intérêt pour la mode) qu'ils ne le pourraient avec des cookies.
Au bout de deux semaines supplémentaires, Running & Walking
, Athletic Shoes
et Hotels & Accommodations
peuvent être supprimés de la liste des thèmes éligibles d'adtech2.example si l'utilisateur ne consulte aucun site avec ces thèmes qui incluent du code provenant d'adtech2.example.

Modèle de classificateur
Topics utilise un modèle de classification qui met en correspondance les noms d'hôte des sites Web avec zéro ou plusieurs thèmes (l'analyse d'informations supplémentaires, telles que les URL complètes ou le contenu des pages, peut permettre de diffuser des annonces plus pertinentes, mais peut aussi réduire la confidentialité).
Taxonomie
Les thèmes sont sélectionnés à partir d'une taxonomie. Ces thèmes ont été sélectionnés par Chrome dans le but de faire de la taxonomie une ressource gérée par des contributeurs de confiance de l'écosystème. La taxonomie doit être suffisamment petite pour que les navigateurs de nombreux utilisateurs soient associés à chaque sujet. L'objectif final est que la taxonomie soit fournie par un tiers qui intègre les commentaires et les idées de l'ensemble du secteur.
Pour éviter les catégories sensibles, les thèmes doivent être publics, sélectionnés par l'humain et à jour. La taxonomie utilisée par Chrome a été gérée par l'humain pour exclure les catégories généralement considérées comme sensibles, telles que l'origine ethnique ou l'orientation sexuelle.
Classification des thèmes
Les thèmes sont sélectionnés manuellement pour 50 000 sites populaires. Cette liste de forçage personnalisée de noms d'hôtes et de thèmes est utilisée pour entraîner le modèle de classificateur. Pour les principaux sites, les thèmes sont accessibles à partir de la liste de forçage plutôt qu'à l'aide du modèle de classificateur. Vous pouvez consulter la liste des forçages en local sur votre ordinateur.

chrome://topics-internals
liste la version du modèle, son chemin d'accès et les thèmes associés à chaque hôte listé.L'implémentation de l'API Topics par Chrome télécharge un fichier TensorFlow Lite représentant le modèle afin qu'il puisse être utilisé localement sur l'appareil de l'utilisateur.
Comment les cinq thèmes principaux de l'utilisateur sont sélectionnés
L'API renvoie un thème pour chaque époque, jusqu'à trois au maximum. Si trois thèmes sont renvoyés, cela inclut les thèmes de l'époque actuelle et des deux précédentes.
- À la fin de chaque époque, le navigateur compile une liste de pages qui répondent aux critères suivants :
- L'utilisateur a consulté la page pendant l'époque.
- La page inclut du code qui appelle
document.browsingTopics()
. - L'API a été activée (par exemple, elle n'a pas été bloquée par l'utilisateur ni par un en-tête de réponse).
- Le navigateur, sur l'appareil de l'utilisateur, utilise le modèle de classificateur fourni par l'API Topics pour mapper le nom d'hôte de chaque page à une liste de thèmes.
Le navigateur génère une liste des cinq premiers sujets.
- Chacun des 22 thèmes de la taxonomie est attribué à un bucket "haute utilité" ou "utilité standard" en fonction des commentaires de l'écosystème publicitaire. Le navigateur trie d'abord les sujets en fonction de leur attribution à un bucket. Tous les sujets descendants héritent de l'attribution de bucket de leur sujet racine parent. Les sujets "hautement utiles" sont prioritaires.
- Le navigateur trie ensuite les thèmes par fréquence dans chaque ensemble.
- Les cinq thèmes principaux de cette liste triée sont sélectionnés comme thèmes principaux de l'utilisateur pour cette époque.
La méthode document.browsingTopics()
renvoie ensuite un thème aléatoire parmi les cinq premiers pour chaque époque, avec une probabilité de 5% que l'un de ces thèmes soit choisi de manière aléatoire dans la taxonomie complète des thèmes. Dans Chrome, les utilisateurs peuvent également supprimer des thèmes spécifiques ou effacer leur historique de navigation pour réduire le nombre de thèmes renvoyés par l'API. Les utilisateurs peuvent également désactiver l'API.
Vous pouvez consulter des informations sur les thèmes observés pendant l'époque actuelle sur la page chrome://topics-internals
.
Étapes suivantes
Configuration
Implémenter des sujets
Voir aussi
Consultez nos ressources pour mieux comprendre l'API Topics sur le Web.
- Découvrez les démonstrations, vidéos de collaboration et tutoriels sur Topics.
- Consultez la liste des indicateurs Chrome permettant aux développeurs de personnaliser l'API Topics pour les tests.
- Découvrez comment les utilisateurs et les développeurs peuvent contrôler l'API.
- Consultez les ressources pour obtenir des explications techniques et obtenir de l'aide. Posez des questions, interagissez et partagez vos commentaires.