Découvrez comment utiliser l'API, y compris les indicateurs Chrome à des fins de test.
É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 unique.
- 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 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 exemplechrome.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 exemple2
topic
: numéro identifiant le thème dans la taxonomie, par exemple309
version
: une 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 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 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 sujets appropriés à l'appelant.) L'explication de Topics aborde plus en détail la question suivante: Est-il possible d'envoyer des sujets en utilisant Fetch comme en-tête de requête ?
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êtefetch()
. 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 équivalenteiframe.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
.
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
.
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
.
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).
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 denumber_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 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.