Lancer une mise aux enchères basée sur un navigateur avec un seul vendeur

bookmark_border Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Ce document présente une vue d'ensemble du lancement d'enchères avec des données Protected Audience pour un seul vendeur, comme utilisé dans l'itération actuelle de l'API Protected Audience. Une enchère avec un seul vendeur peut être exécutée dans le cadre d'une enchère plus complexe impliquant plusieurs vendeurs. Dans ce cas, la mise aux enchères avec un seul vendeur est appelée "enchère de composant". Elle peut fournir des annonces candidates à la "mise aux enchères de premier niveau" à laquelle participent plusieurs vendeurs.

Consultez le guide du développeur pour découvrir le cycle de vie complet de l'API Protected Audience, et consultez la présentation de l'API Protected Audience pour en savoir plus sur la façon dont les vendeurs exécutent des enchères sur l'appareil.

Six étapes d'une enchère publicitaire de l'API Protected Audience

1. Un utilisateur consulte un site qui diffuse des annonces.
2. Le code du vendeur exécute navigator.runAdAuction(). Il spécifie l'espace publicitaire à vendre et les utilisateurs autorisés à enchérir. Les vendeurs doivent également inclure un script qui évalue chaque enchère, scoreAd().
3. Le code de l'acheteur invité s'exécute pour générer une enchère, une URL pour une création publicitaire pertinente et d'autres données. Le script d'enchères peut interroger des données en temps réel, telles que le budget restant de la campagne publicitaire, à partir du service clés-valeurs de l'acheteur.
4. Le code du vendeur attribue une note à chaque enchère et sélectionne un gagnant. Cette logique utilise la valeur de l'enchère et d'autres données pour renvoyer la désirabilité d'une enchère. Les annonces qui ne peuvent pas battre l'annonce gagnante contextuelle sont refusées. Le vendeur peut utiliser son propre service clé-valeur pour les données en temps réel.
5. L'annonce gagnante est renvoyée sous la forme d'une valeur opaque, qui s'affiche dans un cadre clôturé. Ni le vendeur, ni l'éditeur ne pourront voir cette valeur.
6. L'enchère est communiquée au vendeur et aux acheteurs ayant remporté l'enchère.

Une mise aux enchères peut avoir lieu lorsqu'un utilisateur accède à une page affichant une annonce. Les enchères peuvent être lancées à l'avance afin que la création publicitaire soit prête lorsque l'emplacement publicitaire s'affiche.

Les vendeurs lancent l'enchère sur les annonces, attribuent un score aux annonces candidates à l'aide d'une logique personnalisée fournie en tant que fonction scoreAd() et sont chargés de communiquer les résultats de l'enchère à eux-mêmes ainsi qu'à l'acheteur gagnant. Les vendeurs peuvent également appliquer les règles des éditeurs et filtrer la qualité des annonces à l'aide de leur fonction scoreAd().

Un vendeur peut faire référence aux éléments suivants:

• Éditeurs de contenu qui hébergent eux-mêmes des contenus publicitaires sur leur site Web
• Plates-formes côté offre (SSP), qui collaborent avec l'éditeur d'annonces et fournissent d'autres services
• Scénarios tiers, qui agissent pour un éditeur afin de permettre sa participation aux enchères d'annonces.

Prérequis pour lancer une mise aux enchères

Pour lancer une mise aux enchères, un vendeur doit définir deux fonctions JavaScript:

• scoreAd(), qui attribue une note à une annonce candidate
• reportResult(), qui gère le reporting du résultat de l'enchère au vendeur lui-même

Ces scripts doivent être diffusés à partir d'un seul point de terminaison appartenant au vendeur.

scoreAd()

Un vendeur doit définir une fonction scoreAd() qui est diffusée à partir d'un point de terminaison qu'il possède. Le point de terminaison est spécifié dans la configuration des enchères en tant que decisionLogicUrl. La fonction scoreAd() a la signature suivante:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

Les paramètres scoreAd() sont les suivants:

• adMetaData, qui correspond à des métadonnées arbitraires sur la création publicitaire fournie par l'acheteur. Il s'agit d'un objet sérialisable JSON que les vendeurs et les acheteurs devront définir et convenir de la structure.
• bid, qui est une valeur numérique représentant l'enchère.
• auctionConfig, qui correspond à la configuration des enchères utilisée pour les exécuter.
• trustedScoringSignals, qui sont des signaux lus au moment des enchères à partir du serveur clé-valeur du vendeur. La plate-forme utilisera l'renderUrl de l'annonce candidate comme clé pour cette recherche.
• browserSignals, qui est un objet construit par le navigateur, y compris des informations que le navigateur connaît et que le script d'enchères du vendeur peut vouloir vérifier.
• directFromSellerSignals est un objet pouvant contenir les champs suivants : ** sellerSignals: comme auctionConfig.sellerSignals, mais transmis à l'aide du mécanisme directFromSellerSignals. ** auctionSignals: comme auctionConfig.auctionSignals, mais transmis à l'aide du mécanisme directFromSellerSignals.

Voici un exemple de browserSignals. Notez que l'renderUrl de l'annonce candidate est disponible via ces signaux:

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

Un vendeur doit définir une fonction reportResult() qui est diffusée à partir d'un point de terminaison qu'il possède. Le point de terminaison est spécifié dans la configuration des enchères en tant que decisionLogicUrl. La fonction reportResult() a la signature suivante:

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

Les paramètres reportResult() sont les suivants:

• auctionConfig, qui correspond à la configuration des enchères utilisée pour les exécuter.
• browserSignals, qui est un objet construit par le navigateur, y compris des informations que le navigateur connaît et que le script d'enchères du vendeur peut vouloir vérifier. Il s'agit du même objet transmis à la fonction scoreAds().

reportResult() renvoie signalsForWinner, qui est un objet JSON arbitraire transmis à la fonction de création de rapports de l'acheteur gagnant. Cela doit inclure toutes les informations pertinentes que le vendeur peut fournir sur l'enchère que l'acheteur exige pour ses rapports.

Lancer une mise aux enchères de l'API Protected Audience

Un vendeur doit suivre quatre étapes principales pour organiser une mise aux enchères. Notez que ces étapes supposent que le vendeur a configuré un point de terminaison pour renvoyer le code JavaScript requis mentionné précédemment dans ce guide.

1. Configurez l'enchère. Cette étape inclut la création d'un objet auctionConfig. Cela permet au vendeur de spécifier les acheteurs qui doivent participer aux enchères, ainsi que de fournir tous les signaux qui pourraient être pertinents lors de la génération d'enchères ou de l'évaluation des annonces.
2. Exécutez l'enchère en appelant navigator.runAdAuction(), en transmettant la configuration créée à l'étape précédente. Cela lance la chaîne d'acheteurs qui génèrent des enchères, puis une évaluation. Le résultat final de cette étape est une annonce candidate pouvant être affichée.
3. Affichez l'annonce gagnante dans un frame ou un iframe clôturé.
4. Signalez le résultat de l'enchère. Une fonction, navigator.sendReportTo(), lance la création de rapports. Le vendeur recevra toujours un rapport sur les résultats des enchères. Seul l'acheteur ayant remporté l'enchère recevra un rapport. Pour cela, le reportResult() du vendeur décrit précédemment dans ce guide est utilisé pour envoyer un rapport à son serveur.