Implémenter l'API Topics

Cette page explique les détails d'implémentation que les appelants de l'API Topics doivent respecter pour observer et accéder aux thèmes. Avant de commencer à implémenter votre solution, assurez-vous que votre navigateur est correctement configuré. Consultez la section "Présentation" pour en savoir plus sur la façon dont les appelants observent et accèdent aux thèmes des utilisateurs.

Observer et accéder aux thèmes

Il existe deux façons d'observer les thèmes d'un utilisateur et d'y accéder : les en-têtes HTTP et l'API JavaScript.

En-têtes HTTP

L'utilisation d'en-têtes HTTP est une approche recommandée pour observer et accéder aux thèmes utilisateur. Cette approche peut être beaucoup plus performante que l'utilisation de l'API JavaScript. Avec les en-têtes HTTP, l'URL de la requête fournit le domaine pouvant être enregistré qui est enregistré en tant que domaine de l'appelant. Il s'agit du domaine qui a observé les thèmes de l'utilisateur.

Lancer une demande

Il existe deux façons d'utiliser les thèmes avec des en-têtes :

• En accédant aux en-têtes de requête et de réponse sur une requête fetch() qui inclut une option browsingTopics: true.
• En accédant aux en-têtes d'un élément iframe qui inclut un attribut browsingtopics.

Lancer une requête avec une récupération

À l'aide de fetch, l'appelant de l'API envoie une requête qui inclut {browsingTopics: true} dans le paramètre d'options. Le paramètre d'URL de la requête de récupération est l'origine qui a été observée pour les thèmes.

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

Lancer une demande avec un iFrame

Ajoutez l'attribut browsingtopics à l'élément <iframe>. Le navigateur inclut l'en-tête Sec-Browsing-Topics dans la requête de l'iFrame, avec l'origine de l'iFrame comme appelant.

   <iframe src="https://adtech.example" browsingtopics></iframe>

Interpréter les valeurs des en-têtes de requête

Pour les deux approches (récupération et iframe), les thèmes observés pour un utilisateur peuvent être récupérés sur le serveur à partir de l'en-tête de requête Sec-Browsing-Topics. L'API Topics inclura automatiquement les thèmes utilisateur dans l'en-tête sur la requête fetch() ou iframe. Si l'API renvoie un ou plusieurs thèmes, une requête d'extraction vers l'origine à partir de laquelle les thèmes ont été observés inclura un en-tête Sec-Browsing-Topics comme 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 redirections seront suivies, et les thèmes envoyés dans la demande de redirection seront spécifiques à l'URL de redirection. Les valeurs d'en-tête Sec-Browsing-Topics sont complétées pour atténuer le risque qu'un pirate informatique découvre le nombre de thèmes associés à un appelant en fonction de la longueur de l'en-tête.

Gérer la réponse côté serveur

Si la réponse à la requête inclut un en-tête Observe-Browsing-Topics: ?1, cela indique que le navigateur doit marquer les thèmes de la requête associée comme observés et inclure la visite de la page actuelle dans le calcul des thèmes de la prochaine époque de l'utilisateur. Incluez l'en-tête Observe-Browsing-Topics: ?1 dans la réponse de votre code côté serveur :

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

Partager les thèmes observés avec des partenaires

Étant donné que les SSP ne sont présents que du côté de l'éditeur, les DSP peuvent souhaiter partager les thèmes qu'ils observent sur les sites des annonceurs avec leurs SSP partenaires. Pour ce faire, ils peuvent envoyer une requête fetch() avec l'en-tête "topics" aux SSP à partir du contexte de premier niveau de l'annonceur.

const response = await fetch("partner-ssp.example", {
 browsingTopics: true
});

Observer les thèmes et y accéder avec JavaScript

La méthode document.browsingTopics() de l'API Topics JavaScript permet à la fois d'observer et de récupérer les thèmes d'intérêt d'un utilisateur dans l'environnement du navigateur : - Enregistrer l'observation : informe le navigateur que l'appelant a observé l'utilisateur visitant la page actuelle. Cette observation contribue au calcul du thème de l'utilisateur pour l'appelant lors des prochaines epochs. - Accéder aux thèmes : récupère les thèmes que l'appelant a précédemment observés pour l'utilisateur. La méthode renvoie un tableau contenant jusqu'à trois objets de thème, un pour chacune des époques les plus récentes, dans un ordre aléatoire.

Nous vous recommandons de forker la démonstration de l'API Topics JavaScript et de l'utiliser comme point de départ pour votre code.

Disponibilité de l'API

Avant d'utiliser l'API, assurez-vous qu'elle est compatible et disponible :

 if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
    console.log('document.browsingTopics() is supported on this page');
 } else {
    console.log('document.browsingTopics() is not supported on this page');
 }

Intégrer un iFrame

Un iFrame d'origine croisée doit être utilisé pour l'appel, car le contexte à partir duquel l'API est appelée est utilisé pour s'assurer que le navigateur renvoie les thèmes appropriés à l'appelant. Incluez un élément <iframe> dans votre code HTML :

<iframe src="https://example.com" browsingtopics></iframe>

Vous pouvez également créer un iFrame de manière dynamique à l'aide de JavaScript :

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

Appeler l'API depuis l'iframe

 try {
   // Get the array of top topics for this user.
   const topics = await document.browsingTopics();
  
   // Request an ad creative, providing topics information.
   const response = await fetch('https://ads.example/get-creative', {
   method: 'POST',
   headers: {
    'Content-Type': 'application/json',
   },
   body: JSON.stringify(topics)
   })
  
   // Get the JSON from the response.
   const creative = await response.json();
  
   // Display ad.

 } catch (error) {
   // Handle error.
 }

Par défaut, la méthode document.browsingTopics() permet également au navigateur d'enregistrer la visite de la page actuelle telle qu'observée par l'appelant, afin qu'elle puisse être utilisée ultérieurement dans le calcul des thèmes. La méthode peut recevoir un argument facultatif pour empêcher l'enregistrement de la visite de la page : {skipObservation:true}.

 // current page won't be included in the calculation of topics:
 const topics = await document.browsingTopics({skipObservation:true});

Comprendre la réponse

Un maximum de trois thèmes sont renvoyés : un ou zéro pour chacune des trois dernières semaines, selon que des thèmes ont été observés ou non. Seuls les thèmes observés par l'appelant pour l'utilisateur actuel sont renvoyés. Voici un exemple de ce que l'API renvoie :

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]

• configVersion : chaîne identifiant la version de configuration de l'algorithme de thèmes du navigateur.
• modelVersion : chaîne identifiant le classificateur de machine learning utilisé pour déduire les thèmes.
• taxonomyVersion : chaîne identifiant l'ensemble de thèmes utilisés par le navigateur.
• topic : nombre identifiant le thème dans la taxonomie.
• version : chaîne concaténant configVersion, taxonomyVersion et modelVersion. Les paramètres décrits dans ce guide, ainsi que les détails de l'API (tels que la taille de la taxonomie, le nombre de thèmes calculés par semaine et le nombre de thèmes renvoyés par appel) sont susceptibles d'être modifiés à mesure que nous intégrons les commentaires de l'écosystème et que nous itérons sur l'API.

Consultez la page Tester et passer au mode production pour savoir à quelle réponse vous attendre et comment utiliser les thèmes comme signal supplémentaire pour diffuser des annonces plus pertinentes.

Étapes suivantes

Tester et mettre en ligne

Découvrez comment déployer, tester et faire évoluer des solutions basées sur Topics.

Outils

Découvrez les outils disponibles dans Chrome pour afficher des informations sur l'API Topics, comprendre comment les thèmes sont attribués et déboguer votre implémentation.

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.