Dans ce document, vous trouverez une présentation générale de l'exécution d'une mise aux enchères avec les données Protected Audience pour un seul vendeur, telles qu'elles sont utilisées dans l'itération actuelle de l'API Protected Audience. Une enchère avec un seul vendeur peut être organisée dans le cadre d'enchères plus complexes impliquant plusieurs vendeurs. Dans ce cas, l'enchère de vendeur unique est appelée"enchère de composants " et peut proposer des annonces candidates à l'enchère de premier niveau à laquelle plusieurs vendeurs participent.
Lisez le guide du développeur pour connaître le cycle de vie complet de l'API Protected Audience et consultez la présentation de l'API Protected Audience pour une discussion approfondie sur la façon dont les vendeurs effectuent des enchères sur l'appareil.
Six étapes d'une mise aux enchères publicitaires de l'API Protected Audience
- Un utilisateur visite un site qui affiche des annonces.
- Le code du vendeur exécute
navigator.runAdAuction(). Cela permet de spécifier quel espace publicitaire est à vendre et qui peut enchérir. Les vendeurs doivent également inclure un script qui évalue chaque enchère,scoreAd(). - Le code de l'acheteur invité s'exécute pour générer une enchère, l'URL d'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é-valeur de l'acheteur.
- Le code du vendeur attribue un score à chaque enchère et sélectionne un gagnant. Cette logique utilise la valeur de l'enchère et d'autres données renvoient l'attrait d'une enchère. Les annonces qui ne l'emportent pas avec l'annonce contextuelle gagnante sont refusées. Le vendeur peut utiliser son propre service clé-valeur pour les données en temps réel.
- L'annonce gagnante est renvoyée sous la forme d'une valeur opaque, qui s'affiche dans un frame cloisonné. Le vendeur et l'éditeur ne peuvent pas voir cette valeur.
- L'enchère est signalée au vendeur et aux acheteurs gagnants.
Une enchère peut avoir lieu lorsqu'un utilisateur accède à une page qui affiche une annonce. Les enchères peuvent être lancées à l'avance afin que la création soit prête lorsque l'espace publicitaire apparaît.
Les vendeurs lancent les enchères publicitaires, évaluent les annonces candidates à l'aide d'une logique personnalisée fournie via une fonction scoreAd(). Ils sont ensuite chargés de communiquer les résultats de l'enchère à eux-mêmes ainsi qu'à l'acheteur gagnant. Les vendeurs peuvent également appliquer des règles applicables aux éditeurs et filtrer les annonces en fonction de la qualité des annonces à l'aide de leur fonction scoreAd().
Un vendeur peut faire référence aux éléments suivants:
- Éditeurs de contenu, agissant en leur nom pour héberger le contenu publicitaire sur leur site Web
- Plates-formes côté offre (SSP) en collaborant avec l'éditeur d'annonces et en fournissant d'autres services
- Scripts tiers agissant pour le compte d'un éditeur afin de permettre la participation aux enchères publicitaires.
Conditions préalables à la mise aux enchères
Un vendeur a besoin de deux fonctions JavaScript définies pour lancer une mise aux enchères:
scoreAd(), qui évalue une annonce candidatereportResult(), qui gère la transmission du résultat de la mise aux enchères au vendeur lui-même
Ces scripts doivent être diffusés depuis un seul point de terminaison appartenant au vendeur.
scoreAd()
Un vendeur doit définir une fonction scoreAd() diffusée à partir d'un point de terminaison dont il est propriétaire. 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 fournies par l'acheteur concernant la création publicitaire. Il s'agit d'un objet JSON sérialisable que les vendeurs et les acheteurs doivent définir et accepter la structure.bid, qui est une valeur numérique représentant l'enchère.auctionConfig, qui est la configuration d'enchères utilisée pour lancer l'enchère.trustedScoringSignals, qui sont des signaux lus au moment de la mise aux enchères à partir du serveur clé-valeur du vendeur. La plate-forme utilisera l'renderUrlde l'annonce candidate comme clé pour cette recherche.browserSignals, qui est un objet construit par le navigateur, y compris des informations connues de celui-ci et que le script d'enchères du vendeur est susceptible de vouloir vérifier.directFromSellerSignalsest un objet qui peut contenir les champs suivants : **sellerSignals: commeauctionConfig.sellerSignals, mais transmis à l'aide du mécanismedirectFromSellerSignals. **auctionSignals: semblable àauctionConfig.auctionSignals, mais transmis à l'aide du mécanismedirectFromSellerSignals.
Voici un exemple de browserSignals. Notez que le 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() diffusée à partir d'un point de terminaison dont il est propriétaire. 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 est la configuration d'enchères utilisée pour lancer l'enchère.browserSignals, qui est un objet construit par le navigateur, y compris des informations connues de celui-ci et que le script d'enchères du vendeur est susceptible de vouloir vérifier. Il s'agit du même objet transmis à la fonctionscoreAds().
reportResult() renvoie signalsForWinner, qui est un objet JSON arbitraire transmis à la fonction de création de rapports de l'acheteur ayant remporté l'enchère. Elles doivent inclure toutes les informations pertinentes que le vendeur peut fournir sur l'enchère dont l'acheteur a besoin pour ses rapports.
Lancer une mise aux enchères de l'API Protected Audience
Pour lancer une mise aux enchères, un vendeur doit suivre quatre étapes principales. 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.
- Configurez la mise aux enchères. Cette étape inclut la création d'un objet
auctionConfig. Cela permet au vendeur de spécifier les acheteurs qui doivent participer à l'enchère, et de fournir tous les signaux qui pourraient être pertinents lors de la génération des enchères ou de l'évaluation des annonces. - Pour lancer la mise aux enchères, appelez
navigator.runAdAuction()et transmettez la configuration créée à l'étape précédente. La chaîne d'acheteurs qui génère des enchères, puis leur évaluation, est ainsi lancée. Le résultat final de cette étape est une annonce candidate qui peut être affichée pour afficher une annonce. - Affichez l'annonce gagnante dans un frame cloisonné ou dans un iFrame.
- Générez un rapport sur le résultat de la mise aux enchères. Une fonction
navigator.sendReportTo()permet de lancer la création de rapports. Le vendeur reçoit toujours un rapport sur les résultats des enchères. Seul l'acheteur ayant remporté l'enchère reçoit un rapport. Elle utilise lereportResult()du vendeur décrit précédemment dans ce guide pour signaler à son serveur.