API Protected Audience: guide du développeur

Guide du développeur pour les enchères publicitaires sur l'appareil permettant de diffuser des audiences de remarketing et personnalisées sans suivi tiers sur plusieurs sites.

Information:FLEDGE a été renommé API Protected Audience. Pour en savoir plus sur ce changement de nom, consultez cet article de blog.

Important:La phase d'évaluation de la pertinence et des mesures de la Privacy Sandbox s'est terminée le 20 septembre 2023. Les API sont désormais disponibles pour 99% des utilisateurs de Chrome. L'inscription à cette phase est terminée. Pour connaître le pourcentage d'utilisateurs pour lesquels chaque API est activée, consultez les graphiques d'état de Chrome.

Pour les nouveaux utilisateurs de l'API Protected Audience, consultez la présentation de l'API Protected Audience pour une explication générale de l'API.

Cet article est destiné aux développeurs et sert de référence technique pour la dernière itération de l'API expérimentale Protected Audience. Une démonstration du déploiement de base de l'API Protected Audience est disponible, ainsi que des références d'API pour les acheteurs et les vendeurs d'annonces.

État de l'implémentation

• La proposition de l'API Protected Audience est maintenant en phase de disponibilité générale. Soulevez les questions et suivez la discussion.
• L'état des fonctionnalités en attente de l'API Protected Audience détaille les modifications et les améliorations apportées à cette API et à ses fonctionnalités.
• État du clignotement
• État de la plate-forme Chrome de l'API Protected Audience: spécifique à l'API Protected Audience sur Chrome.
• État de la plate-forme Chrome API Ads: ensemble d'API facilitant la publicité: API Protected Audience, Topics, Fenced Frames et Attribution Reporting.

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

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

L'API Protected Audience est une API de la Privacy Sandbox conçue pour diffuser des cas d'utilisation de remarketing et d'audiences personnalisées. Elle a été conçue pour ne pas être utilisée par des tiers pour suivre le comportement de navigation des utilisateurs sur les sites. L'API active les enchères sur l'appareil par le navigateur, afin de choisir des annonces pertinentes pour les sites Web précédemment consultés par l'utilisateur.

L'API Protected Audience est la première expérience mise en œuvre dans Chromium dans la famille de propositions TURTLEDOVE.

Essayer l'API Protected Audience

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

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

• Guide des acheteurs pour joinAdInterestGroup() et generateBid().
• Guide du vendeur pour l'API Protected AudiencerunAdAuction()
• Guide des acheteurs reportWin() et guide du vendeur concernant reportResult()
• Résoudre les problèmes liés à l'API Protected Audience

Vous pouvez également lire les bonnes pratiques concernant la latence des enchères publicitaires 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 des sites d'annonceurs et d'éditeurs est disponible sur protect-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 avec chrome://flags ou des flags de fonctionnalité

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

• Activer chrome://flags/#privacy-sandbox-ads-apis
• Définissez des indicateurs à partir de la ligne de commande. La liste complète des indicateurs de l'API Protected Audience disponibles est disponible dans Chromium Code Search.

Afficher des annonces dans des cadres iFrame ou cloisonnés

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

Pour afficher les annonces à l'aide de <fencedframe>:

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

Pour afficher les annonces à l'aide de <iframe>:

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

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

Remarque:Il s'agit d'une version en cours de développement de l'API Protected Audience, destinée aux tests préliminaires. Elle ne doit pas être considérée comme complète ni indiquer la mise en œuvre finale. La progression et le statut de l'API Protected Audience sont abordés lors des réunions WICG régulières. Le calendrier de la Privacy Sandbox indique les délais d'implémentation de l'API Protected Audience et d'autres API Privacy Sandbox.

Fonctionnalités compatibles

L'API Protected Audience derrière les flags de fonctionnalités dans Chromium est un premier test visant à tester les fonctionnalités suivantes de cette API:

• Groupes de centres d'intérêt: ils sont stockés par le navigateur, avec les métadonnées associées permettant de configurer les enchères et l'affichage des annonces.
• Enchères sur l'appareil par les acheteurs (DSP ou annonceur): basées sur les groupes de centres d'intérêt stockés et les signaux du vendeur.
• Sélection d'annonces sur l'appareil par le vendeur (SSP ou éditeur): basée sur les enchères et les métadonnées des acheteurs.
• Rendu des annonces dans une version temporairement assouplie de Fenced Frames: 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 compatibles et les contraintes, consultez la présentation de l'API Protected Audience.

Autorisations liées aux groupes de centres d'intérêt

L'implémentation actuelle de l'API Protected Audience autorise par défaut l'appel de joinAdInterestGroup() depuis n'importe quelle page d'une page, même à partir d'iFrames interdomaines.

À l'avenir, une fois que les propriétaires de sites auront eu le temps de mettre à jour leurs règles d'autorisation pour les cadres iFrame interdomaines, il sera question d'interdire les appels provenant de cadres iFrame 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 afin de récupérer des informations en temps réel compatibles avec les enchères publicitaires de l'API Protected Audience. Ces informations peuvent être utilisées de plusieurs manières:

• Les acheteurs peuvent décider de calculer le budget restant de leur campagne publicitaire.
• Les vendeurs peuvent être tenus de vérifier que les créations publicitaires respectent le règlement pour les éditeurs.

Le code de service clé-valeur de l'API Protected Audience est maintenant disponible. Consultez l'annonce sur le blog pour connaître l'état d'avancement.

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

Consultez l'article de blog sur les services de l'API Protected Audience pour connaître le calendrier. Nous informerons les développeurs de commencer les tests et l'adoption avant que cette transition n'ait lieu.

Détecter la compatibilité des fonctionnalités

Avant d'utiliser l'API, vérifiez si elle est compatible avec le navigateur et si elle est 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');

Attention:La prise en charge des fonctionnalités sur la page actuelle ne garantit pas l'utilisation d'une API. L'utilisateur peut avoir désactivé l'API dans les paramètres du navigateur ou disposer d'autres paramètres empêchant l'utilisation de l'API. Afin de protéger la confidentialité des utilisateurs, il n'existe aucun moyen de vérifier cela de manière programmatique.

Comment fonctionne l'API Protected Audience ?

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

Avertissement:Les fonctionnalités décrites dans cet article n'ont pas toutes été implémentées (ou entièrement implémentées) dans la version de l'API Protected Audience en cours de test dans Chrome. L'article Tester avec des flags de fonctionnalités décrit les fonctionnalités de l'API Protected Audience actuellement disponibles pour les tests dans Chrome exécuté à partir de la ligne de commande.

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

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

Imaginez qu'un utilisateur visite le site Web d'un fabricant de vélos personnalisé (l'annonceur) dans cet exemple et passe un certain temps sur la page du produit d'un vélo en acier fait main. Le fabricant du vélo dispose ainsi d'une opportunité de remarketing.

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

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

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

• Lisez la présentation de l'API Protected Audience: Les navigateurs enregistrent les groupes de centres d'intérêt.
• Consultez le guide de l'API: acheteurs et DSP, découvrez comment joinAdInterestGroup() et générer des enchères.

Remarque:L'origine du contexte d'appel pour joinAdInterestGroup() doit correspondre à celle du propriétaire du groupe de centres d'intérêt. joinAdInterestGroup() doit être appelé à partir d'un iFrame appartenant au propriétaire du groupe de centres d'intérêt (par exemple, depuis une DSP). Si l'origine du document actuel est la même que celle du propriétaire du groupe de centres d'intérêt (par exemple, un site Web possédant ses propres groupes de centres d'intérêt), aucun iFrame n'est nécessaire.

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

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

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

Comment les acheteurs définissent-ils les enchères ?

generateBid() est appelé pour chaque groupe de centres d'intérêt auquel le navigateur est membre, si le propriétaire du groupe de centres d'intérêt est invité à définir une enchère.

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

3. L'utilisateur visite un site qui vend de l'espace publicitaire.

Plus tard, l'utilisateur visite un site qui vend de l'espace publicitaire. Dans cet exemple, il s'agit d'un site Web d'actualités. Le site dispose d'un inventaire publicitaire qu'il vend de manière programmatique avec des enchères en temps réel.

4. Les enchères publicitaires ont lieu dans le navigateur

Les enchères publicitaires sont susceptibles d'être menées par le fournisseur côté offre 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. La mise aux enchères tient compte des groupes de centres d'intérêt auxquels le navigateur appartient, ainsi que des données provenant des acheteurs d'espace publicitaire et des vendeurs des services de clé-valeur.

• Lire la vidéo d'explication de l'API Protected Audience: Les vendeurs effectuent des enchères sur l'appareil.
• Lisez le guide de l'API: les vendeurs peuvent en savoir plus sur runAdAuction() et les bonnes pratiques concernant la latence des enchères publicitaires.

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

Lors d'une enchère publicitaire, le vendeur peut demander des données en temps réel sur des créations publicitaires spécifiques en envoyant une demande à son service clé-valeur. Le vendeur peut demander ces informations lors de la méthode runAdAuction() via 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 de centres d'intérêt participant à l'enchère.

Un acheteur peut demander des données en temps réel à partir de son service clé-valeur à l'aide des propriétés trustedBiddingSignalsUrl et trustedBiddingSignalsKeys de l'argument de groupe de centres 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 tirée de trustedBiddingSignalsKeys.

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

• Lisez la vidéo d'explication de l'API Protected Audience: Récupérer des données en temps réel à partir du service clés-valeurs de l'API Protected Audience.
• Consultez la page sur le service clé-valeur de l'API Protected Audience en Open Source.

Important:Pendant la phase expérimentale initiale de test de l'API Protected Audience, trustedBiddingSignalsUrl doit avoir la même origine que le propriétaire du groupe de centres d'intérêt. Pour en savoir plus, consultez Utiliser votre propre serveur.

6. L'annonce gagnante est diffusée.

La promesse renvoyée par runAdAuction() se résout en un objet de configuration de frame cloisonné (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 cloisonné pour parcourir le frame vers l'annonce gagnante, mais l'URL de l'annonce n'est pas visible par l'outil d'intégration de frames.

Remarque:L'objet FencedFrameConfig n'est renvoyé que lorsque l'indicateur resolveToConfig est défini sur true dans la configuration de l'enchère. Si l'indicateur n'est pas défini ou s'il est défini sur false, une URN opaque est renvoyée, et ne peut s'afficher que dans un iFrame.

L'objet de configuration de cloisonnement est disponible à partir de M114. Pour en savoir plus sur l'objet FencedFrameConfig, consultez cet article du blog Chrome.

• Lire la présentation de l'API Protected Audience: les navigateurs affichent l'annonce gagnante

7. Le résultat de la mise aux 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 de création de rapports temporaire au niveau de l'événement, le code qui implémente reportResult() pour le vendeur et reportWin() pour l'enchérisseur gagnant peut appeler la fonction sendReportTo(). Elle utilise un seul argument: une chaîne représentant une URL récupérée à la fin de l'enchère, qui encode les informations au niveau de l'événement à signaler.

• Consultez le guide de l'API: découvrez les rapports sur les vendeurs et les acheteurs.

8. Un clic sur une annonce est enregistré.

Un clic sur une annonce affichée dans un frame cloisonné est signalé. Pour en savoir plus à ce sujet, consultez Rapports sur les annonces Fenced Frames.

---

Ce diagramme décrit chaque étape d'une mise aux enchères 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 mise en œuvre dans Chromium dans la famille de propositions TURTLEDOVE.

L'API Protected Audience respecte les principes généraux de TURTLEDOVE. Certaines publicités en ligne consistent à diffuser une annonce auprès d'une personne potentiellement intéressée ayant déjà interagi avec l'annonceur ou le réseau publicitaire. Jusqu'à présent, cela a permis à l'annonceur de reconnaître une personne spécifique lorsqu'elle parcourait des sites Web, ce qui constitue une préoccupation majeure pour la confidentialité sur le Web d'aujourd'hui.

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

• C'est le navigateur, et non l'annonceur, qui contient les informations sur ce qui, selon l'annonceur, intéresse une personne.
• Les annonceurs peuvent diffuser des annonces en fonction d'un centre d'intérêt, mais ne peuvent pas combiner ce centre d'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 née de TURTLEDOVE et d'un ensemble de propositions de modification associées afin de mieux répondre aux besoins des développeurs qui utiliseraient l'API:

• Dans SPARROW : Criteo a proposé l'ajout d'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 la création de rapports agrégés.
• Les propositions TERN de NextRoll et PARRROT de Magnite décrivent les différents rôles des acheteurs et des vendeurs dans les enchères sur l'appareil. Le flux d'enchères/d'évaluation des annonces de l'API Protected Audience s'appuie sur ce travail.
• Les modifications TURTLEDOVE basées sur le résultat et au niveau du produit de RTB House ont amélioré le modèle d'anonymat et les fonctionnalités de personnalisation des enchères sur l'appareil.
• PARAKEET est la proposition de Microsoft pour un service publicitaire de type TURTLEDOVE qui repose sur un serveur proxy exécuté dans un TEE entre le navigateur et les fournisseurs de technologie publicitaire, pour anonymiser les demandes d'annonces et 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 soutenir les futurs travaux visant à combiner davantage les meilleures fonctionnalités des deux propositions.

L'API Protected Audience n'empêche pas encore le réseau publicitaire d'un site Web de déterminer quelles annonces sont vues par les utilisateurs. Nous prévoyons de 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, une propriété de l'objet de configuration des enchères transmis à navigator.runAdAuction().
• userBiddingSignals, une propriété de l'objet de configuration du groupe de centres d'intérêt transmis à navigator.joinAdInterestGroup()

Configuration de navigateur disponible

Les utilisateurs peuvent ajuster leur participation aux essais de la 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 de haut niveau Privacy Sandbox pour désactiver l'API Protected Audience. Chrome prévoit de permettre aux utilisateurs de voir et de gérer la liste des groupes de centres d'intérêt auxquels ils ont été ajoutés sur les sites Web qu'ils ont visités. Comme pour les technologies de la Privacy Sandbox, les paramètres utilisateur peuvent évoluer en fonction des commentaires des utilisateurs, des organismes de réglementation et d'autres personnes.

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 de l'API ne peuvent pas accéder à l'appartenance à un groupe lorsque les utilisateurs naviguent en mode navigation privée. L'adhésion 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 ?

Le navigateur met en cache les ressources qui contiennent les Worklets Protected Audience : les Worklets de génération d'enchères et de création de rapports de l'acheteur, ainsi que les Worklets de création de rapports et d'évaluation des annonces du vendeur. Vous pouvez utiliser l'en-tête Cache-Control pour contrôler le comportement de mise en cache.

Interagir et donner votre avis

Obtenir de l'aide

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

• GitHub: consultez l'explication, posez des questions et suivez la discussion.
• Démonstration: signalez un problème dans le dépôt de code de démonstration.
• Assistance aux développeurs: posez des questions et participez à des discussions sur le dépôt d'assistance pour les développeurs Privacy Sandbox. Sélectionnez le modèle de problème pour l'API Protected Audience.
• Implémentation dans Chrome: pour les bugs ou les problèmes liés à l'implémentation de l'API Protected Audience dans Chrome, vous pouvez consulter les problèmes existants ou signaler un nouveau problème.

Pour des questions plus générales concernant la réponse à vos besoins avec l'API Protected Audience, signalez un problème dans le dépôt de l'API. Vous pouvez également discuter de cas d'utilisation sectoriels dans le groupe d'activités Améliorer la publicité Web du W3C.

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 d'un site ou en tant qu'utilisateur individuel.

Recevoir les dernières informations

• Pour recevoir les notifications de changement d'état de l'API, rejoignez la liste de diffusion pour les développeurs.
• Pour suivre de près toutes les discussions en cours sur l'API, cliquez sur le bouton Watch (Regarder) sur la page de l'API sur GitHub. Pour ce faire, vous devez disposer d'un compte GitHub ou en créer un.
• Pour obtenir des informations générales sur la Privacy Sandbox, abonnez-vous au flux RSS [Progress in the Privacy Sandbox].
• Rejoignez les appels planifiés pour l'API Protected Audience (toutes les deux semaines). Tout le monde est bienvenu. Pour participer, assurez-vous d'abord de rejoindre le WICG. Vous pouvez participer activement ou simplement l'écouter !