Guide du développeur de l'API Topics

Découvrez comment utiliser l'API, y compris les indicateurs Chrome à des fins de test.

État de l'implémentation

Essayer la version de démonstration

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

Vous pouvez également exécuter le colab Topics pour tester le modèle de classificateur 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(). Cette approche a deux objectifs:

  • Demandez au navigateur d'enregistrer la visite en cours 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 qui ont été observés par l'appelant.

Cette méthode renvoie une promesse qui se résout dans 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 dans 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éterminer les thèmes du site (par exemple, 4)
  • taxonomyVersion: chaîne identifiant l'ensemble des thèmes utilisés par le navigateur, par exemple 2
  • topic: numéro identifiant le thème dans la taxonomie, par exemple 309
  • version: une 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 prenons en compte les commentaires de l'écosystème et itérez 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 sujets observés par l'appelant pour l'utilisateur actuel. Par défaut, la méthode oblige également le navigateur à enregistrer la visite en cours sur la page telle qu'elle est observée par l'appelant, afin de pouvoir l'utiliser ultérieurement dans le calcul des thèmes. À partir de Chrome 108, la méthode peut être transmise à 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 méthode n'inclut pas 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 sujets et marquer les visites de page comme observées à l'aide des en-têtes de requête et de réponse. L'approche de l'en-tête peut s'avérer beaucoup plus performante que d'appeler l'API JavaScript.

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

Si vous définissez un en-tête Observe-Browsing-Topics: ?1 sur la réponse à la requête, le navigateur enregistre la visite en cours de la page telle qu'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 des en-têtes HTTP de deux manières:

  • fetch(): ajoutez {browsingTopics: true} au paramètre d'options d'une requête fetch(). La démonstration de l'en-tête Topics en présente un exemple simplifié.
  • Attribut iFrame: ajoutez l'attribut browsingtopics à un élément <iframe> ou définissez la propriété JavaScript équivalente 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.

Quelques remarques supplémentaires sur les en-têtes:

  • Les redirections sont suivies et les sujets envoyés dans la demande de redirection sont 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 n'est pas enregistrée comme observée. Elle n'a donc aucune incidence sur le calcul du thème de l'utilisateur pour la prochaine epoch.
  • L'en-tête de réponse n'est respecté 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 la mise en œuvre de votre API

La page chrome://topics-internals sera disponible dans Chrome sur ordinateur une fois que vous aurez activé l'API Topics. Elle affiche les thèmes de l'utilisateur actuel, ceux déduits pour les noms d'hôte, ainsi que des informations techniques sur l'implémentation de l'API. Nous itérerons et améliorerons 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 des informations sur les thèmes observés pour leur navigateur à l'heure actuelle et à l'époque précédente en consultant chrome://topics-internals.

Page chrome://topics-internals avec le panneau &quot;Topics State&quot; (État des thèmes) sélectionné
Le panneau "État du sujet" de la page chrome://topics-internals affiche les ID des thèmes, 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. Ainsi, l'API Topics sélectionne Pets et Cats comme deux des principaux thèmes pour l'epoch actuelle. Les trois thèmes restants ont été choisis au hasard, car l'historique de navigation (sur les sites qui observent des thèmes) est insuffisant pour fournir cinq thèmes.

La colonne Domaines de contexte observés (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.

Page chrome://topics-internals avec le panneau de classification sélectionné.
Le panneau de classificateur de la page chrome://topics-internals affiche les thèmes sélectionnés, les hôtes consultés, ainsi que la version et le chemin d'accès du modèle.

La mise en œuvre actuelle de l'API Topics déduit les thèmes à partir des noms d'hôte uniquement, et non des autres parties d'une URL.

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

Afficher les informations sur 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 à partir de la ligne de commande. Cela peut être utile pour vérifier que les indicateurs de ligne de commande ont fonctionné 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).

Page chrome://topics-internals avec le panneau &quot;Fonctionnalités et paramètres&quot; sélectionné
Le panneau "Fonctionnalités et paramètres" de chrome://topics-internals affiche les fonctionnalités activées, la durée 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 affichés dans la capture d'écran correspondent aux indicateurs que vous pouvez définir lorsque vous exécutez Chrome à partir de la ligne de commande. Par exemple, la démonstration sur 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 sa fonction.

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ée
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 activer les fonctionnalités de la Privacy Sandbox.

BrowsingTopicsBypassIPIsPubliclyRoutableCheck
Valeur par défaut:désactivée
Si cette option est activée, la vérification de l'état routable publiquement de l'adresse IP sera ignorée lors de la détermination de l'éligibilité d'une page à inclure dans le calcul des thèmes.

BrowsingTopics:number_of_epochs_to_expose
Valeur par défaut:3
Nombre d'époques à partir duquel calculer les thèmes à attribuer à un contexte de demande. 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 epoch. Pour le débogage, il peut être utile de définir cette valeur 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 dans une epoch soit renvoyé de manière aléatoire à partir de l'ensemble de la taxonomie des thèmes. Le caractère aléatoire dépend d'une époque et d'un site.

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

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

BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
Valeur par défaut: 100 000
Nombre maximal d'entrées pouvant être extraites de la base de données pour chaque requête dans les contextes d'utilisation de l'API. La requête sera exécutée une fois par epoch au moment du calcul des thèmes. L'objectif est de limiter les pics d'utilisation 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é qu'à un seul ensemble de configuration. La mise à jour des paramètres de configuration sans mettre à jour config_version devrait généralement convenir aux tests en local. Toutefois, dans certains cas, le navigateur pourrait rester dans un état incohérent et entraîner un plantage du navigateur, par exemple lors de la mise à jour de number_of_top_topics_per_epoch.

BrowsingTopics:taxonomy_version
Valeur par défaut:1
Version de 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: browsing-topics=() Permissions-Policy 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'affectera pas les autres pages.

Vous pouvez également contrôler l'accès des tiers aux sujets de votre page à l'aide de l'en-tête Permissions-Policy. Utilisez self et tous les domaines pour lesquels vous souhaitez autoriser l'accès à l'API comme paramètres de l'en-tête. 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