Guide du développeur de l'API FLEDGE

À qui s'adresse cet article ?

Ce post est une référence technique à la version actuelle de l'API expérimentale Protected Audience.

Qu'est-ce que Protected Audience ?

L'API Protected Audience est une proposition de la Privacy Sandbox qui permet de diffuser des cas d'utilisation de remarketing et d'audiences personnalisées. Elle est 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.

Protected Audience est la première expérience à avoir été implémentée dans Chromium dans la famille de propositions TURTLEDOVE.

Le schéma ci-dessous présente le cycle de vie de FLEDGE:

Illustration offrant un aperçu de chaque étape du cycle de vie de FLEDGE
Cycle de vie de FLEDGE
.

Comment essayer l'API Protected Audience ?

Démonstration de Protected Audience

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

La vidéo de démonstration explique le fonctionnement du code de démonstration et explique comment utiliser les outils pour les développeurs Chrome pour le débogage de Protected Audience.

Participer à une phase d'évaluation de l'API Protected Audience

Une phase d'évaluation de la mesure et de la pertinence de la Privacy Sandbox est disponible dans la version bêta 101.0.4951.26 et ultérieures de Chrome sur ordinateur pour les API Protected Audience, Topics et Attribution Reporting.

Pour y participer, demandez un jeton pour la phase d'évaluation.

Une fois inscrit à l'essai, vous pouvez essayer l'API Protected Audience JavaScript sur les pages qui fournissent un jeton d'essai valide: par exemple, pour demander au navigateur de rejoindre un ou plusieurs groupes de centres d'intérêt, puis lancer une enchère publicitaire pour sélectionner et afficher une annonce.

La démonstration de l'API Protected Audience fournit un exemple de base de son déploiement de bout en bout.

Fournissez un jeton d'essai pour chaque page sur laquelle vous souhaitez exécuter le code de l'API Protected Audience:

  • En tant que balise Meta dans la section <head>:

    <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">

  • En tant qu'en-tête HTTP:

    Origin-Trial: TOKEN_GOES_HERE

  • En fournissant un jeton par programmation:

    const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);

Un iFrame exécutant du code Protected Audience (par exemple, un appel navigator.joinAdInterestGroup() effectué par le propriétaire d'un groupe de centres d'intérêt) doit fournir un jeton correspondant à son origine.

La page Informations sur la phase d'évaluation proposée pour la première phase d'audience protégée fournit plus de détails sur les objectifs du premier essai et explique quelles fonctionnalités sont compatibles.

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 ou ultérieure de Chrome sur un ordinateur : * En activant chrome://flags/#privacy-sandbox-ads-apis. * En définissant des indicateurs à partir de la ligne de commande.

Afficher des annonces dans des cadres iFrame ou cloisonnés

Les annonces peuvent être affichées dans un <iframe> ou un <fencedframe>, en fonction des 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 et de gains pour le débogage.

La section Exécuter Chromium avec des indicateurs explique comment définir des indicateurs lorsque vous exécutez Chrome et d'autres navigateurs Chromium à partir de la ligne de commande. La liste complète des indicateurs Protected Audience est disponible sur Chromium Code Search.

Quelles sont les fonctionnalités compatibles avec la dernière version de Chrome ?

L'API Protected Audience est mise à disposition des indicateurs de fonctionnalité dans Chromium. Il s'agit d'un premier test pour les fonctionnalités suivantes de la proposition Protected Audience:

  • 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.
  • Affichage des annonces dans une version temporairement assouplie de Fenced Frames: l'accès au réseau et la journalisation sont autorisés pour l'affichage des annonces.

L'explication de l'API fournit plus de détails sur la compatibilité et les contraintes des fonctionnalités.

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

Dans l'implémentation actuelle de l'API Protected Audience, l'autorisation d'appeler joinAdInterestGroup() est autorisée par défaut depuis n'importe quel endroit d'une page, même à partir d'iFrames interdomaines. À l'avenir, une fois que les propriétaires de sites auront eu le temps d'ajuster leurs règles d'autorisation pour les cadres iFrame interdomaines, leur objectif consistera à interdire les appels provenant de cadres iFrame interdomaines, comme expliqué dans l'explication.

Service clé-valeur

Dans le cadre d'une enchère publicitaire Protected Audience, le navigateur peut accéder à un service clé-valeur qui renvoie des paires clé-valeur simples pour fournir des informations à un acheteur d'annonces, telles que le budget restant de la campagne. La proposition de l'API Protected Audience exige que ce serveur "n'effectue aucune journalisation au niveau des événements et ne comporte aucun autre effet secondaire basé sur ces requêtes".

Le code du service Clé-valeur de l'API Protected Audience est désormais disponible dans un dépôt GitHub Privacy Sandbox. Ce service peut être utilisé par les développeurs Chrome et Android. Consultez l'annonce sur le blog pour connaître l'état d'avancement. Pour en savoir plus sur le service clé-valeur Protected Audience, consultez la présentation de l'API et celle du modèle de confiance.

Pour les tests initiaux, le modèle Bring Your Own Server est utilisé. À long terme, les technologies publicitaires devront utiliser les services Open Source de clés-valeurs Protected Audience s'exécutant dans des environnements d'exécution approuvés pour récupérer les données en temps réel.

Afin de garantir que l'écosystème dispose d'un temps de test suffisant, nous ne prévoyons pas d'exiger l'utilisation des services de clés-valeurs ou des TEE Open Source avant un certain temps après l'abandon des cookies tiers. Nous informerons les développeurs dans les grandes lignes pour 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');

Comment désactiver l'API Protected Audience ?

Vous pouvez bloquer l'accès à l'API Protected Audience soit en tant que propriétaire du site, soit en tant qu'utilisateur individuel.

Comment les sites peuvent-ils contrôler l'accès ?

À terme, Protected Audience obligera les sites à définir une règle d'autorisations pour permettre la disponibilité de cette fonctionnalité. Cela permettra de garantir que des tiers arbitraires ne peuvent pas utiliser l'API à l'insu du site. Toutefois, pour faciliter les tests lors de la première phase d'évaluation, cette exigence est annulée par défaut. Les sites qui souhaitent désactiver explicitement la fonctionnalité Protected Audience pendant la période de test peuvent utiliser les règles d'autorisation pertinentes pour bloquer l'accès.

Deux règles d'autorisation Protected Audience peuvent être définies indépendamment : * join-ad-interest-group active/désactive la fonctionnalité permettant d'ajouter un navigateur à des groupes de centres d'intérêt * run-ad-auction active/désactive les fonctionnalités permettant de lancer des enchères sur l'appareil

L'accès aux API Protected Audience peut être entièrement désactivé dans les contextes propriétaires en spécifiant la règle d'autorisation suivante dans un en-tête de réponse HTTP:

Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()

Vous pouvez désactiver l'utilisation des API dans un iFrame en ajoutant l'attribut allow suivant à un élément iFrame:

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

Vous trouverez plus d'informations à ce sujet dans la section Proposed First Protected Audience Origin Trial Permissions-Policy (Autorisations d'autorisation de la phase d'évaluation de la première audience protégée proposée) pour en savoir plus.

Désactivation par l'utilisateur

Un utilisateur peut bloquer l'accès à l'API Protected Audience et à d'autres fonctionnalités de la Privacy Sandbox à l'aide de l'un des mécanismes suivants:

  • Désactivez les essais de la Privacy Sandbox dans les paramètres de Chrome: Paramètres > Sécurité et confidentialité > Privacy Sandbox. Ce contenu est également accessible sur chrome://settings/adPrivacy.
  • Désactivez les cookies tiers dans les paramètres de Chrome: Paramètres > Sécurité et confidentialité.
  • Définissez Cookies et autres données de site sur "Bloquer les cookies tiers" ou "Bloquer tous les cookies" dans chrome://settings/cookies.
  • Utilisez le mode navigation privée.

L'explication sur l'API Protected Audience fournit plus de détails sur les éléments de conception d'une API et décrit comment l'API cherche à atteindre les objectifs de confidentialité.

Déboguer les Worklets Protected Audience

À partir de la version 98.0.4718.0 de Chrome Canary, il est possible de déboguer les Worklets de l'API Protected Audience dans les outils pour les développeurs Chrome.

La première étape consiste à définir des points d'arrêt via une nouvelle catégorie dans le volet Points d'arrêt de l'écouteur d'événements du panneau Sources.

Capture d&#39;écran des outils de développement dans Chrome Canary mettant en évidence le volet &quot;Points d&#39;arrêt de l&#39;écouteur d&#39;événements&quot; dans le panneau &quot;Sources&quot;. Le début de la phase d&#39;enchères de l&#39;enchérisseur est sélectionné dans le Worklet d&#39;enchères publicitaires.

Lorsqu'un point d'arrêt se déclenche, l'exécution est suspendue avant la première instruction, au niveau supérieur du script de worklet. Vous pouvez utiliser des points d'arrêt ou des commandes d'étape standards pour accéder à la fonction d'enchères, d'évaluation et de création de rapports elle-même.

Les scripts du worklet en direct s'affichent également sous le panneau Threads.

Capture d&#39;écran des outils de développement dans Chrome Canary, avec le volet &quot;Threads&quot; encadré dans le panneau &quot;Sources&quot; et montrant le script de worklet actuellement mis en pause.

Étant donné que certains Worklets peuvent s'exécuter en parallèle, plusieurs threads peuvent se retrouver à l'état "Suspendu". Vous pouvez utiliser la liste des threads pour passer d'un thread à l'autre, et les reprendre ou les inspecter plus en détail, le cas échéant.

Observer les événements Protected Audience

Dans le panneau "Application" des outils pour les développeurs Chrome, vous pouvez observer les événements de groupes de centres d'intérêt et d'enchères Protected Audience.

Si vous consultez le site de démonstration de l'API Protected Audience dans un navigateur sur lequel l'API Protected Audience est activée, les outils de développement affichent des informations sur l'événement join.

Panneau &quot;Outils de développement&quot; de Chrome Canary affichant des informations sur la participation à un groupe de centres d&#39;intérêt de l&#39;API Protected Audience

Désormais, si vous consultez le site de démonstration de l'API Protected Audience dans un navigateur sur lequel l'API Protected Audience est activée, les outils de développement affichent des informations sur les événements bid et win.

Panneau &quot;Application&quot; des outils de développement dans Chrome Canary affichant des informations sur l&#39;enchère aux enchères Protected Audience et les événements gagnants.

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.

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

Illustration représentant une personne qui visite le site d&#39;un fabricant de vélos personnalisé dans un navigateur sur son ordinateur portable

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 de 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.

Illustration représentant une personne qui consulte un site dans un navigateur sur son ordinateur portable. Le code JavaScript joinAdInterestGroup() s&#39;exécute dans le navigateur.

Section explicative:Les navigateurs enregistrent des groupes 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 est nommé custom-bikes et le 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 décrites à l'étape 4. 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.

joinAdInterestGroup() nécessite l'autorisation : * Le site consulté * Le propriétaire du groupe de centres d'intérêt

Par exemple, malicious.example ne doit pas pouvoir appeler joinAdInterestGroup() avec dsp.example comme propriétaire sans l'autorisation de dsp.example.

Autorisation du site consulté

Même origine: par défaut, l'autorisation est implicitement accordée pour les appels joinAdInterestGroup() provenant de la même origine que le site consulté, c'est-à-dire de la même origine que le frame de premier niveau de la page actuelle. Les sites peuvent utiliser une instruction join-ad-interest-group de l'en-tête des règles d'autorisations Protected Audience pour désactiver les appels joinAdInterestGroup().

Inter origines: l'appel de joinAdInterestGroup() à partir d'origines différentes de la page actuelle ne peut aboutir que si le site consulté a défini une règle d'autorisation qui autorise les appels à joinAdInterestGroup() depuis des iFrames multi-origines.

Autorisation du propriétaire du groupe de centres d'intérêt

L'autorisation de propriétaire d'un groupe de centres d'intérêt est accordée implicitement en appelant joinAdInterestGroup() à partir d'un iFrame ayant la même origine que celle du propriétaire du groupe de centres d'intérêt. Par exemple, un iFrame dsp.example peut appeler joinAdInterestGroup() pour les groupes de centres d'intérêt appartenant à dsp.example.

La proposition est que joinAdInterestGroup() peut s'exécuter dans une page ou un iFrame du domaine du propriétaire, ou être délégué à d'autres domaines fournis à l'aide d'une liste dans une URL .well-known.

Utiliser navigateurator.joinAdInterestGroup()

Voici un exemple d'utilisation de l'API:

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  dailyUpdateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

La taille de l'objet interestGroup transmis à la fonction ne doit pas dépasser 50 Kio. Sinon, l'appel échouera. Le deuxième paramètre spécifie la durée du groupe de centres d'intérêt, limitée à 30 jours. Les appels successifs écrasent les valeurs stockées précédemment.

Propriétés du groupe de centres d'intérêt

Propriété Obligatoire Exemple Rôle
owner Obligatoire 'https://dsp.example' Origine du propriétaire du groupe de centres d'intérêt.
name Obligatoire 'custom-bikes' Nom du groupe de centres d'intérêt.
biddingLogicUrl** Facultatif* 'https://dsp.example/bid/custom-bikes/bid.js' URL pour l'exécution de JavaScript d'enchères dans le worklet.
biddingWasmHelperUrl** Facultatif* 'https://dsp.example/bid/custom-bikes/bid.wasm' URL du code WebAssembly généré à partir de biddingLogicUrl.
dailyUpdateUrl** Facultatif 'https://dsp.example/bid/custom-bikes/update' URL qui renvoie au format JSON pour mettre à jour les attributs du groupe de centres d'intérêt. (voir Mettre à jour le groupe de centres d'intérêt).
trustedBiddingSignalsUrl** Facultatif 'https://dsp.example/trusted/bidding-signals' URL de base pour les demandes de clé-valeur envoyées au serveur de confiance de l'enchérisseur.
trustedBiddingSignalsKeys Facultatif ['key1', 'key2' ...] Clés pour les requêtes adressées au serveur de confiance de clé-valeur.
userBiddingSignals Facultatif {...} Métadonnées supplémentaires que le propriétaire peut utiliser lors des enchères.
ads Facultatif* [bikeAd1, bikeAd2, bikeAd3] Annonces susceptibles d'être affichées pour ce groupe de centres d'intérêt.
adComponents Facultatif [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] Composants d'annonces composées de plusieurs éléments

* Toutes les propriétés sont facultatives, à l'exception de owner et name. Les propriétés biddingLogicUrl et ads sont facultatives, mais obligatoires pour participer à une mise aux enchères. Il peut y avoir des cas d'utilisation de la création d'un groupe de centres d'intérêt sans ces propriétés: par exemple, le propriétaire d'un groupe de centres d'intérêt peut vouloir ajouter un navigateur à un groupe de centres d'intérêt pour une campagne qui n'est pas encore diffusée ou pour une autre utilisation future, ou il peut temporairement avoir épuisé son budget publicitaire.

** Les URL biddingLogicUrl, biddingWasmHelperUrl, dailyUpdateUrl et trustedBiddingSignalsUrl doivent avoir la même origine que celle du propriétaire. Aucune contrainte de ce type n'est appliquée aux URL ads et adComponents.

Mettre à jour les attributs des groupes de centres d'intérêt

dailyUpdateUrl spécifie un serveur Web qui renvoie au format JSON les propriétés de groupes de centres d'intérêt correspondant à l'objet de groupe de centres d'intérêt transmis à navigator.joinAdInterestGroup(). Le propriétaire d'un groupe peut ainsi mettre à jour régulièrement les attributs du groupe de centres d'intérêt. Dans l'implémentation actuelle, les attributs suivants peuvent être modifiés:

  • biddingLogicUrl
  • biddingWasmHelperUrl
  • trustedBiddingSignalsUrl
  • trustedBiddingSignalsKeys
  • ads
  • priority

Les champs non spécifiés dans le fichier JSON ne seront pas écrasés. Seuls les champs spécifiés dans le fichier JSON sont mis à jour, tandis que l'appel de navigator.joinAdInterestGroup() écrase tout groupe de centres d'intérêt existant.

Les mises à jour sont optimisées et peuvent échouer dans les conditions suivantes : * Délai avant expiration de la requête réseau (actuellement de 30 secondes). * Autre défaillance réseau. * Échec de l'analyse JSON.

Les mises à jour peuvent également être annulées si trop de temps contigu a été passé à la mise à jour, bien que cela n'impose aucune limite de débit pour les mises à jour annulées (restantes). Le débit est limité à une mise à jour par jour. Les mises à jour ayant échoué en raison d'erreurs réseau font l'objet d'une nouvelle tentative au bout d'une heure. Celles qui échouent en raison d'une déconnexion d'Internet sont retentées immédiatement lors de la reconnexion.

Mises à jour manuelles

Les mises à jour des groupes de centres d'intérêt appartenant à l'origine du frame actuel peuvent être déclenchées manuellement via navigator.updateAdInterestGroups(). La limitation du débit empêche les mises à jour trop fréquentes : les appels répétés à navigator.updateAdInterestGroups() n'ont aucun effet avant la fin de la période de limitation du débit (actuellement un jour). La limite du taux est réinitialisée si navigator.joinAdInterestGroup() est à nouveau appelé pour les mêmes groupe de centres d'intérêt owner et name.

Mises à jour automatiques

Tous les groupes de centres d'intérêt chargés pour une mise aux enchères sont mis à jour automatiquement une fois l'enchère terminée, sous réserve des mêmes limites de taux que les mises à jour manuelles. Pour chaque propriétaire ayant au moins un groupe de centres d'intérêt participant à une mise aux enchères, c'est comme si navigator.updateAdInterestGroups() était appelé à partir d'un iFrame dont l'origine correspond à ce propriétaire.

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 ?

Le script à l'emplacement biddingLogicUrl fourni par le propriétaire d'un groupe de centres d'intérêt doit inclure une fonction generateBid(). Lorsqu'un vendeur d'espace publicitaire appelle navigator.runAdAuction(), la fonction generatedBid() est appelée une fois pour chacun des groupes de centres d'intérêt dont le navigateur est membre, si le propriétaire du groupe de centres d'intérêt est invité à enchérir. En d'autres termes, generateBid() est appelé une fois pour chaque annonce candidate. Le vendeur fournit une propriété decisionLogicUrl pour le paramètre de configuration de l'enchère transmis à navigator.runAdAuction(). Le code au niveau de cette URL doit inclure une fonction scoreAd(), qui est exécutée pour chaque enchérisseur de la mise aux enchères, afin d'évaluer chacune des enchères renvoyées par generateBid().

Le script sur biddingLogicUrl fourni par un acheteur d'espace publicitaire doit inclure une fonction generateBid(). Cette fonction est appelée une fois pour chaque annonce candidate. runAdAuction() vérifie individuellement chaque annonce, ainsi que l'enchère et les métadonnées associées, puis attribue à l'annonce un score de désirabilité numérique.

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

generateBid() utilise les arguments suivants :

  • interestGroup
    Objet transmis à joinAdInterestGroup() par l'acheteur d'annonces. (Le groupe de centres d'intérêt peut être mis à jour via dailyUpdateUrl.)

  • auctionSignals
    Propriété de l'argument configuration des enchères transmise à navigator.runAdAuction() par le vendeur de l'espace publicitaire. Elles fournissent des informations sur le contexte de la page (telles que la taille de l'annonce et la référence éditeur), le type d'enchère (au premier prix ou au second prix), ainsi que d'autres métadonnées.

  • perBuyerSignals
    Comme pour auctionSignals, il s'agit d'une propriété de l'argument de configuration des enchères transmise à navigator.runAdAuction() par le vendeur. Cela peut fournir des signaux contextuels du serveur de l'acheteur à propos de la page, si le vendeur est une SSP qui effectue un appel d'enchères en temps réel vers les serveurs de l'acheteur et renvoie la réponse, ou si la page de l'éditeur contacte directement le serveur de l'acheteur. Le cas échéant, l'acheteur peut souhaiter vérifier une signature cryptographique de ces signaux dans "generateBid()" afin de se protéger contre la falsification.

  • trustedBiddingSignals
    Objet dont les clés sont les trustedBiddingSignalsKeys pour le groupe de centres d'intérêt et dont les valeurs sont renvoyées dans la requête trustedBiddingSignals.

  • browserSignals
    Objet construit par le navigateur, qui peut inclure des informations sur le contexte de la page (telles que la hostname de la page actuelle, que le vendeur aurait autrement falsifiée) et des données sur le groupe de centres d'intérêt lui-même (par exemple, l'enregistrement du moment où le groupe a remporté une mise aux enchères, afin d'autoriser la limitation de la fréquence d'exposition sur l'appareil).

L'objet browserSignals possède les propriétés suivantes:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  joinCount: 3,
  bidCount: 17,
  prevWins: [[time1,ad1],[time2,ad2],...],
  wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
  dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}

Pour calculer une valeur bid, le code dans generateBid() peut utiliser les propriétés des paramètres de la fonction. Exemple :

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
    ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    ...
  }
}

generateBid() renvoie un objet avec quatre propriétés:

  • ad
    Métadonnées arbitraires sur l'annonce, telles que les informations que le vendeur s'attend à connaître sur cette enchère ou la création publicitaire. Le vendeur](/privacy-sandbox/resources/glossary#ssp) utilise ces informations pour sa création d'enchères et de décision. Le vendeur utilise ces informations dans sa logique de mise aux enchères et de décision.

  • bid
    Il s'agit d'une enchère numérique qui participera à la mise aux enchères. Le vendeur doit être en mesure de comparer les enchères de différents acheteurs. Par conséquent, les enchères doivent se trouver dans une unité choisie par le vendeur (par exemple, "EUR pour mille"). Si l'enchère est nulle ou négative, ce groupe de centres d'intérêt ne participera pas du tout aux enchères du vendeur. Grâce à ce mécanisme, l'acheteur peut appliquer les règles de l'annonceur concernant les emplacements où ses annonces peuvent être diffusées ou non.

  • render
    Une URL ou une liste d'URL qui sera utilisée pour afficher la création si cette enchère remporte la mise aux enchères. (Consultez la section Annonces composées de plusieurs éléments dans la vidéo d'explication de l'API.) La valeur doit correspondre à l'renderUrl de l'une des annonces définies pour le groupe de centres d'intérêt.

  • adComponents
    Liste facultative de 20 composants au maximum pour les annonces composées de plusieurs éléments, provenant de la propriété adComponents de l'argument de groupe de centres d'intérêt transmis à navigator.joinAdInterestGroup().

Demander à un navigateur de quitter un groupe de centres d'intérêt

Le propriétaire d'un groupe de centres d'intérêt peut demander à ce qu'un navigateur soit supprimé. En d'autres termes, le navigateur est invité à supprimer le groupe de centres d'intérêt de la liste des groupes dont il est membre.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

Si un utilisateur revient sur le site qui a demandé au navigateur d'ajouter un groupe de centres d'intérêt, le propriétaire de ce groupe peut appeler la fonction navigator.leaveAdInterestGroup() pour demander au navigateur de supprimer le groupe de centres d'intérêt. Le code d'une annonce peut également appeler cette fonction pour son groupe de centres d'intérêt.

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

Illustration représentant une personne qui consulte un site Web d&#39;actualités dans un navigateur sur son ordinateur portable. Le site dispose d&#39;un espace publicitaire vide.

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 à l'aide d'enchères en temps réel.

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

Illustration représentant une personne qui consulte un site Web d&#39;actualités dans un navigateur sur son ordinateur portable. Une mise aux enchères publicitaire à l&#39;aide de l&#39;API Protected Audience est en cours.

Section explicative:Les vendeurs effectuent des enchères sur l'appareil.

Les enchères publicitaires sont susceptibles d'être menées par la 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. 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'espaces publicitaires et des vendeurs des services de clés-valeurs.

Le vendeur d'espace publicitaire demande au navigateur de l'utilisateur de lancer une mise aux enchères en appelant navigator.runAdAuction().

Exemple :

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

const auctionResultPromise = navigator.runAdAuction(auctionConfig);

runAdAuction() renvoie une promesse qui se résout en URN (urn:uuid:<something>) qui représente le résultat de l'enchère publicitaire. Elle ne peut être décodée par le navigateur que lorsqu'elle est transmise à un frame cloisonné pour l'affichage: la page de l'éditeur ne peut pas inspecter l'annonce gagnante.

Le script decisionLogicUrl considère chaque annonce individuelle, ainsi que l'enchère et les métadonnées associées, l'une après l'autre, puis lui attribue un score de désirabilité numérique.

auctionConfig établissements

Propriété Obligatoire Exemple Rôle
seller Obligatoire 'https://ssp.example' Origine du vendeur.
decisionLogicUrl Obligatoire 'https://ssp.example/auction-decision-logic.js' URL du JavaScript du worklet d'enchères.
trustedScoringSignalsUrl Facultatif 'https://ssp.example/scoring-signals' URL du serveur de confiance du vendeur.
interestGroupBuyers* Obligatoire ['https://dsp.example', 'https://buyer2.example', ...] Origines de tous les propriétaires de groupes de centres d'intérêt ayant demandé à définir une enchère dans la mise aux enchères.
auctionSignals Facultatif {...} Informations sur le vendeur concernant le contexte de la page, le type d'enchère, etc.
sellerSignals Facultatif {...} Informations basées sur les paramètres de l'éditeur, sur les demandes d'annonces contextuelles, etc.
sellerTimeout Facultatif 100 Durée d'exécution maximale (ms) du script scoreAd() du vendeur.
perBuyerSignals Facultatif {'https://dsp.example': {...},
  'https://another-buyer.example': {...},
...}		 Signaux contextuels provenant de son serveur concernant la page de chaque acheteur.
perBuyerTimeouts Facultatif 50 Durée maximale d'exécution (ms) des scripts generateBid() d'un acheteur spécifique.
componentAuctions Facultatif [{'seller': 'https://www.some-other-ssp.com',
  'decisionLogicUrl': ..., ...},
  ...]		 Configurations supplémentaires pour les enchères de composants.

* Le vendeur peut spécifier interestGroupBuyers: '*' pour permettre à tous les groupes de centres d'intérêt d'enchérir. Les annonces sont ensuite acceptées ou refusées sur la base de critères autres que l'inclusion du propriétaire du groupe de centres d'intérêt. Par exemple, le vendeur peut examiner les créations publicitaires pour s'assurer qu'elles respectent ses règles.

** additionalBids n'est pas compatible avec l'implémentation actuelle de Protected Audience. Pour en savoir plus, consultez la section Participants aux enchères dans la vidéo d'explication sur Protected Audience.

Comment les annonces sont-elles sélectionnées ?

Le code dans decisionLogicUrl (une propriété de l'objet de configuration des enchères transmis à runAdAuction()) doit inclure une fonction scoreAd(). Celle-ci est exécutée une fois pour chaque annonce afin de déterminer sa désirabilité.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

scoreAd() utilise les arguments suivants : * adMetadata
Métadonnées arbitraires fournies par l'acheteur. * bid
Valeur d'enchère numérique. * auctionConfig
L'objet de configuration des enchères a été transmis à navigator.runAdAuction(). * trustedScoringSignals
Valeurs récupérées au moment de la mise aux enchères sur le serveur de confiance du vendeur, et représentant l'opinion du vendeur concernant l'annonce. * browserSignals
Objet construit par le navigateur, y compris des informations connues de celui-ci et que le script d'enchères du vendeur peut vouloir vérifier:

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}

Avant le début d'une enchère, le vendeur trouve la meilleure annonce contextuelle pour l'espace publicitaire disponible. Une partie de sa logique scoreAd() consiste à refuser toute annonce qui ne peut pas battre l'annonce contextuelle gagnante.

5. Le vendeur et les acheteurs participants reçoivent des données en temps réel de la part du service clé-valeur.

Illustration représentant une personne qui consulte un site Web d&#39;actualités dans un navigateur sur son ordinateur portable. Une enchère publicitaire est en cours à l&#39;aide de l&#39;API Protected Audience, et un participant obtient des données auprès du service clé-valeur.

Section explicative:Récupérer des données en temps réel à partir du service clé-valeur Protected Audience

Lors d'une enchère publicitaire, le vendeur de l'espace publicitaire peut obtenir des données en temps réel sur des créations publicitaires spécifiques en envoyant une demande à un service clé-valeur à l'aide de la propriété trustedScoringSignalsUrl de l'argument de configuration des enchères transmis à navigator.runAdAuction(), ainsi que des 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 de l'enchère.

De même, un acheteur d'espace publicitaire peut demander des données en temps réel au 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 demande 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 qui fournit des valeurs pour chacune des clés.

6. L'annonce gagnante est diffusée.

Illustration représentant une personne qui consulte un site Web d&#39;actualités dans un navigateur sur son ordinateur portable. Annonce pour un vélo (20% de remise) diffusée, avec un cadenas au-dessus indiquant que l&#39;annonce s&#39;affiche dans un cadre cloisonné.

Section explicative:Les navigateurs affichent l'annonce gagnante

Comme décrit précédemment: la promesse renvoyée par runAdAuction() est résolue en URN, qui est transmis à un frame cloisonné pour l'affichage, et le site affiche l'annonce gagnante.

7. Le résultat de la mise aux enchères est indiqué

Section explicative:Rapports au niveau des événements (pour l'instant)

Le vendeur signale le résultat

Section explicative:Rapports sur le vendeur sur l'affichage

Le code JavaScript du vendeur fourni sur decisionLogicUrl (qui a également fourni scoreAd()) peut inclure une fonction reportResult() pour indiquer le résultat de la mise aux enchères.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Les arguments transmis à cette fonction sont les suivants:

  • auctionConfig
    L'objet de configuration des enchères a été transmis à navigator.runAdAuction().

  • browserSignals
    Objet construit par le navigateur et fournissant des informations sur l'enchère. Exemple:

    {
  'topWindowHostname': 'publisher.example',
  'interestGroupOwner': 'https://dsp.example',
  'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
  'bid:' <bidValue>,
  'desirability': <winningAdScore>
}

La valeur renvoyée par cette fonction est utilisée comme argument sellerSignals pour la fonction reportWin() de l'enchérisseur gagnant.

L'enchérisseur ayant remporté l'enchère signale le résultat

Section explicative:Créer des rapports sur l'affichage et les événements d'annonces pour les acheteurs

Le code JavaScript de l'enchérisseur gagnant (qui a également fourni generateBid()) peut inclure une fonction reportWin() pour générer des rapports sur le résultat de la mise aux enchères.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

Les arguments transmis à cette fonction sont les suivants:

  • auctionSignals et perBuyerSignals
    Les mêmes valeurs sont transmises à generateBid() pour l'enchérisseur gagnant.
  • sellerSignals
    Valeur renvoyée par reportResult(), qui donne au vendeur la possibilité de transmettre des informations à l'acheteur.

  • browserSignals
    Objet construit par le navigateur et fournissant des informations sur l'enchère. Exemple:

    {
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid:' <bidValue>
}

Implémentation de rapports temporaires sur les pertes/gains

Deux méthodes sont temporairement disponibles dans Chrome pour créer des rapports sur les enchères:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Ces méthodes utilisent chacune un seul argument: une URL à extraire une fois l'enchère terminée. Elles peuvent être appelées plusieurs fois, dans scoreAd() et generateBid(), avec des arguments d'URL différents.

Chrome n'envoie des rapports de débogage que lorsqu'une enchère se termine. Si une mise aux enchères est annulée (en raison d'une nouvelle navigation, par exemple), aucun rapport n'est généré.

Ces méthodes sont disponibles par défaut dans Chrome si chrome://flags/#privacy-sandbox-ads-apis est activé. Toutefois, si vous exécutez Chrome avec des indicateurs de ligne de commande pour activer Protected Audience, vous devez activer explicitement les méthodes en incluant l'indicateur BiddingAndScoringDebugReportingAPI. Si l'indicateur n'est pas activé, les méthodes restent disponibles, mais ne font rien.

8. Un clic sur une annonce est enregistré.

Illustration représentant une personne qui clique sur une annonce pour un vélo, dans un cadre clôturé, sur un site Web d&#39;actualités, avec des données de rapport transmises au vendeur et aux acheteurs.

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.


Le diagramme ci-dessous décrit chaque étape d'une enchère publicitaire Protected Audience:

Illustration offrant un aperçu de chaque étape d&#39;une enchère publicitaire Protected Audience


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

Protected Audience est la première expérience à avoir été implémentée dans Chromium dans la famille de propositions TURTLEDOVE.

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. Auparavant, l'annonceur reconnaitait une personne spécifique lorsqu'il parcourait des sites Web, ce qui constitue une préoccupation majeure en ce qui concerne 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 des avancées clés en termes 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 peut 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 modifications associées visant à 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). 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 et d'évaluation des annonces de Protected Audience s'appuie sur ce travail.
  • Les modifications de 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é. Protected Audience n'a pas adopté ce modèle de proxy. Nous harmonisons les API JavaScript pour PARAKEET et Protected Audience afin de poursuivre nos futurs travaux visant à combiner 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 modifier pour rendre l'API plus privée au fil du temps.

Quelle est la 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 premiers tests, les utilisateurs pourront utiliser ce paramètre de haut niveau de la Privacy Sandbox pour désactiver l'API Protected Audience. Chrome prévoit de permettre aux utilisateurs de consulter 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 de mettre à jour les paramètres disponibles dans Chrome à mesure que la proposition Protected Audience progresse, 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.



Interagir et donner votre avis

Obtenir de l'aide

Pour poser une question sur votre implémentation, sur la démonstration ou sur la documentation : * Signaler un nouveau problème dans le dépôt privacy-sandbox-dev-support Veillez à sélectionner le modèle de problème pour Protected Audience. * Signalez un problème dans le dépôt du code de démonstration sur GitHub. * Pour des questions plus générales sur la façon de traiter vos cas d'utilisation avec l'API, signalez un problème dans le dépôt de propositions.

Pour les bugs et les problèmes liés à l'implémentation de l'API Protected Audience dans Chrome : * Consultez les problèmes existants signalés pour l'API. * Signalez un nouveau problème sur crbug.com/new.

Recevoir les dernières informations

  • Pour être informé des changements d'état dans l'API, rejoignez la liste de diffusion pour les développeurs.
  • Pour suivre de près toutes les discussions en cours concernant l'API, cliquez sur le bouton Watch (Regarder) sur la page de la proposition sur GitHub. Pour ce faire, vous devez disposer d'un compte GitHub ou en créer un.
  • Pour recevoir des informations générales sur la Privacy Sandbox, abonnez-vous au flux RSS [Progress in the Privacy Sandbox].

En savoir plus

Photo de Ray Hennessy sur Unsplash.