Guide du développeur de l'API Topics

Découvrez comment utiliser l'API, y compris les indicateurs Chrome pour les tests.

État de l'implémentation

Essayer la démo

Deux démonstrations de l'API Topics vous permettent d'essayer Topics en tant qu'utilisateur individuel.

Vous pouvez également exécuter le colab Topics pour tester le modèle de classificateur de Topics.

Utiliser l'API JavaScript pour accéder aux sujets et les enregistrer comme observés

L'API Topics JavaScript comporte une méthode: document.browsingTopics(). Elle a deux objectifs:

  • Demandez au navigateur d'enregistrer la visite actuelle de la page comme ayant été observée pour l'appelant, afin de pouvoir l'utiliser ultérieurement pour calculer les thèmes de l'utilisateur (pour l'appelant).
  • Accédez aux sujets de l'utilisateur observés par l'appelant.

La méthode renvoie une promesse qui renvoie vers un tableau comportant jusqu'à trois thèmes, un pour chacune des trois epochs les plus récentes, dans un ordre aléatoire. Une epoch est une période définie sur une semaine dans l'implémentation de Chrome.

Chaque objet "topic" du tableau renvoyé par document.browsingTopics() possède les propriétés suivantes:

  • configVersion: chaîne identifiant la configuration actuelle de l'API Topics, par exemple chrome.2
  • modelVersion: chaîne identifiant le classificateur de machine learning utilisé pour déduire les thèmes du site (par exemple, 4)
  • taxonomyVersion: chaîne identifiant l'ensemble des sujets utilisés par le navigateur, par exemple 2
  • topic: numéro identifiant le thème dans la taxonomie, par exemple 309
  • version: chaîne concaténant configVersion, taxonomyVersion et modelVersion, par exemple chrome.2:2:4

Les paramètres décrits dans ce guide et 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 optimisons l'API.

Détecter la prise en charge de document.browsingTopics

Avant d'utiliser l'API, vérifiez si elle est compatible avec le navigateur et si elle est disponible dans le document:

'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');

Accéder aux sujets avec l'API JavaScript

Voici un exemple basique d'utilisation possible de l'API pour accéder aux sujets de l'utilisateur actuel.

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.
}

Accéder aux sujets sans modifier l'état

document.browsingTopics() renvoie les thèmes observés par l'appelant pour l'utilisateur actuel. Par défaut, avec cette méthode, le navigateur enregistre également la visite actuelle de la page telle qu'elle est observée par l'appelant. Elle peut ainsi être utilisée ultérieurement dans le calcul des thèmes. À partir de Chrome 108, la méthode peut transmettre un argument facultatif pour empêcher l'enregistrement de la visite de la page: {skipObservation:true}.

En d'autres termes, {skipObservation:true} signifie que l'appel de la méthode n'entraîne pas l'inclusion de la page actuelle dans le calcul des thèmes.

Utiliser des en-têtes pour accéder aux sujets et les marquer comme observés

Vous pouvez accéder aux thèmes et marquer les visites de pages comme observées à l'aide de request et response.

L'utilisation de l'en-tête peut être beaucoup plus performante que l'utilisation de l'API JavaScript, car l'API nécessite de créer un iFrame multi-origine et d'effectuer un appel document.browsingTopics() à partir de celui-ci. (Un iFrame multi-origine doit être utilisé pour l'appel, car le contexte à partir duquel l'API est appelée permet de s'assurer que le navigateur renvoie les thèmes appropriés à l'appelant.) L'explication de Topics propose une discussion plus détaillée: Y a-t-il un moyen d'envoyer des thèmes en utilisant Fetch comme en-tête de requête ? .

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

Définir un en-tête Observe-Browsing-Topics: ?1 dans la réponse à la requête le navigateur enregistre la page consultée en cours, telle qu'elle est observée par l'appelant ; afin de pouvoir l'utiliser ultérieurement dans le calcul des thèmes.

Il est possible d'accéder aux sujets et de les observer avec les en-têtes HTTP de deux manières:

  • fetch(): ajoutez {browsingTopics: true} au paramètre "options" d'une requête fetch(). La démonstration de l'en-tête Topics en illustre un exemple simplifié.
  • Attribut iFrame: ajoutez l'attribut browsingtopics à un élément <iframe> ou définissez le code JavaScript équivalent iframe.browsingTopics = true. Le domaine enregistrable de la source iFrame est le domaine de l'appelant: par exemple, pour <iframe src="https://example.com" browsingtopics></iframe>: l'appelant est example.com.

Remarques supplémentaires concernant les en-têtes:

  • Les redirections seront suivies et les sujets envoyés dans la demande de redirection seront spécifiques à l'URL de redirection.
  • L'en-tête de requête ne modifie pas l'état de l'appelant, sauf s'il existe un en-tête de réponse correspondant. Autrement dit, sans l'en-tête de réponse, la visite de la page ne sera pas enregistrée comme observée et n'aura donc pas d'incidence sur le calcul du thème de l'utilisateur pour la prochaine epoch.
  • L'en-tête de réponse n'est traité que si la requête correspondante inclut l'en-tête "topics".
  • L'URL de la requête fournit le domaine enregistrable qui est enregistré en tant que domaine de l'appelant.

Déboguer l'implémentation de votre API

La page chrome://topics-internals est disponible dans Chrome sur ordinateur une fois que vous avez activé l'API Topics. Les sujets concernant l'utilisateur actuel, les thèmes déduits pour les noms d'hôte et les informations techniques sur la mise en œuvre de l'API s'affichent. Nous itérerons et améliorons la conception de la page en fonction des commentaires des développeurs: ajoutez vos commentaires sur bugs.chromium.org.

Afficher les thèmes calculés pour votre navigateur

Les utilisateurs peuvent consulter les informations sur les thèmes observés dans leur navigateur pendant la période actuelle et la période précédente en accédant à chrome://topics-internals.

<ph type="x-smartling-placeholder">
</ph> Page chrome://topics-internals avec le panneau d&#39;état des sujets sélectionné.
Le panneau "État des sujets" de la page chrome://topics-internals affiche les ID des sujets, les attributions de thèmes aléatoires et réelles, ainsi que les versions de taxonomie et de modèle.

Cette capture d'écran montre que les sites récemment consultés incluent topics-demo-cats.glitch.me et cats-cats-cats-cats.glitch.me. L'API Topics sélectionne donc Pets et Cats comme deux des thèmes principaux pour la epoch en cours. Les trois autres thèmes ont été choisis au hasard, car l'historique de navigation est insuffisant (sur les sites qui observent des thèmes) pour en indiquer cinq.

La colonne Domaines de contexte observés par les domaines (hachés) indique la valeur hachée d'un nom d'hôte pour lequel un sujet a été observé.

Afficher les sujets déduits pour les noms d'hôte

Vous pouvez également afficher les thèmes déduits par le modèle de classificateur Topics pour un ou plusieurs noms d'hôte dans chrome://topics-internals.

<ph type="x-smartling-placeholder">
</ph> Page chrome://topics-internals avec le panneau &quot;Classificateur&quot; sélectionné
Le panneau "Outil de classification" de la page chrome://topics-internals affiche les thèmes sélectionnés, les hôtes consultés, la version du modèle et le chemin d'accès.

Dans l'implémentation actuelle de l'API Topics, les thèmes ne sont déduits qu'à partir des noms d'hôte. et non à partir d'une autre partie d'une URL.

Utilisez uniquement des noms d'hôte (sans protocole ni chemin d'accès) pour afficher les sujets déduits à partir du classificateur chrome://topics-internals. chrome://topics-internals affichera une erreur si vous tentez d'inclure "/" dans le champ "Host".

Afficher les informations concernant l'API Topics

Vous trouverez des informations sur l'implémentation et les paramètres de l'API Topics, tels que la version de la taxonomie et la durée de l'epoch, dans chrome://topics-internals. Ces valeurs reflètent les paramètres par défaut de l'API ou ceux définis avec succès à partir de la ligne de commande. Cela peut être utile pour confirmer que les indicateurs de ligne de commande fonctionnent comme prévu.

Dans cet exemple, time_period_per_epoch a été défini sur 15 secondes (la valeur par défaut est de sept jours).

<ph type="x-smartling-placeholder">
</ph> Page chrome://topics-internals avec le panneau &quot;Features and Parameters&quot; (Fonctionnalités et paramètres) sélectionné
Le panneau chrome://topics-internals "Fonctionnalités et paramètres" affiche les fonctionnalités activées, le temps par epoch, le nombre d'époques à utiliser pour calculer les thèmes, la version de la taxonomie et d'autres paramètres.

Les paramètres présentés dans la capture d'écran correspondent aux indicateurs pouvant être définis lorsque vous exécutez Chrome à partir de la ligne de commande. Par exemple, la démo disponible à l'adresse topics-fetch-demo.glitch.me recommande d'utiliser les indicateurs suivants:

--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting

La liste suivante décrit chaque paramètre, sa valeur par défaut et son rôle.

Indicateurs Chrome

BrowsingTopics
Valeur par défaut:activé
Indique si l'API Topics est activée.

PrivacySandboxAdsAPIsOverride
Valeur par défaut:activé
Active les API Ads: Attribution Reporting, Protected Audience, Topics et Fenced Frames.

PrivacySandboxSettings4
Valeur par défaut:désactivé
Active la quatrième version des paramètres de l'interface utilisateur de la Privacy Sandbox.

OverridePrivacySandboxSettingsLocalTesting
Valeur par défaut:activé
Si cette option est activée, le navigateur n'a plus besoin d'activer les paramètres sous-jacents pour les fonctionnalités de la Privacy Sandbox.

BrowsingTopicsBypassIPIsPubliclyRoutableCheck
Valeur par défaut:désactivé
Si cette option est activée, le système vérifie si l'adresse IP est routable publiquement ignoré lors de la détermination de l'éligibilité d'une page à être incluse dans les thèmes calcul.

BrowsingTopics:number_of_epochs_to_expose
Valeur par défaut:3
Nombre d'époques à partir desquelles calculer les thèmes à attribuer à une requête le contexte. Le navigateur conserve en interne jusqu'à N+1 époques.

BrowsingTopics:time_period_per_epoch
Valeur par défaut:7d-0h-0m-0s
Durée de chaque époque. Pour le débogage, il peut être utile de définir cette durée sur 15 secondes, par exemple, au lieu des sept jours par défaut.

BrowsingTopics:number_of_top_topics_per_epoch
Valeur par défaut:5
Nombre de thèmes calculés par epoch.

BrowsingTopics:use_random_topic_probability_percent
Valeur par défaut:5
Probabilité qu'un thème individuel d'une époque soit renvoyé de manière aléatoire toute la taxonomie de sujets. Le caractère aléatoire est persistant par rapport à une époque et à un site.

BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
Valeur par défaut:3
Pendant combien d'époques les données d'utilisation de l'API (c'est-à-dire les observations par thèmes) seront utilisées filtrer les sujets pour un contexte d'appel.

BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
Valeur par défaut:1000
Nombre maximal de domaines observés par contexte à conserver pour chaque thème principal. L'intention consiste à limiter la mémoire en cours d'utilisation.

BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
Valeur par défaut:100000
Nombre maximal d'entrées pouvant être récupérées dans la base de données pour chaque requête pour les contextes d'utilisation de l'API. La requête sera exécutée une fois par epoch lors du calcul des thèmes en temps réel. L'objectif est de limiter l'utilisation maximale de la mémoire.

BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
Valeur par défaut:30
Nombre maximal de domaines de contexte d'utilisation de l'API pouvant être stockés par chargement de page.

BrowsingTopics:config_version
Valeur par défaut:1
Encode les paramètres de configuration de l'API Topics. Chaque numéro de version ne doit être mappés à un ensemble de configuration. Mettre à jour les paramètres de configuration sans mettre à jour le config_version doit est généralement adaptée aux tests en local, mais peut parfois laisser le navigateur dans un un état incohérent et peut entraîner le plantage du navigateur, par exemple la mise à jour number_of_top_topics_per_epoch

BrowsingTopics:taxonomy_version
Valeur par défaut:1
La taxonomie utilisée par l'API.

Désactiver votre site

Vous pouvez désactiver le calcul des thèmes pour des pages spécifiques de votre site en incluant l'en-tête Permissions-Policy Permissions-Policy: browsing-topics=() sur une page afin d'empêcher le calcul des thèmes pour tous les utilisateurs de cette page uniquement. Les visites ultérieures sur d'autres pages de votre site ne seront pas affectées: si vous définissez une règle pour bloquer l'API Topics sur une page, cela n'aura aucune incidence sur les autres pages.

Vous pouvez également contrôler l'accès des tiers à l'API Topics à l'aide de l'en-tête Permissions-Policy. En tant que paramètres de l'en-tête, utilisez self et tous les domaines pour lesquels vous souhaitez autoriser l'accès à l'API. Par exemple, pour désactiver complètement l'utilisation de l'API Topics dans tous les contextes de navigation, à l'exception de votre propre origine et de https://example.com, définissez l'en-tête de réponse HTTP suivant:

Permissions-Policy: browsing-topics=(self "https://example.com")

Étapes suivantes

En savoir plus

Interagir et partager des commentaires