API Protected Audience: guide du développeur

Guide du développeur pour les enchères publicitaires sur l'appareil afin de diffuser des annonces de remarketing et des audiences personnalisées, sans suivi tiers multisite.

Si vous ne connaissez pas l'API Protected Audience, consultez la présentation de l'API Protected Audience pour obtenir une explication générale de l'API.

Cet article s'adresse aux développeurs et sert de référence technique pour la dernière itération de l'API Protected Audience expérimentale. Une démonstration d'un déploiement de base de l'API Protected Audience est disponible, tout comme les documents de référence de l'API pour les acheteurs et les vendeurs d'annonces.

État de l'implémentation

Pour être informé des changements d'état dans l'API, rejoignez la liste de diffusion pour les développeurs.

Qu'est-ce que l'API Protected Audience ?

L'API Protected Audience est une API �Privacy Sandbox conçue pour les cas d'utilisation du remarketing et des audiences personnalisées. Elle est conçue pour que les tiers ne puissent pas l'utiliser pour suivre le comportement de navigation des utilisateurs sur les sites. L'API permet au navigateur d'organiser des enchères sur l'appareil pour choisir des annonces pertinentes pour les sites Web que l'utilisateur a déjà consultés.

L'API Protected Audience est la première expérience à être implémentée dans Chromium au sein de la famille de propositions TURTLEDOVE.

Essayer l'API Protected Audience

Documentation de référence de l'API disponible

Ce document présente l'API Protected Audience. Si vous recherchez des méthodes et des paramètres d'API spécifiques :

Vous pouvez également consulter les Bonnes pratiques concernant la latence des enchères d'annonces de l'API Protected Audience.

Démonstration de l'API Protected Audience

Un tutoriel sur le déploiement de base de l'API Protected Audience sur les sites d'annonceurs et d'éditeurs est disponible sur protected-audience-demo.web.app/.

Regardez ce déploiement de bout en bout pour découvrir comment fonctionne le code de démonstration de l'API Protected Audience et comment utiliser les outils pour les développeurs Chrome pour le débogage.

Tester cette API

Vous pouvez tester l'API Protected Audience pour un seul utilisateur dans Chrome bêta 101.0.4951.26 et versions ultérieures sur ordinateur :

Afficher des annonces dans des iFrames ou des frames cloisonnés

Les annonces peuvent être affichées dans un <iframe> ou un <fencedframe>, selon les indicateurs définis.

Pour utiliser <fencedframe> pour afficher des annonces :

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

Pour utiliser <iframe> pour afficher des annonces :

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

Incluez l'indicateur BiddingAndScoringDebugReportingAPI pour activer les méthodes temporaires de signalement des pertes/gains de débogage.

Fonctionnalités compatibles

L'API Protected Audience derrière les flags de fonctionnalité dans Chromium est une première expérience permettant de tester les fonctionnalités suivantes de l'API Protected Audience :

  • Groupes d'intérêt : stockés par le navigateur, avec des métadonnées associées pour configurer les enchères et le rendu des annonces.
  • Enchères sur l'appareil par les acheteurs (DSP ou annonceur) : basées sur les groupes d'intérêt et les signaux stockés du vendeur.
  • Sélection d'annonces sur l'appareil par le vendeur (SSP ou éditeur) : basée sur les offres d'enchères et les métadonnées des acheteurs.
  • Rendu des annonces dans une version temporairement assouplie des cadres clôturés : l'accès au réseau et la journalisation sont autorisés pour le rendu des annonces.

Pour en savoir plus sur les fonctionnalités et les contraintes, consultez la présentation de l'API Protected Audience.

Autorisations des groupes d'intérêt

L'implémentation actuelle de l'API Protected Audience permet par défaut d'appeler joinAdInterestGroup() depuis n'importe quel endroit d'une page, même depuis des iFrames multidomaines.

À l'avenir, une fois que les propriétaires de sites auront eu le temps de mettre à jour leurs stratégies d'autorisation pour les iFrames interdomaines, nous prévoyons d'interdire les appels depuis les iFrames interdomaines.

Service clé-valeur

Pour prendre en charge les enchères publicitaires de l'API Protected Audience, le navigateur peut accéder à un service clé/valeur pour récupérer des informations en temps réel qui prennent en charge les enchères publicitaires de l'API Protected Audience. Ces informations peuvent être utilisées de différentes manières :

  • Les acheteurs peuvent souhaiter calculer le budget restant d'une campagne publicitaire.
  • Les vendeurs peuvent être tenus de vérifier que les créations publicitaires respectent les règles des éditeurs.

Le code de service clé/valeur de l'API Protected Audience est désormais disponible. Pour connaître l'état de la fonctionnalité, consultez l'article de blog à ce sujet.

Pour les tests initiaux, un modèle Bring Your Own Server a été introduit. À long terme, les technologies publicitaires devront utiliser les services clé/valeur de l'API Protected Audience Open Source s'exécutant dans des environnements d'exécution sécurisés.

Consultez l'article de blog sur les services de l'API Protected Audience pour connaître les dernières informations sur le calendrier. Nous vous avertirons suffisamment à l'avance pour que vous puissiez commencer à tester et à adopter cette transition.

Compatibilité avec la fonctionnalité Détecter

Avant d'utiliser l'API, vérifiez si elle est prise en charge par le navigateur et disponible dans le document :

'joinAdInterestGroup' in navigator &&
  document.featurePolicy.allowsFeature('join-ad-interest-group') &&
  document.featurePolicy.allowsFeature('run-ad-auction') ?
  console.log('navigator.joinAdInterestGroup() is supported on this page') :
  console.log('navigator.joinAdInterestGroup() is not supported on this page');

Comment fonctionne l'API Protected Audience ?

Dans cet exemple, un utilisateur parcourt le site Web d'un fabricant de vélos personnalisés, puis visite un site d'actualités et voit une annonce pour un nouveau vélo du fabricant.

Les fonctionnalités de l'API Protected Audience seront ajoutées au fil du temps à mesure que l'implémentation progressera.

1. Un utilisateur consulte le site d'un annonceur.

Une personne consulte le site d&#39;un fabricant de vélos personnalisés dans un navigateur sur son ordinateur portable.

Imaginez qu'un utilisateur visite le site Web d'un fabricant de vélos personnalisés (l'annonceur dans cet exemple) et passe du temps sur la page produit d'un vélo en acier fait main. Cela permet au fabricant de vélos de faire du remarketing.

2. Le navigateur de l'utilisateur est invité à ajouter un groupe d'intérêt.

Un utilisateur ouvre un navigateur sur son ordinateur portable et consulte un site. Le code JavaScript permettant de rejoindre des groupes d&#39;intérêt publicitaire s&#39;exécute dans le navigateur.

La plate-forme côté demande (DSP, demand-side platform) de l'annonceur (ou l'annonceur lui-même) appelle navigator.joinAdInterestGroup() pour demander au navigateur d'ajouter un groupe d'intérêt à la liste des groupes dont le navigateur est membre.

Dans cet exemple, le groupe est nommé custom-bikes et le propriétaire est dsp.example. Le propriétaire du groupe d'intérêt (dans ce cas, la DSP) sera un acheteur lors des enchères publicitaires de l'API Protected Audience. L'appartenance à un groupe d'intérêt est stockée par le navigateur sur l'appareil de l'utilisateur, et n'est pas partagée avec le fournisseur du navigateur ni avec qui que ce soit d'autre.

Spécifier des annonces pour un groupe d'intérêt

Les objets ads et adComponents incluent l'URL d'une création publicitaire et, éventuellement, des métadonnées arbitraires pouvant être utilisées au moment des enchères. Exemple :

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

Comment les acheteurs font-ils des offres ?

generateBid() est appelé pour chaque groupe d'intérêt dont le navigateur est membre, si le propriétaire du groupe d'intérêt est invité à enchérir.

Consultez la documentation pour les développeurs generatedBid().

3. L'utilisateur consulte un site qui vend des espaces publicitaires.

Une personne consulte un site Web d&#39;actualités dans un navigateur sur son ordinateur portable. Le site comporte un emplacement publicitaire vide.

Plus tard, l'utilisateur visite un site qui vend des espaces publicitaires (un site d'actualités, par exemple). Le site dispose d'un inventaire publicitaire qu'il vend de manière programmatique avec des enchères en temps réel.

4. Une mise aux enchères d'annonces est exécutée dans le navigateur.

Une personne consulte un site Web d&#39;actualités dans un navigateur sur son ordinateur portable. Une enchère publicitaire de l&#39;API Protected Audience est organisée pour sélectionner une annonce pour l&#39;espace publicitaire disponible.

L'enchère publicitaire est susceptible d'être organisée par le fournisseur côté offre (SSP) de l'éditeur ou par l'éditeur lui-même. L'objectif de la mise aux enchères est de sélectionner l'annonce la plus appropriée pour un seul espace publicitaire disponible sur la page actuelle. L'enchère tient compte des groupes d'intérêt auxquels le navigateur appartient, ainsi que des données des acheteurs d'espaces publicitaires et des vendeurs des services clé/valeur.

5. Le vendeur et les acheteurs participants demandent des données en temps réel au service clés/valeurs.

L&#39;utilisateur consulte un site d&#39;actualités dans un navigateur sur son ordinateur portable. Une enchère publicitaire utilisant l&#39;API Protected Audience a lieu, et un participant obtient des données du service de clés/valeurs.

Lors d'une vente aux enchères d'annonces, le vendeur peut demander des données en temps réel sur des créations publicitaires spécifiques en envoyant une requête à son service de clés/valeurs. Le vendeur peut demander ces informations pendant runAdAuction() à l'aide de la propriété trustedScoringSignalsUrl, ainsi que les clés des propriétés renderUrl de toutes les entrées des champs ads et adComponents de tous les groupes d'intérêt de l'enchère.

Un acheteur peut demander des données en temps réel à son service de clé/valeur à l'aide des propriétés trustedBiddingSignalsUrl et trustedBiddingSignalsKeys de l'argument de groupe d'intérêt transmis à navigator.joinAdInterestGroup().

Lorsque runAdAuction() est appelé, le navigateur envoie une requête au serveur de confiance de chaque acheteur d'annonces. L'URL de la requête peut se présenter comme suit :

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
  • L'URL de base provient de trustedBiddingSignalsUrl.
  • Le hostname est fourni par le navigateur.
  • La valeur keys est extraite de trustedBiddingSignalsKeys.

La réponse à cette requête est un objet JSON fournissant des valeurs pour chacune des clés.

6. L'annonce gagnante est diffusée.

Une personne consulte un site Web d&#39;actualités dans un navigateur sur son ordinateur portable. Une annonce pour un vélo avec 20 % de remise s&#39;affiche dans un frame sécurisé.

La promesse renvoyée par runAdAuction() est résolue en un objet de configuration de frame clôturé (FencedFrameConfig) lorsque l'indicateur resolveToConfig est défini sur true dans la configuration de l'enchère. La configuration du frame est utilisée par un frame clôturé pour accéder à l'annonce gagnante, mais l'URL de l'annonce n'est pas visible par l'intégrateur du frame.

L'objet de configuration du cadre clôturé est disponible à partir de M114. Pour en savoir plus sur l'objet FencedFrameConfig, consultez l'article du blog Chrome.

7. Le résultat des enchères est indiqué

L'objectif à long terme est de permettre au navigateur de communiquer les résultats des enchères pour le vendeur et les acheteurs à l'aide des API Private Aggregation.

En tant que mécanisme temporaire de création de rapports au niveau des événements, le code implémentant reportResult() pour le vendeur et reportWin() pour l'enchérisseur gagnant peut appeler la fonction sendReportTo(). Cette fonction prend un seul argument : une chaîne représentant une URL récupérée une fois l'enchère terminée, qui encode les informations au niveau de l'événement à signaler.

8. Un clic sur une annonce est enregistré

Un utilisateur clique sur une annonce pour un vélo, intégrée dans un frame cloisonné, sur un site Web d&#39;actualités. Les données du rapport sont envoyées aux vendeurs et aux acheteurs.

Un clic sur une annonce affichée dans un cadre clôturé est signalé. Pour en savoir plus sur le fonctionnement de cette fonctionnalité, consultez Rapports sur les annonces dans des cadres clôturés.

Présentation de chaque étape d&#39;une enchère d&#39;annonce de l&#39;API Protected Audience
Ce schéma décrit chaque étape d'une enchère de l'API Protected Audience.

Quelle est la différence entre l'API Protected Audience et TURTLEDOVE ?

L'API Protected Audience est la première expérience à être implémentée dans Chromium au sein de la famille de propositions TURTLEDOVE.

L'API Protected Audience suit les principes généraux de TURTLEDOVE. Certaines publicités en ligne sont basées sur la diffusion d'une annonce auprès d'une personne potentiellement intéressée qui a déjà interagi avec l'annonceur ou le réseau publicitaire. Historiquement, cela fonctionnait en permettant à l'annonceur de reconnaître une personne spécifique lorsqu'elle naviguait sur des sites Web, ce qui constitue un problème de confidentialité majeur sur le Web actuel.

L'objectif de TURTLEDOVE est de proposer une nouvelle API pour répondre à ce cas d'utilisation tout en offrant des avancées clés en matière de confidentialité :

  • C'est le navigateur, et non l'annonceur, qui détient les informations sur ce qui intéresse une personne.
  • Les annonceurs peuvent diffuser des annonces en fonction d'un intérêt, mais ne peuvent pas combiner cet intérêt avec d'autres informations sur une personne, en particulier son identité ou la page qu'elle visite.

L'API Protected Audience est issue de TURTLEDOVE et d'un ensemble de propositions de modifications associées visant à mieux servir les développeurs qui utiliseraient l'API :

  • Dans SPARROW : Criteo a proposé d'ajouter un modèle de service ("Gatekeeper") s'exécutant dans un environnement d'exécution sécurisé (TEE). L'API Protected Audience inclut une utilisation plus limitée des TEE, pour la recherche de données en temps réel et les rapports agrégés.
  • Les propositions TERN de NextRoll et PARRROT de Magnite décrivaient les différents rôles des acheteurs et des vendeurs dans l'enchère sur l'appareil. Le flux d'enchères/de scoring d'annonces de l'API Protected Audience est basé sur ce travail.
  • Les modifications basées sur les résultats et au niveau des produits de TURTLEDOVE par RTB House ont amélioré le modèle d'anonymat et les capacités de personnalisation des enchères sur l'appareil.
  • PARAKEET est la proposition de Microsoft pour un service publicitaire de type TURTLEDOVE qui s'appuie sur un serveur proxy exécuté dans un TEE entre le navigateur et les fournisseurs de technologies publicitaires, afin d'anonymiser les demandes d'annonces et d'appliquer les propriétés de confidentialité. L'API Protected Audience n'a pas adopté ce modèle de proxy. Nous harmonisons les API JavaScript pour PARAKEET et l'API Protected Audience afin de pouvoir combiner les meilleures fonctionnalités des deux propositions à l'avenir.

L'API Protected Audience n'empêche pas encore le réseau publicitaire d'un site Web de savoir quelles annonces une personne voit. Nous prévoyons de modifier l'API pour la rendre plus privée au fil du temps.

L'API Topics peut-elle être utilisée avec l'API Protected Audience ?

Oui. Un thème observé pour l'utilisateur actuel, fourni par l'API Topics, peut être utilisé comme information contextuelle par un vendeur ou un enchérisseur. Un thème peut être inclus dans les propriétés suivantes :

  • auctionSignals, propriété de l'objet de configuration des enchères transmis à navigator.runAdAuction()
  • userBiddingSignals, propriété de l'objet de configuration du groupe d'intérêt transmis à navigator.joinAdInterestGroup()

Configuration du navigateur disponible

Les utilisateurs peuvent ajuster leur participation aux tests Privacy Sandbox dans Chrome en activant ou en désactivant le paramètre de premier niveau dans chrome://settings/adPrivacy.

Lors des tests initiaux, les utilisateurs pourront utiliser ce paramètre Privacy Sandbox de haut niveau pour désactiver l'API Protected Audience. Chrome prévoit de permettre aux utilisateurs de consulter et de gérer la liste des groupes d'intérêt auxquels ils ont été ajoutés sur les sites Web qu'ils ont consultés. Comme pour les technologies Privacy Sandbox elles-mêmes, les paramètres utilisateur peuvent évoluer en fonction des commentaires des utilisateurs, des organismes de réglementation et d'autres parties prenantes.

Nous continuerons à mettre à jour les paramètres disponibles dans Chrome en fonction des tests et des commentaires. À l'avenir, nous prévoyons de proposer des paramètres plus précis pour gérer l'API Protected Audience et les données associées.

Les appelants d'API ne peuvent pas accéder à l'appartenance à un groupe lorsque les utilisateurs naviguent en mode navigation privée. L'appartenance est supprimée lorsque les utilisateurs effacent les données de leur site.

Les worklets Protected Audience sont-ils mis en cache par le navigateur ?

Les ressources contenant les worklets Protected Audience (worklets de génération d'enchères et de création de rapports de l'acheteur, et worklets de notation et de création de rapports d'annonces du vendeur) sont mises en cache par le navigateur. Vous pouvez utiliser l'en-tête Cache-Control pour contrôler le comportement de mise en cache.

Interagir et envoyer des commentaires

Obtenir de l'aide

Pour poser des questions et obtenir de l'aide concernant votre implémentation, la démo ou la documentation :

Pour toute question plus générale sur la façon de répondre à vos besoins avec l'API Protected Audience, créez un problème dans le dépôt de l'API. Vous pouvez également discuter des cas d'utilisation du secteur dans le groupe d'activités du W3C pour l'amélioration de la publicité sur le Web.

Utilisez le formulaire de commentaires de la Privacy Sandbox pour partager vos commentaires en privé avec l'équipe Chrome, en dehors des forums publics.

Désactiver

Vous souhaitez désactiver l'API Protected Audience ? Découvrez comment bloquer l'accès à l'API Protected Audience en tant que propriétaire de site ou utilisateur individuel.

Recevoir les dernières informations