API Topics pour le Web

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 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.
Diagram showing that the Topics API only marks the topics as observed if the callers has presence in the context.
The Topics API marks the topics observed only by the callers that have presence in the context of these topics. The callers will only be able to access the topics they have observed.

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.

Schéma illustrant les étapes du cycle de vie de l'API Topics, de la visite de sites Web par un utilisateur à l'affichage d'une annonce.
Le diagramme du cycle de vie de l'API Topics présente les étapes des actions de l'API d'un point de vue général.

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 et Dogs, 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 et Hotels & Accommodations, mais pas le sujet Dogs.

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.

Étapes suivies par l'API Topics lorsque les utilisateurs visitent des sites qui utilisent l'API.
Comment l'API observe-t-elle et accède-t-elle aux thèmes ?

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.

Page chrome://topics-internals avec le panneau "Classifier" (Classificateur) sélectionné.
Le panneau "Classificateur" de la page 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.

  1. À 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).
  2. 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.
  3. 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

Préparez votre environnement à tester et à développer des applications Web avec l'API Topics.
Découvrez les détails de l'implémentation et des exemples de code permettant aux appelants d'observer et d'accéder aux sujets.

Voir aussi

Consultez nos ressources pour mieux comprendre l'API Topics sur le Web.