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 pour les 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. Consultez l'explication sur l'API pour en savoir plus.
  2. Vérifiez l'état d'implémentation et le calendrier de l'API Topics.
  3. Comprendre le rôle de l'API dans l'amélioration de la pertinence des annonces dans un avenir sans cookies
  4. Pour être informé des changements d'état dans l'API, rejoignez la liste de diffusion des développeurs et tenez-vous informé des dernières actualités de Topics.
  5. Tenez-vous informé des dernières actualités sur l'API Topics.
  6. Participez à la conversation via des problèmes GitHub ou des appels W3C.
  7. Si vous rencontrez des termes inconnus, consultez le glossaire de la Privacy Sandbox.
  8. Pour en savoir plus sur les concepts de Chrome, comme les indicateurs Chrome, consultez les courts articles et les vidéos courtes disponibles sur 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: environ deux jours)
    1. Activez l'API dans votre navigateur local à partir de la ligne de commande à l'aide des indicateurs de fonctionnalité. Testez les démonstrations header et de l'API JavaScript pour observer Topics en action (tutoriel vidéo).
    2. Exécutez la colab Topics pour tester l'inférence de sujet à 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 tests 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 en ajoutant des indicateurs Chromium à l'aide de paramètres spécifiques à l'API Topics pour procéder à la configuration selon vos besoins.
Activez les API Privacy Sandbox sur chrome://flags/#privacy-sandbox-ads-apis.
Activer les API Privacy Sandbox

Vous pouvez contrôler plus précisément 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 l'option chrome://flags/#privacy-sandbox-ads-apis est activée, elle remplace le paramètre d'epoch de la ligne de commande et rétablit la valeur par défaut (actuellement une semaine).

Aperçu de la mécanique d'API Topics

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

Jetez un œil à l'API Topics sur chrome://topics-internals.
Onglet "État des thèmes" dans chrome://topics-internals tools

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

Cet outil vous permet de vérifier les éléments suivants:

  • État des thèmes:affiche les thèmes observés pour l'utilisateur actuel.
  • Classificateur:prévisualisez les sujets déduits pour les noms d'hôte.
  • Fonctionnalités et paramètres:affichez 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 thèmes principaux. La colonne Topics Internals intitulée Real or Random (Réel ou aléatoire) indique si le sujet en question est basé sur une observation réelle ou une marge intérieure aléatoire supplémentaire pour compléter le top 5. Pour en savoir plus sur ce mécanisme, consultez l'explication.

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

Pour renforcer la confidentialité et garantir que tous les thèmes peuvent être représentés, il y a 5% de chances que le thème sélectionné pour une epoch soit sélectionné au hasard parmi tous les thèmes, plutôt que parmi les thèmes 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 la page Classification des thèmes.

Principales recommandations

  1. Assurez-vous de fermer (et d'arrêter) tous les processus Chrome avant d'en démarrer un 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 ligne de commande et rétablit les valeurs par défaut.
  3. Consultez la page de débogage pour comprendre comment fonctionne Topics en local.
  4. Si vous avez des questions, consultez la explication sur les problèmes GitHub.
  5. Si l'API ne fonctionne pas comme prévu, suivez nos conseils de dépannage.

Planifier le déploiement de MVP

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

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

Les étapes suivies par l'API Topics lorsque les utilisateurs visitent des sites qui l'utilisent.
Comment l'API observe-t-elle les sujets et y accède-t-elle.

Dans ce diagramme:

  1. Un utilisateur ouvre Chrome et consulte plusieurs sites Web (clientA.example, clientB.example.br, etc.) qui incluent l'iFrame de votre technologie publicitaire (source: iframe.adtech.example) ou les en-têtes de transmission de l'appel de récupération.
    • Chrome enregistrera les sujets qui l'intéressent.
  2. Après sept jours de navigation, avec les thèmes d'intérêt observés par l'API Topics, le même utilisateur visite un site Web cible (éditeur-e.example) sur le même appareil. L'API Topics renvoie une liste de thèmes. Dans cet exemple spécifique, un sujet calculé à partir de la semaine précédente d'observations de cet utilisateur est renvoyé.
    • Seuls les navigateurs des utilisateurs qui ont consulté les sites qu'adtech.example a observés à l'étape 1 renverront les résultats des thèmes de l'étape 2 (nous appelons ce 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 concerne 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 centres 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) contenant du code JavaScript appelant l'API Topics à l'aide de document.browsingTopics().
  • Option "Headers" (En-têtes) :
    • Récupération (recommandée) ou XHR (non recommandée et disponible uniquement pendant la phase d'évaluation) :
      • Vous pouvez accéder aux thèmes à partir de l'en-tête Sec-Browsing-Topics dans les requêtes adressées au backend ad tech. Il s'agit de l'option la plus performante (faible latence pour observer les sujets d'un utilisateur spécifique).
    • En utilisant un tag iFrame avec l'attribut browsingtopics :
      • Vous pouvez ajouter un iFrame avec un attribut browsingtopics. Chrome inclura alors 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 à l'aide de JavaScript et d'iFrames

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

Vous pouvez inclure un élément <iframe> dans le code HTML ou ajouter un iFrame de manière dynamique avec JavaScript. Pour créer un iFrame de manière 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 grâce à la détection de 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 depuis 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 les trois dernières semaines au maximum.

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 sujets actuellement utilisés par le navigateur.
  • topic: un numéro identifiant le thème dans la taxonomie.
  • version: chaîne combinant 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 retrieve()/XHR ou d'une requête iframe.

En-têtes de requête et de réponse pour définir et récupérer les 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 dans la réponse à la requête. Le navigateur s'appuie ensuite sur ces thèmes pour calculer ce qui intéresse l'utilisateur.

Si l'API renvoie un ou plusieurs thèmes, une requête d'extraction envoyée à l'eTLD+1 à partir duquel les sujets ont été observés inclut un en-tête Sec-Browsing-Topics semblable à celui-ci: 

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

Si l'API ne renvoie aucun thème, 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 à l'échelle d'un appelant en fonction de la longueur de l'en-tête.

Implémenter avec fetch()

Sur la page de l'éditeur, ajoutez votre code pour la demande d'extraction, 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 liste 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é sur un iFrame.

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

Dans ce cas, est l'appelant, comme pour 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 par le navigateur comme observés, mais aussi pour inclure la visite actuelle de la page dans le calcul du thème principal 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 backend de Topics

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

// 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 des thèmes en tant que données contextuelles

Les données sur les thèmes peuvent être considérées comme des signaux supplémentaires concernant votre audience, conjointement à d'autres signaux comme les URL, les mots clés et même les tags.

Comme expliqué dans Maximiser la pertinence des annonces après les cookies tiers, il existe plusieurs approches pour exploiter Topics afin de diffuser des annonces pertinentes. Certaines consistent à utiliser des thèmes pour créer des audiences, tandis que d'autres suggèrent d'utiliser Topics comme signal parmi d'autres pour entraîner des modèles de machine learning qui seront utilisés pour déterminer les centres d'intérêt supplémentaires de l'audience ou même pour optimiser la logique d'enchères.

Migration Build and Deploy

  1. Collecter des thèmes en observant les utilisateurs en production (pas encore ajusté) (durée estimée: environ une semaine)
    1. Comprendre les options disponibles: iFrame et JavaScript ou 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 "En-têtes".
    4. Déployez Topics dans votre environnement contrôlé (certains sites de production).
    5. Ajouter l'implémentation de Topics à certains sites cibles (pas plus de cinq sites pour le moment).
    6. Tests fonctionnels et validation.
  2. [Facultatif] Utiliser les données Topics comme signal de contexte (avec des URL, des balises, etc.) (Durée estimée: environ 3 jours).
    1. Après avoir reçu la liste des thèmes, vous pouvez l'envoyer à votre backend avec d'autres signaux de contexte.

Déployer sur des sites cibles

Maintenant que vous disposez du code, ajoutons-le à certains sites cibles pour effectuer un premier test et vérifier 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): commencez par déployer l'API auprès d'une petite audience.
  • Vous êtes propriétaire et contrôlez: si nécessaire, vous pouvez rapidement désactiver l'implémentation sans approbations complexes.
  • Ne sont pas essentiels pour l'activité: étant donné que cette implémentation peut perturber l'expérience utilisateur, commencez par les sites cibles à faible risque.
  • Pas plus de cinq sites au total: vous n'aurez pas besoin d'un trafic ni d'une exposition aussi importants pour l'instant.
  • Représentez différents thèmes: choisissez des sites Web qui représentent différentes catégories (par exemple, l'une sur le sport, l'autre sur l'actualité, l'autre sur l'alimentation et les boissons, etc.). Vous pouvez utiliser l'outil Topics interne de Chrome pour valider les domaines et leur classement 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 à:

  • Tableau vide de thèmes [] s'il s'agit du premier appel effectué sur cet appareil, pour ce site et l'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 cette semaine.
      • Remarque importante: si vous n'avez pas suffisamment de thèmes observés par vous pour qu'un utilisateur puisse calculer les cinq thèmes principaux de la semaine avec l'API Topics, Topics ajoutera autant de thèmes aléatoires que nécessaire pour obtenir le nombre total de cinq. En savoir plus sur l'API
  • Un nouveau sujet remplaçant l'un des trois si vous l'appelez après quatre semaines d'observation.
    • En effet, l'API Topics restera stable pendant les semaines suivantes, sans révéler trop d'intérêts des 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 votre expérience utilisateur.

  • La durée d'exécution des appels JavaScript à l'API Topics dans un iFrame multi-origine doit être mesurée pour être utilisée dans les analyses de performances futures. Veillez à collecter et à stocker correctement les données de télémétrie dans votre backend.
    • Le temps nécessaire pour créer un iFrame et postMessage() thèmes, après la réception des thèmes, est également une autre métrique à calculer.

Dépannage

J'appelle l'API Topics, mais je reçois un résultat nul. 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 votre code front-end pour vous assurer que votre code 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 sur les thèmes.

  4. Topics ne sera 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 les règles d'autorisation. 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é du passage à la production. Les étapes sont expliquées ci-dessous.

  1. Procéder au scaling de l'implémentation (en production) est décrit ci-dessous.
    1. Ajouter l'iFrame à plusieurs sites Web d'éditeurs
  2. Traiter et utiliser les données sur les thèmes (durée estimée: environ quatre semaines)
    1. Intégrez des données sur les thèmes en tant que signaux cumulatifs avec d'autres données.
    2. Trouver des partenaires de test des enchères en temps réel
    3. Exécutez des tests d'utilité avec des thèmes en tant que signal additif pour vos autres données.

Faire évoluer votre implémentation

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

Il est maintenant temps d'étendre cette implémentation en déployant le même code sur d'autres 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. Déployez-les progressivement sur vos sites, en particulier si le trafic est important.
  2. Effectuez des tests de charge pour vos données de thèmes, en fonction de votre trafic attendu.
    1. Vérifiez que votre backend peut gérer un grand nombre d'appels.
    2. Configurez la collecte de métriques et les journaux à des fins d'analyse.
  3. Juste après le déploiement de l'API Topics, vérifiez vos métriques pour détecter les problèmes graves des utilisateurs finaux. Continuez à vérifier 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 comprendre et résoudre le problème.

Interagir et partager des commentaires