Guide d'intégration de l'API Topics

Découvrez comment utiliser l'API Topics pour répondre à des cas d'utilisation spécifiques de technologies publicitaires.

Avant de commencer

La première étape consiste à vous familiariser avec l'API et les services Topics.

  1. Consultez la documentation destinée aux développeurs :
    1. Commencez par lire la présentation pour vous familiariser avec l'API Topics et ses fonctionnalités.
    2. Regardez le tutoriel de démonstration de Topics (vidéo).
    3. Essayez les démonstrations de l'en-tête de Topics et de l'API JavaScript.
    4. Dupliquez les démos (elles fournissent toutes deux des liens vers leur code) et exécutez-les à partir de votre propre site.
    5. Lisez l'explication de l'API pour en savoir plus.
  2. Vérifiez l'état de l'implémentation et le calendrier de l'API Topics.
  3. Découvrez le rôle de l'API dans la pertinence des annonces dans un avenir sans cookies.
  4. Pour être informé des changements d'état de l'API, rejoignez la liste de diffusion pour les développeurs et tenez-vous informé des dernières nouveautés de Topics.
  5. Tenez-vous informé des dernières actualités concernant l'API Topics.
  6. Participez à la conversation en consultant les problèmes GitHub ou les appels W3C.
  7. Si vous rencontrez des termes que vous ne connaissez pas, consultez le glossaire de la Privacy Sandbox.
  8. Pour en savoir plus sur les concepts de Chrome, tels que les indicateurs Chrome, consultez les courtes vidéos et articles disponibles à l'adresse goo.gle/cc.

Compiler et tester en local

Cette section explique comment essayer l'API Topics en tant que développeur individuel.

  1. Tests et déploiement en local (durée estimée: deux jours environ)
    1. Activez l'API avec votre navigateur local depuis la ligne de commande à l'aide des flags de fonctionnalité. Testez les démonstrations de l'en-tête et de l'API JavaScript pour voir Topics en action (vidéo de présentation).
    2. Exécutez le colab Topics pour tester l'inférence de thèmes à l'aide du modèle de machine learning Topics.

Activer Topics dans votre navigateur

Pour activer l'API Topics dans votre propre instance Chrome à des fins de test en local, deux options s'offrent à vous:

  1. Ouvrez chrome://flags/#privacy-sandbox-ads-apis et activez les API Privacy Sandbox.
  2. (Recommandé) Exécutez Chrome à partir de la ligne de commande avec des indicateurs Chromium en utilisant les paramètres propres à l'API Topics pour effectuer la configuration selon vos besoins.
Activez les API Privacy Sandbox sur chrome://flags/#privacy-sandbox-ads-apis.
Activez les API Privacy Sandbox.

Vous bénéficiez d'un contrôle plus précis sur les fonctionnalités de Topics en exécutant Chrome à partir de la ligne de commande. Par exemple, il est possible de définir des époques Topics (la période utilisée par l'API pour calculer les centres d'intérêt des utilisateurs) et de configurer le comportement de l'API en fonction de vos besoins.

N'oubliez pas que si chrome://flags/#privacy-sandbox-ads-apis est activé, celui-ci remplace le paramètre d'epoch de la ligne de commande et rétablit la valeur par défaut (actuellement une semaine).

Prévisualiser les mécanismes de l'API Topics

Vous pouvez obtenir une visibilité sur les mécanismes de l'API Topics sous-jacents en local à l'aide des outils chrome://topics-internals.

Accédez à l'API Topics sur chrome://topics-internals.
Onglet "Topics State" (État des thèmes) de l'outil chrome://topics-internals

Utilisez l'outil "Internals" de l'API Topics pour tester le classificateur en local en fonction des sites que vous consultez.

Cet outil vous permet de vérifier:

  • Topics State (État des thèmes) : affiche les thèmes observés pour l'utilisateur actuel.
  • Classificateur:aperçu des thèmes déduits pour les noms d'hôte.
  • Fonctionnalités et paramètres:consultez les valeurs des paramètres de l'API pour vérifier que les flags de fonctionnalité fonctionnent comme prévu.

Découvrez comment déboguer Topics avec l'outil Internals.

Comment l'API renvoie les thèmes

Si Chrome ne dispose pas d'un nombre suffisant de thèmes observés pour créer les cinq thèmes principaux d'une epoch (une semaine), l'API Topics ajoute des thèmes aléatoires pour compléter les cinq principaux. La colonne "Interne Topics" intitulée Réel ou aléatoire indique si ce sujet spécifique était basé sur une observation réelle ou sur une "marge intérieure" aléatoire supplémentaire pour compléter les cinq premiers éléments. Pour en savoir plus sur ce mécanisme, consultez l'explication.

Le thème de chaque epoch est choisi de manière aléatoire parmi les cinq thèmes principaux associés à l'utilisateur pour cette période. Si un nombre insuffisant de thèmes ont été observés au cours de l'epoch, des thèmes supplémentaires seront choisis au hasard pour former le total de cinq thèmes. Ces thèmes sélectionnés de manière aléatoire sont soumis à des filtres.

Pour améliorer davantage la confidentialité et garantir que tous les thèmes sont représentés, il y a 5% de chances que le thème sélectionné pour une epoch soit choisi au hasard parmi tous les thèmes, plutôt que parmi ceux observés. Comme dans le cas ci-dessus, où trop peu de thèmes ont été observés, ces thèmes sélectionnés de manière aléatoire ne sont pas soumis au filtrage.

Pour en savoir plus sur la sélection des thèmes, consultez Classification des thèmes.

Principales recommandations

  1. Assurez-vous de fermer (et d'arrêter) tous les processus Chrome avant de lancer le nouveau à l'aide des indicateurs.
  2. Si vous effectuez des tests dans votre environnement local, vous devez désactiver chrome://flags/#privacy-sandbox-ads-apis, car il remplace les paramètres de la ligne de commande et rétablit les valeurs par défaut.
  3. Utilisez la page de débogage pour comprendre comment Topics fonctionne localement.
  4. Si vous avez des questions, consultez les problèmes GitHub pour obtenir des explications.
  5. Si l'API ne fonctionne pas comme prévu, suivez nos conseils de dépannage.

Planifier votre déploiement de MVP

L'API Topics permet d'accéder aux centres d'intérêt observés pour un utilisateur, sans avoir à suivre les sites qu'il visite ni à exposer son historique de navigation.

L'appelant de l'API Topics est l'entité qui appelle la méthode JavaScript document.browsingTopics(), ou qui observe les sujets et y accède à l'aide des en-têtes de requête HTTP. Votre code, et l'eTLD+1 à partir duquel il est appelé, dans ce cas, correspondent à l'appelant. Lorsque vous appelez l'API Topics, vous demandez au navigateur de l'utilisateur d'observer les thèmes d'intérêt lorsqu'il visite un site Web. Cette visite est ensuite prise en compte dans le calcul des thèmes pour l'epoch suivante.

L'API Topics est conçue pour filtrer les résultats par appelant ou par eTLD+1 du contexte d'appel. En d'autres termes, l'origine de l'iFrame (si vous utilisez l'API JavaScript) ou l'URL de la requête de récupération (en cas d'utilisation des en-têtes) est considérée comme l'appelant, et les thèmes sont calculés en fonction de cet appelant.

Le schéma suivant illustre cette approche:

Étapes suivies par l'API Topics lorsque les utilisateurs consultent des sites qui l'utilisent.
Comment l'API observe-t-elle les sujets et y accède-t-il ?

Dans ce diagramme:

  1. Un utilisateur ouvre Chrome et consulte plusieurs sites Web (customerA.example, customerB.example.br, etc.) qui incluent l'iFrame de votre technologie publicitaire (source: iFrame.adtech.example) ou l'appel de récupération transmettant les en-têtes.
    • Chrome enregistrera les thèmes qui intéressent cet utilisateur.
  2. Au bout de sept jours de navigation, les thèmes d'intérêt étant observés par l'API Topics, le même utilisateur sur le même appareil visite un site Web cible (publisher-e.example). L'API Topics renvoie une liste de thèmes. Dans cet exemple spécifique, un thème calculé à partir des observations de cet utilisateur la semaine précédente est renvoyé.
    • Seuls les navigateurs des utilisateurs ayant consulté des sites qu'adtech.example a observés à l'étape 1 renverront les résultats des thèmes à l'étape 2 (nous appelons cela le filtrage des observations : vous ne pouvez pas voir les thèmes des utilisateurs que vous n'avez jamais vus auparavant).
  3. Avec cette liste (qui ne contient qu'un seul sujet pour le moment), vous pouvez appeler votre API backend (ads.adtech.example/topics-backend) pour utiliser les données sur les thèmes dans votre ensemble de données contextuel.
  4. Désormais, en fonction de votre cas d'utilisation, vous pouvez créer une expérience plus personnalisée pour cet utilisateur en accédant aux sujets d'intérêt que vous avez observés pour lui au cours des dernières semaines.

Appeler l'API Topics

Il existe deux façons d'observer les sujets d'un utilisateur et d'y accéder. Grâce à

  • L'API JavaScript à partir d'un iFrame :
    • Ajouter un iFrame sur les sites Web cibles (sites Web de l'éditeur) qui contient du code JavaScript appelant l'API Topics avec document.browsingTopics().
  • Option d'en-têtes :
    • Extraire (recommandé) ou XHR (non recommandé et n'était disponible que pendant la phase d'évaluation) :
      • Vous pouvez accéder aux thèmes depuis l'en-tête Sec-Browsing-Topics dans les requêtes adressées au backend de technologie publicitaire. Il s'agit de l'option la plus performante (une faible latence pour observer les sujets d'un utilisateur spécifique).
    • Avec un tag iFrame avec l'attribut browsingtopics :
      • Vous pouvez ajouter un iFrame avec un attribut browsingtopics pour que Chrome inclue les thèmes (observés pour l'eTLD+1 de l'iFrame) dans l'en-tête Sec-Browsing-Topics de la demande d'iFrame.

Implémenter avec du code JavaScript et des iFrames

Nous vous recommandons de dupliquer la démo de l'API JavaScript de Topics ou la démonstration de l'en-tête et de l'utiliser comme point de départ pour votre code.

Vous pouvez inclure un élément <iframe> en HTML ou ajouter un iFrame de façon dynamique avec JavaScript. Pour créer un iFrame de façon dynamique, vous pouvez utiliser le code JavaScript suivant:

const iframe = document.createElement('iframe');
iframe.setAttribute('src', 'https://...');
document.body.appendChild(iframe);

Vérifiez si l'API Topics est compatible et disponible sur cet appareil via la détection des fonctionnalités:

'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
  console.log('document.browsingTopics() is supported on this page') :
  console.log('document.browsingTopics() is not supported on this page');

Appelez l'API Topics à partir de cet iFrame:

const topics = await document.browsingTopics();

Vous devriez recevoir la liste des thèmes observés pour cet utilisateur au cours des trois dernières semaines. N'oubliez pas que cette liste peut être vide ou inclure un, deux ou trois thèmes sur une période maximale des trois dernières semaines.

Voici un exemple de ce que renvoie l'API:

[{'configVersion': String, 
  'modelVersion': String, 
  'taxonomyVersion': String, 
  'topic': Number, 
  'version': String}]
  • configVersion: chaîne identifiant la configuration actuelle.
  • modelVersion: chaîne identifiant le classificateur de machine learning utilisé pour déduire les thèmes.
  • taxonomyVersion: chaîne identifiant l'ensemble des thèmes actuellement utilisés par le navigateur.
  • topic: numéro identifiant le sujet dans la taxonomie.
  • version: chaîne combinant les éléments configVersion et modelVersion.

En savoir plus sur cette implémentation

Implémenter avec des en-têtes HTTP

Les sujets sont accessibles à partir de l'en-tête Sec-Browsing-Topics d'une requête fetch()/XHR ou d'une requête iframe.

En-têtes de requête et de réponse permettant de définir et de récupérer des sujets.
En-têtes pour iFrame et fetch().

Vous pouvez marquer les sujets fournis par les en-têtes de requête comme observés en définissant un en-tête Observe-Browsing-Topics: ?1 sur la réponse à la requête. Le navigateur les utilise ensuite pour calculer les centres d'intérêt de l'utilisateur.

Si l'API renvoie un ou plusieurs thèmes, une requête de récupération à l'eTLD+1 à partir de laquelle les sujets ont été observés inclut un en-tête Sec-Browsing-Topics comme celui-ci: 

(325);v=chrome.1:1:1, ();p=P000000000

Si aucun sujet n'est renvoyé par l'API, l'en-tête se présente comme suit:

();p=P0000000000000000000000000000000

Les valeurs d'en-tête Sec-Browsing-Topics sont complétées pour réduire le risque qu'un pirate informatique découvre le nombre de sujets limités à un appelant en fonction de la longueur de l'en-tête.

Implémentation avec fetch()

Sur la page de l'éditeur, ajoutez votre code pour la demande de récupération, en veillant à inclure {browsingTopics: true}.

fetch('<topics_caller_eTLD+1>', {browsingTopics: true})
    .then((response) => {
        // Process the response
 })

Dans les navigateurs compatibles avec l'API, la requête fetch() inclut un en-tête Sec-Browsing-Topics qui répertorie les sujets observés pour le nom d'hôte de l'URL de la requête.

Implémenter avec un iFrame

Comme pour une requête fetch(), l'en-tête Sec-Browsing-Topics est envoyé lorsque l'attribut browsingtopics est utilisé dans un iFrame.

<iframe src="<topics_caller_eTLD+1>" browsingtopics></iframe>

Dans ce cas, sera l'appelant, tout comme l'appel de récupération.

Côté serveur : identique dans tous les cas

Pour que les thèmes de l'en-tête de requête Sec-Browsing-Topics soient marqués comme observés par le navigateur, mais aussi pour inclure la visite actuelle de la page dans le calcul des thèmes principaux de la prochaine epoch de l'utilisateur, la réponse du serveur doit inclure Observe-Browsing-Topics: ?1.

Voici un exemple JavaScript utilisant setHeader():

res.setHeader('Observe-Browsing-Topics', '?1');

Implémentation dans le backend de Topics

L'ajout d'un backend pour Topics est facultatif. Votre choix dépend de la manière dont vous souhaitez utiliser les thèmes calculés sur l'appareil (dans le navigateur) et de l'emplacement où vous le souhaitez. 

// Use the language/framework/stack of your preference
function processTopicsBackendAPI(topics, user, domain, caller) {
  // Validate inputs
  // If the list is not empty, continue
  // Use topics as an additional contextual signal
}

Utiliser les thèmes comme données contextuelles

Les données sur les thèmes peuvent être prises en compte avec d'autres signaux, comme les URL, les mots clés et même les balises, comme indicateur supplémentaire concernant votre audience.

Comme expliqué dans l'article Optimiser la pertinence des annonces après les cookies tiers, plusieurs approches permettent d'exploiter Topics pour diffuser des annonces pertinentes. Certaines d'entre elles impliquent l'utilisation de thèmes pour créer des audiences, tandis que d'autres suggèrent de l'utiliser, entre autres, pour entraîner des modèles de machine learning (apprentissage automatique) qui serviront à déduire des centres d'intérêt supplémentaires de l'audience ou même à optimiser la logique d'enchères.

Migration Build and Deploy

  1. Collectez les thèmes en observant les utilisateurs en production (pas encore mis à l'échelle) (durée estimée: environ une semaine)
    1. Comprendre les options disponibles: iFrame et JavaScript, ou les en-têtes HTTP
    2. Définissez le domaine de l'iFrame.
    3. Créez le code JavaScript en vous servant de l'application de démonstration comme référence de code, ou implémentez l'option "Headers" (En-têtes).
    4. Déployez Topics dans votre environnement contrôlé (certains sites de production).
    5. Ajoutez l'implémentation de Topics à certains sites cibles (pas plus de cinq sites à l'heure actuelle).
    6. Tests fonctionnels et validation.
  2. [Facultatif] Utiliser les données Topics comme signal contextuel (avec des URL, des balises, etc.) (Durée estimée: environ 3 jours.)
    1. Une fois que vous avez reçu la liste de sujets, vous pouvez l'envoyer à votre backend avec d'autres signaux de contexte.

Déployer sur certains sites cibles

Maintenant que vous avez le code, ajoutons-le à certains sites cibles pour un premier test et pour nous assurer que l'API est stable et fonctionne dans cet environnement contrôlé.

Nous vous recommandons de choisir des sites Web cibles qui:

  • Enregistrer un petit nombre de visites mensuelles (moins d'un million de visites par mois environ): commencez par déployer l'API auprès d'une petite audience.
  • Vous détenez et contrôlez: si nécessaire, vous pouvez rapidement désactiver l'implémentation sans approbations complexes.
  • Ne sont pas critiques pour l'entreprise: étant donné que cette implémentation peut perturber l'expérience utilisateur, commencez par les sites cibles à faible risque.
  • Pas plus de cinq sites en tout: vous n'avez pas besoin d'un trafic ni d'une exposition aussi importants pour le moment.
  • Représenter différents thèmes: choisissez des sites Web qui représentent différentes catégories (par exemple, un sur le sport, un autre sur l'actualité, un autre sur l'alimentation et les boissons, etc.). Vous pouvez utiliser l'outil Topics interne de Chrome pour valider les domaines et la façon dont ils sont classés par le classificateur de machine learning Topics. Pour en savoir plus sur le débogage, consultez le guide du développeur de l'API Topics.

Tests fonctionnels et validation

Lorsque vous appelez l'API Topics dans cet environnement limité, vous pouvez vous attendre à ce qui suit:

  • Tableau vide des thèmes [] s'il s'agit du premier appel effectué par cet appareil pour ce site et cet appelant au cours des sept derniers jours.
  • Liste de zéro à trois thèmes représentant les centres d'intérêt de cet utilisateur.
  • Après sept jours d'observation, vous devriez obtenir :
    • Un thème représentant l'intérêt de cet utilisateur calculé à partir de l'historique de navigation de la semaine en question.
      • Remarque importante: si vous n'avez pas observé suffisamment de thèmes pour qu'un utilisateur puisse calculer les cinq thèmes principaux de la semaine, l'API Topics ajoute autant de thèmes aléatoires que nécessaire pour obtenir le nombre total de cinq thèmes. En savoir plus sur l'API
  • Une nouvelle entrée de sujet remplace l'un des trois si vous l'appelez après quatre semaines d'observation.
    • En effet, l'API Topics sera stable pendant les semaines suivantes, sans dévoiler trop d'intérêts pour les utilisateurs. Pour en savoir plus, consultez GitHub.
  • Si vous n'avez pas observé de thèmes pour l'utilisateur depuis plus de trois semaines, l'API Topics renvoie à nouveau un tableau vide [].

Mesurez les performances et les métriques de l'expérience utilisateur.

  • La durée d'exécution des appels JavaScript vers l'API Topics dans un iFrame multi-origine doit être mesurée pour être utilisée dans l'analyse future des performances. Veillez à collecter et stocker correctement les données de télémétrie dans votre backend.
    • Une autre métrique possible est également le temps nécessaire pour créer un iFrame et postMessage() thèmes, une fois les thèmes reçus.

Dépannage

J'appelle l'API Topics, mais le résultat affiche une valeur nulle. Que dois-je faire ?
Si vous appelez l'API Topics au cours de la première semaine suivant l'observation d'un utilisateur, ce comportement est normal.

Principales recommandations

  1. Testez le code de l'interface pour vous assurer que JavaScript fonctionne comme prévu.

  2. Testez votre backend pour recevoir les résultats des thèmes.

    1. N'oubliez pas de vous assurer que les types de données et les paramètres de l'API backend sont correctement configurés.
    2. Assurez-vous que votre backend est configuré pour évoluer de manière appropriée.

  3. D'après notre expérience, il est nécessaire de prévoir au moins trois semaines avant de commencer à obtenir des résultats plus pertinents pour les thèmes.

  4. Topics n'est pas activé pour tous les utilisateurs:

    1. Les utilisateurs peuvent désactiver explicitement l'API Topics.
    2. Les pages de l'éditeur peuvent contrôler le règlement relatif aux autorisations. Consultez la section (désactiver) dans le guide du développeur de l'API Topics.
    3. Pour en savoir plus, consultez chromestatus.com.

  5. Ajoutez des métriques et l'observabilité à cet environnement: vous en aurez besoin pour analyser les premiers résultats. Voici quelques exemples de métriques:

    1. Latence des appels
    2. Erreurs HTTP sur les appels de sujets

  6. Essayez de limiter les modifications de votre mise en œuvre au cours des trois premières semaines.

Adaptation à la production

Voici un résumé détaillé de la manière dont vous pouvez passer en production. La procédure à suivre est expliquée ci-dessous.

  1. Mise à l'échelle de l'implémentation (production). Cette procédure est décrite ci-dessous.
    1. Ajouter le cadre iFrame aux sites Web de plusieurs éditeurs
  2. Traiter et utiliser les données des thèmes (durée estimée: environ quatre semaines)
    1. Intégrez les données sur les thèmes en tant que signal cumulatif avec d'autres données.
    2. Trouver des partenaires de test d'enchères en temps réel
    3. Exécutez des tests d'utilité avec des thèmes pour ajouter un signal à vos autres données.

Adapter votre implémentation

À ce stade, vous devriez collecter des données sur les thèmes depuis certains sites dans un environnement contrôlé, avec un niveau de confiance élevé pour la solution dans son ensemble.

Il est maintenant temps de faire évoluer cette implémentation en déployant le même code sur un plus grand nombre de sites Web cibles. Vous pourrez ainsi observer plus d'utilisateurs, collecter plus de données sur les thèmes et mieux comprendre vos audiences.

Nous vous recommandons de suivre les conseils suivants :

  1. Procédez au déploiement progressif sur vos sites, surtout si le trafic est important.
  2. Effectuez des tests de charge sur vos données de thèmes en fonction du trafic attendu.
    1. Vérifiez que votre backend peut gérer un grand nombre d'appels.
    2. Configurer la collecte de métriques et les journaux pour l'analyse
  3. Immédiatement après avoir déployé l'API Topics, vérifiez vos métriques pour détecter tout problème grave aux utilisateurs finaux. Consultez régulièrement vos métriques.
  4. En cas d'interruption ou de comportement inattendu, effectuez un rollback du déploiement et analysez vos journaux pour identifier le problème et le résoudre.

Interagir et partager des commentaires