Guide du développeur de l'API FLEDGE

À qui s'adresse cet article ?

Cet article est une référence technique à l'itération actuelle de l'API Protected Audience expérimentale.

Qu'est-ce que Protected Audience ?

L'API Protected Audience est une proposition de la Privacy Sandbox destinée à diffuser le remarketing et les audiences personnalisées, conçu de sorte qu'il ne soit pas adapté des tiers pour suivre le comportement de navigation des utilisateurs sur les sites. L'API permet les enchères sur l'appareil le navigateur, afin de choisir des annonces pertinentes pour les sites Web précédemment visités par l'utilisateur.

Protected Audience est le premier test à être implémenté dans Chromium dans le TURTLEDOVE.

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

<ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder"></ph> Illustration offrant un aperçu de chaque étape du cycle de vie de FLEDGE
Cycle de vie de FLEDGE

Comment puis-je essayer Protected Audience ?

Démonstration de Protected Audience

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

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

Participer à une phase d'évaluation de Protected Audience

Une phase d'évaluation de la pertinence et des mesures de la Privacy Sandbox disponible dans la version bêta de Chrome 101.0.4951.26 et ultérieure sur ordinateur pour l'API Protected Audience. Topics ; et Attribution Reporting.

Pour y participer, demandez un jeton d'évaluation Origin Trial.

Une fois inscrit à l'essai, vous pouvez tester l'API JavaScript Protected Audience 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) ; Ensuite, lancez des enchères publicitaires pour sélectionner et afficher une annonce.

La démonstration de l'API Protected Audience fournit un exemple basique de déploiement de l'API Protected Audience 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 navigator.joinAdInterestGroup()) par un propriétaire de groupe de centres d'intérêt, devra fournir un jeton correspondant à son origine.

Informations proposées pour la première phase d'évaluation de l'API Protected Audience fournit plus de détails sur les objectifs du premier essai et explique les fonctionnalités prises en charge.

Tester cette API

Vous pouvez tester Protected Audience pour un seul utilisateur dans la version bêta 101.0.4951.26 de Chrome ou version ultérieure sur ordinateur:

  • En activant toutes les API Ad Privacy sous chrome://settings/adPrivacy
  • 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 options définies.

Pour utiliser <fencedframe> afin d'afficher des annonces:

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

Pour utiliser <iframe> afin d'afficher des annonces:

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

Incluez l'indicateur BiddingAndScoringDebugReportingAPI pour activer les méthodes temporaires de création de rapports de perte/gagnement de débogage.

Exécuter Chromium avec des indicateurs explique comment définir des indicateurs lors de l'exécution de Chrome et d'autres navigateurs basés sur Chromium à partir de la commande ligne. La liste complète des indicateurs Protected Audience est disponible sur Recherche de code Chromium

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

L'API Protected Audience est disponible derrière les flags de fonctionnalité dans Chromium en tant que pour tester les fonctionnalités suivantes de la proposition Protected Audience:

  • Groupes de centres d'intérêt: stockés par le navigateur, avec les métadonnées associées pour configurer les enchères des annonces et le rendu.
  • Enchères sur l'appareil par les acheteurs (DSP ou annonceur): basées sur les groupes de centres d'intérêt et les signaux enregistrés auprès du vendeur.
  • Sélection des annonces sur l'appareil par le vendeur (SSP ou éditeur): en fonction des enchères et des des métadonnées aux acheteurs.
  • Rendu des annonces dans une version temporairement assouplie des cadres cloisonnés: avec accès au réseau et pour l'affichage des annonces.

La vidéo explicative sur l'API fournit plus de détails. sur la prise en charge et les contraintes des fonctionnalités.

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

Par défaut, l'implémentation actuelle de Protected Audience autorise l'appel de joinAdInterestGroup() depuis n'importe où sur la page, même à partir d'iFrames inter-domaines. À l'avenir, une fois que les propriétaires de sites auront eu le temps pour ajuster ses règles d'autorisation pour les cadres iFrame inter-domaines, elle prévoit d'interdire les appels provenant des sur plusieurs domaines, comme expliqué dans notre vidéo d'explication.

Service clé-valeur

Lors des enchères publicitaires Protected Audience, le navigateur peut accéder à un service clé-valeur qui renvoie des paires clé-valeur simples pour fournir des informations à un acheteur publicitaire, budget de la campagne. La proposition Protected Audience exige que ce serveur "n'effectue aucune journalisation au niveau des événements et n'a aucun autre effet secondaire basé sur ces de recherche".

Le code du service clé-valeur Protected Audience est désormais disponible dans un dépôt GitHub de la Privacy Sandbox. Ce service peut être utilisé par les développeurs Chrome et Android. Consultez l'annonce de 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 clé-valeur Open Source Protected Audience qui s'exécutent dans des environnements d'exécution sécurisés pour récupérer des données en temps réel.

Afin de garantir que l'écosystème dispose de suffisamment de temps pour effectuer des tests, nous ne prévoyons pas d'exiger l'utilisation des TEE ou services clés-valeurs Open Source avant quelque temps après l'abandon des cookies tiers. Nous informerons bien les développeurs qu'ils doivent commencer les tests et l'adoption avant cette transition.

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 puis-je désactiver Protected Audience ?

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

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

À terme, Protected Audience exigera des sites qu'ils définissent des règles d'autorisation pour permettre la disponibilité de la fonctionnalité Protected Audience. Ainsi, des tiers arbitraires ne pourront pas utiliser l'API sans l'autorisation connaissances. 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 la règle d'autorisation appropriée pour bloquer l'accès.

Il existe deux règles d'autorisation Protected Audience qui peuvent être définies indépendamment:

  • join-ad-interest-group active/désactive la fonctionnalité permettant d'ajouter un navigateur aux groupes de centres d'intérêt
  • run-ad-auction active/désactive la fonctionnalité permettant de lancer des enchères sur l'appareil

Vous pouvez désactiver complètement l'accès aux API Protected Audience dans les contextes propriétaires en spécifiant les éléments suivants : règle d'autorisation 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>

La section Règles concernant les autorisations d'évaluation de la première phase d'évaluation de l'API Protected Audience proposée fournit plus de détails.

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 n'importe quelle mécanismes suivants:

  • Désactiver les essais Privacy Sandbox dans les paramètres de Chrome: Paramètres > Sécurité et confidentialité > Privacy Sandbox Elle est également accessible à l'adresse chrome://settings/adPrivacy.
  • Désactivez les cookies tiers dans les paramètres de Chrome: Paramètres > Sécurité et confidentialité.
  • Définissez l'option Cookies et autres données des sites sur "Bloquer les cookies tiers". ou "Bloquer tous les cookies" de chrome://settings/cookies.
  • Utilisez le mode navigation privée.

La vidéo explicative de l'API Protected Audience fournit plus de détails sur les éléments de conception de l'API et explique comment l'API cherche à atteindre les objectifs de confidentialité.

Déboguer les Worklets Protected Audience

À partir de Chrome Canary 98.0.4718.0, il est possible de déboguer les Worklets 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 Event Listener Breakpoints (Points d'arrêt de l'écouteur d'événements). dans le panneau Sources.

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

Lorsqu'un point d'arrêt est déclenché, l'exécution est interrompue avant la première instruction au niveau supérieur de la script de Worklet. Vous pouvez utiliser des points d'arrêt ou des commandes d'étape standards pour accéder aux enchères, aux scores et aux rapports. elle-même.

Les scripts de Worklet actifs s'affichent également dans le panneau "Fils de discussion".

Capture d&#39;écran de Outils de développement dans Chrome Canary, avec le volet &quot;Threads&quot; encadré dans le panneau &quot;Sources&quot; et affichant la version actuelle script Worklet mis en veille.

Étant donné que certains Worklets peuvent s'exécuter en parallèle, plusieurs threads peuvent se retrouver dans la "paused" l'indiquer ici ; vous pouvez utiliser la liste des threads pour passer d'un thread à l'autre, et les reprendre ou les inspecter de plus près approprié.

Observer les événements Protected Audience

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

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

La Panneau &quot;Application des outils de développement&quot; dans Chrome Canary affichant des informations sur un groupe de centres d&#39;intérêt Protected Audience participer à l&#39;événement.

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

<ph type="x-smartling-placeholder">
</ph> La Panneau &quot;Application des outils de développement&quot; dans Chrome Canary affichant des informations sur l&#39;enchère Protected Audience et victoires.

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.

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

Illustration montrant une personne visitant le site d&#39;un fabricant de vélos personnalisés dans un navigateur sur son ordinateur portable.

Imaginez qu'un utilisateur consulte 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 fabriqué à la main. Vous bénéficiez ainsi un fabricant de vélos avec 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. JavaScript le code joinAdInterestGroup() est exécuté dans le navigateur.

Section explicative:Les navigateurs enregistrent les 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 d'intérêt liste des groupes dont le navigateur est membre. Dans cet exemple, le groupe s'appelle custom-bikes. le propriétaire est dsp.example. Le propriétaire du groupe d'intérêt (dans ce cas, la DSP) est acheteur à la mise en concurrence des annonces décrite à l'étape 4. L'appartenance à un groupe de centres d'intérêt est stockée par le navigateur sur l'appareil de l'utilisateur et n'est pas partagée avec le le fournisseur du navigateur ou toute autre personne.

joinAdInterestGroup() a besoin de l'autorisation de:

  • Le site visité
  • 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() de ont la même origine que le site consulté, c'est-à-dire qu'elles ont la même origine que le frame de premier niveau du page actuelle. Les sites peuvent utiliser un en-tête de règle d'autorisation Protected Audience Directive join-ad-interest-group pour désactiver les appels joinAdInterestGroup().

Cross-origin: appel de joinAdInterestGroup() à partir d'origines différentes de l'actuelle la page ne peut réussir que si le site consulté a défini une règle d'autorisations qui autorise les appels à joinAdInterestGroup() à partir d'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 dsp.example L'iFrame peut appeler joinAdInterestGroup() pour les groupes de centres d'intérêt appartenant à dsp.example.

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

Utiliser navigateur.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 indique la durée du groupe d'intérêt, qui est limitée à 30 jours. jours. Les appels successifs écrasent les valeurs précédemment stockées.

Propriétés des groupes 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 du code JavaScript d'enchères dans le Worklet.
biddingWasmHelperUrl** Facultatif* 'https://dsp.example/bid/custom-bikes/bid.wasm' URL du code WebAssembly généré par biddingLogicUrl.
dailyUpdateUrl** Facultatif 'https://dsp.example/bid/custom-bikes/update' URL qui renvoie un fichier JSON pour mettre à jour les attributs des groupes 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 à un serveur de confiance clé-valeur.
userBiddingSignals Facultatif {...} Métadonnées supplémentaires que le propriétaire peut utiliser lors de la définition des enchères.
ads Facultatif* [bikeAd1, bikeAd2, bikeAd3] Annonces susceptibles d'être diffusé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. biddingLogicUrl et ads sont facultatifs, mais obligatoires pour participer à une mise aux enchères. Il peut y avoir des cas d'utilisation créer 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 ajouter un navigateur à un groupe de centres d'intérêt pour une campagne qui n'est pas encore diffusée, ou pour certains toute utilisation ultérieure, ou leur budget publicitaire peut être temporairement épuisé.

** Les URL biddingLogicUrl, biddingWasmHelperUrl, dailyUpdateUrl et trustedBiddingSignalsUrl doivent avoir la même origine que le propriétaire. Les URL ads et adComponents ne sont pas soumises à cette contrainte.

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

dailyUpdateUrl spécifie un serveur Web qui renvoie un fichier JSON définissant les propriétés des groupes d'intérêt. correspondant à l'objet de groupe de centres d'intérêt transmis à navigator.joinAdInterestGroup(). Ce fournit au propriétaire du groupe un mécanisme permettant de mettre à jour périodiquement les attributs du un groupe d'intérêt. Dans la mise en œuvre actuelle, les attributs suivants peuvent être modifiés:

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

Tout champ non spécifié dans le fichier JSON ne sera pas écrasé. Seuls les champs spécifiés dans le fichier JSON sont mis à jour, alors que l'appel de navigator.joinAdInterestGroup() écrase tous les groupes de centres d'intérêt existants.

Les mises à jour reposent sur le principe du "meilleur effort" et peuvent échouer dans les conditions suivantes:

  • Délai avant expiration de la requête réseau (30 secondes actuellement).
  • Autre défaillance du réseau.
  • Échec de l'analyse JSON.

Les mises à jour peuvent également être annulées si leur durée de mise à jour est trop longue. n'impose aucune limitation du débit pour les mises à jour annulées (résidentes). Les mises à jour sont limitées à un (1 par jour au maximum). Les mises à jour qui échouent en raison d'erreurs réseau sont relancées au bout d'une heure. les mises à jour qui échouent en raison d'une déconnexion d'Internet font l'objet d'une nouvelle tentative 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 tant que la limite de débit n'a pas été atteinte (1 jour actuellement) s'est écoulée. La limite de débit est réinitialisée si navigator.joinAdInterestGroup() est rappelé pour le même groupe de centres d'intérêt owner et name.

Mises à jour automatiques

Tous les groupes d'intérêt chargés pour une mise aux enchères sont mis à jour automatiquement une fois la mise aux enchères terminée. soumis aux mêmes limites de débit que les mises à jour manuelles. Pour chaque propriétaire possédant au moins un groupe de centres d'intérêt à des enchères, la méthode navigator.updateAdInterestGroups() est appelée à 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, arbitraires de métadonnées pouvant être utilisées au moment de l'enchère. Exemple :

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

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

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

Le script 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 le 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 d'intérêt peut être modifié via dailyUpdateUrl.)


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


  • perBuyerSignals Comme pour auctionSignals, une propriété de la configuration des enchères argument transmis à navigator.runAdAuction() par le vendeur. Cela peut fournir du contexte du serveur de l'acheteur à propos de la page. Si le vendeur est une SSP, effectue un appel d'enchères en temps réel vers les serveurs de l'acheteur et transmet la réponse. contacte directement le serveur de l'acheteur. Si c'est le cas, l'acheteur peut vérifier un code cryptographique signature de ces signaux dans generateBid() afin d'assurer une protection contre la falsification.


  • trustedBiddingSignals Un objet dont les clés sont les trustedBiddingSignalsKeys pour la groupe 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 la page le contexte (tel que l'hostname de la page actuelle, que le vendeur pourrait falsifier) et les données pour le groupe d'intérêt lui-même (par exemple, l'enregistrement de la date à laquelle le groupe a précédemment remporté une enchère, afin de 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 de l'objet paramètres. 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 concernant l'annonce, telles que les informations que le vendeur s'attend à obtenir sur cette enchère ou dans votre création publicitaire. Le vendeur](/privacy-sandbox/resources/glossary#ssp) utilise ces informations pour ses enchères et ses décisions. dans votre création publicitaire. Le vendeur utilise ces informations pour ses enchères et ses décisions. logique.


  • bid 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 être exprimées dans l'unité choisie par le vendeur (par exemple, "USD par mille"). Si l'enchère est nulle ou négative, le groupe d'intérêt ne participera pas au aux enchères du vendeur. Grâce à ce mécanisme, l'acheteur peut appliquer n'importe quelle règle d'annonceur leurs annonces peuvent être diffusées ou non.


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


  • adComponents Une liste facultative de 20 composants maximum pour des annonces composées de plusieurs éléments, provenant de la propriété adComponents de l'argument de groupe d'intérêts 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 qu'un navigateur soit supprimé d'un groupe de centres d'intérêt. Dans d'autres le navigateur est invité à supprimer le groupe d'intérêt de la liste de ceux dont il fait partie.

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

Si un utilisateur revient sur le site et 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. Il consulte un site qui vend de l'espace publicitaire.

Illustration représentant une personne visitant un site Web d&#39;actualités dans le navigateur de son ordinateur portable Le site comporte un espace publicitaire vide.

Plus tard, l'utilisateur visite un site qui vend des espaces publicitaires, dans cet exemple un site Web d'actualités. Le site comporte l'inventaire publicitaire, qu'il vend via le programmatique à l'aide de enchères en temps réel.

4. Mise en concurrence des annonces effectuée dans le navigateur

Illustration représentant une personne qui consulte un site Web d&#39;actualités dans le navigateur de son ordinateur portable. Une annonce à l&#39;aide de l&#39;API Protected Audience.

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

Les enchères publicitaires sont probablement menées par la SSP de l'éditeur. l'éditeur lui-même. L'objectif de la mise en concurrence est de sélectionner l'annonce la plus appropriée pour l'espace publicitaire disponible sur la page active. L'enchère tient compte des groupes d'intérêt navigateur, ainsi que les données des acheteurs de l'espace publicitaire et des vendeurs des services clé-valeur.

Le vendeur d'espace publicitaire envoie une demande au navigateur de l'utilisateur pour lancer une mise en concurrence des annonces 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 un URN (urn:uuid:<something>) qui représente le le résultat des enchères publicitaires. 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 examine chaque annonce, ainsi que l'enchère qui lui est associée. des métadonnées, une par une, puis lui attribue un score numérique de désirabilité.

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 code 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 invités à enchérir dans l'enchère.
auctionSignals Facultatif {...} Informations sur le vendeur concernant le contexte de la page, le type d'enchères, etc.
sellerSignals Facultatif {...} Informations basées sur les paramètres de l'éditeur, envoi d'une demande d'annonce contextuelle, 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 concernant la page de chaque acheteur, provenant de leur serveur.
perBuyerTimeouts Facultatif 50 Durée d'exécution maximale (ms) des scripts generateBid() d'un acheteur spécifique.
componentAuctions Facultatif [{'seller': 'https://www.some-other-ssp.com',
  'decisionLogicUrl': ..., ...},
  ...]		 Autres configurations pour les enchères de composants.

* Le vendeur peut spécifier interestGroupBuyers: '*' pour autoriser tous les groupes d'intérêt à définir des enchères. Les annonces sont ensuite acceptées ou refusées en fonction 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. Lisez l'article sur la mise en concurrence de la section "Participants" Explications sur Protected Audience.

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

Le code decisionLogicUrl (une propriété de l'objet de configuration des enchères transmis à runAdAuction()) doit inclure une fonction scoreAd(). Elle est exécutée une fois pour chaque annonce pour déterminer son souhait.

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 Objet de configuration des enchères transmis à navigator.runAdAuction().

  • trustedScoringSignals Valeurs récupérées au moment de l'enchère sur le serveur de confiance du vendeur représentant l'opinion du vendeur sur l'annonce

  • browserSignals Objet construit par le navigateur, comprenant les informations que celui-ci connaît et que le script d'enchères du vendeur est susceptible de 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. Fait partie de sa logique scoreAd() consiste à rejeter toute annonce qui ne peut pas battre la annonce contextuelle gagnante.

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

Illustration représentant une personne qui consulte un site Web d&#39;actualités dans le navigateur de son ordinateur portable. Une annonce à l&#39;aide de l&#39;API Protected Audience, et un participant obtient des données 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'enchères publicitaires, le vendeur de l'espace publicitaire peut obtenir des données en temps réel sur des créations spécifiques en fonction de en envoyant une requête à un service clé-valeur à l'aide de la propriété trustedScoringSignalsUrl de un argument de configuration des enchères transmis à navigator.runAdAuction(), avec les clés à partir des propriétés renderUrl de toutes les entrées des champs ads et adComponents de toutes de groupes d'intérêts lors des enchères.

De même, un acheteur d'espace publicitaire peut demander des données en temps réel au service clé-valeur à l'aide de la méthode Propriétés trustedBiddingSignalsUrl et trustedBiddingSignalsKeys de l'argument de groupe de centres d'intérêt transmis à navigator.joinAdInterestGroup().

Lorsque la méthode runAdAuction() est appelée, le navigateur envoie une demande au serveur de confiance de chaque acheteur d'annonces. La 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 issue 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 s'affiche.

Illustration représentant une personne qui consulte un site Web d&#39;actualités dans le navigateur de son ordinateur portable. Une annonce pour un vélo (20% de remise) s&#39;affiche, avec un cadenas en haut pour indiquer que l&#39;annonce est diffusée cadre cloisonné.

Section explicative:Les navigateurs diffusent l'annonce gagnante

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

7. Le résultat de l'enchère est indiqué

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

Résultat des rapports du vendeur

Section explicative:Rapports sur l'affichage du vendeur

Le code JavaScript du vendeur fourni à decisionLogicUrl (qui a également fourni scoreAd()) peut inclure une fonction reportResult() pour indiquer le résultat de l'enchère ;

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

Les arguments transmis à cette fonction sont les suivants:


  • auctionConfig Objet de configuration des enchères 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 l'enchère fonction reportWin().

Résultat des rapports sur l'enchérisseur ayant remporté l'enchère

Section explicative:Créer des rapports d'acheteur sur l'affichage et les événements d'annonce

Le code JavaScript de l'enchérisseur gagnant (qui a également fourni generateBid()) peut inclure un reportWin() pour indiquer le résultat des enchères.

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

Les arguments transmis à cette fonction sont les suivants:

  • auctionSignals et perBuyerSignals
    Les mêmes valeurs ont été transmises à generateBid() pour l'enchérisseur gagnant.

  • sellerSignals La valeur renvoyée pour reportResult(), qui donne au vendeur 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 temporaire de rapports de perte/gagnement

Pour créer des rapports sur les enchères, deux méthodes sont disponibles temporairement dans Chrome:

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

Chacune de ces méthodes utilise un seul argument: une URL à récupérer une fois l'enchère terminée. Ils peuvent être appelé plusieurs fois, à la fois dans scoreAd() et generateBid(), avec des arguments d'URL différents.

Chrome n'envoie des rapports de débogage de perte/gagnement que lorsqu'une enchère est terminée. Si une enchère est annulée (en raison d'une nouvelle navigation, par exemple), aucun rapport ne sera généré.

Ces méthodes sont disponibles par défaut dans Chrome. Pour pouvoir tester les méthodes, activez toutes les API Ad Privacy sous chrome://settings/adPrivacy. 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'option BiddingAndScoringDebugReportingAPI. Si le n'est pas activé, les méthodes seront toujours disponibles, mais ne feront rien.

8. Un clic sur une annonce est enregistré

Illustration montrant une personne cliquant sur une annonce pour un vélo dans un cadre clôturé, sur un site Web d&#39;actualités, avec un rapport aux vendeurs et aux acheteurs.

Un clic sur une annonce affichée dans un cadre cloisonné est enregistré. Pour en savoir plus sur comment cela pourrait fonctionner, consultez Rapports sur les annonces utilisant des cadres cloisonnés.


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 au sein de la famille de propositions TURTLEDOVE.

Protected Audience suit les principes généraux de TURTLEDOVE. Certaines publicités en ligne reposent sur la diffusion d'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, l'annonceur avait l'habitude d'identifier une personne spécifique lorsqu'elle parcourait des sites Web. C'est une préoccupation majeure pour le Web d'aujourd'hui.

L'initiative TURTLEDOVE consiste à 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 détient les informations sur ce que l'annonceur pense qu'un qui intéresse la personne.
  • Les annonceurs peuvent diffuser des annonces en fonction d'un centre d'intérêt, mais ne peuvent pas le combiner à d'autres des informations sur une personne, en particulier son identité et la page qu'il consulte.

Protected Audience est né de TURTLEDOVE et d'un ensemble de propositions de modifications associées afin de mieux répondre aux besoins des développeurs qui utiliseront l'API:

  • Dans SPARROW: Criteo a proposé d'ajouter une 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.
  • TERN de NextRoll et Magnite PARROT ces propositions décrivent les différents rôles des acheteurs et des vendeurs dans le système d'enchères sur l'appareil. Le flux d'enchères/d'évaluation des annonces de Protected Audience est basé sur ce travail.
  • Les règles basées sur les résultats et TURTLEDOVE au niveau du produit modifications apportées ont amélioré le modèle d'anonymat et les fonctionnalités de personnalisation des enchères sur l'appareil
  • PARAKEET est Proposition de Microsoft pour un service publicitaire de type TURTLEDOVE qui repose sur un serveur proxy s'exécutant dans un TEE entre le navigateur et les fournisseurs AdTech, afin d'anonymiser les demandes d'annonces et de renforcer la confidentialité. propriétés. Protected Audience n'a pas adopté ce modèle de proxy. Nous déployons les API JavaScript pour PARAKEET et Protected Audience, s'alignent sur les futurs travaux visant à combiner davantage les meilleures technologies des deux propositions.

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

Quelle est la configuration de navigateur disponible ?

Les utilisateurs peuvent modifier 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. Pendant les tests initiaux, les utilisateurs seront vous pouvez utiliser ce paramètre de la Privacy Sandbox de haut niveau pour désactiver Protected Audience. Chrome prévoit d'autoriser 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 le Web les sites qu'ils ont consultés. Comme pour les technologies de la 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 acteurs.

Nous continuerons de mettre à jour les paramètres disponibles dans Chrome à mesure que la proposition Protected Audience sera en cours, en fonction sur les tests et les commentaires. À l'avenir, nous prévoyons de proposer des paramètres plus précis pour gérer 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 et que l'appartenance est sont supprimées lorsque les utilisateurs effacent les données de leur site.



Interagir et partager des commentaires

Obtenir de l'aide

Pour toute question concernant votre implémentation, la démonstration ou la documentation:

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

Recevoir les dernières informations

En savoir plus

Photo de Ray Hennessy sur Unsplash.