Découvrez comment utiliser l'API, y compris les indicateurs Chrome pour les tests.
État de l'implémentation
- L'API Topics a terminé la phase de discussion publique et est actuellement disponible pour 99 % des utilisateurs (jusqu'à 100 %).
- Pour donner votre avis sur l'API Topics, créez un problème dans l'article d'explication de Topics ou participez aux discussions du groupe pour l'amélioration de la publicité sur le Web. L’explication a un certain nombre de questions ouvertes qui nécessitent encore une définition plus approfondie.
- Le calendrier de la Privacy Sandbox indique les délais d'implémentation de l'API Topics et d'autres propositions de la Privacy Sandbox.
- L'article API Topics: dernières mises à jour décrit les modifications et améliorations apportées à l'API Topics et aux implémentations.
Essayer la démo
Deux démonstrations de l'API Topics vous permettent d'essayer Topics en tant qu'utilisateur individuel.
- Démonstration de l'API JavaScript: topics-demo.glitch.me
- Démonstration de l'en-tête: topics-fetch-demo.glitch.me
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 exemplechrome.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 exemple2
topic
: numéro identifiant le thème dans la taxonomie, par exemple309
version
: chaîne concaténantconfigVersion
,taxonomyVersion
etmodelVersion
, par exemplechrome.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êtefetch()
. 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 équivalentiframe.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 estexample.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
.
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
.
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).
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 à journumber_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 sur les thèmes et leur fonctionnement
- Essayez la démonstration.
En savoir plus
Interagir et partager des commentaires
- GitHub: consultez l'explication sur l'API Topics, posez des questions et suivez les discussions concernant les problèmes liés au dépôt d'API.
- W3C: discutez de cas d'utilisation sectoriels dans le groupe Améliorer la publicité sur le Web.
- Annonces: rejoignez ou consultez la liste de diffusion.
- Assistance pour les développeurs de la Privacy Sandbox: posez des questions et participez à des discussions sur le dépôt de l'assistance pour les développeurs Privacy Sandbox.
- Chromium: signalez un bug Chromium pour poser des questions sur l'implémentation actuellement disponible à tester dans Chrome.