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

Ce document présente une vue d'ensemble de l'exécution d'une enchère 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 à un seul vendeur est appelée "mise aux enchères de composants", qui peut fournir des candidats publicitaires à 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 la présentation de l'API Protected Audience pour en savoir plus sur la façon dont les vendeurs exécutent les enchères sur l'appareil.

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

1. Un utilisateur consulte un site qui diffuse des annonces.
2. Le code du vendeur s'exécute navigator.runAdAuction(). Cela indique l'espace publicitaire à vendre et les annonceurs 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, l'URL d'une création publicitaire pertinente et d'autres données. Le script d'enchères peut interroger le service clés/valeurs de l'acheteur pour obtenir des données en temps réel, telles que le budget restant de la campagne publicitaire.
4. Le code du vendeur évalue chaque enchère et sélectionne un gagnant. Cette logique utilise la valeur de l'enchère et d'autres données pour déterminer l'attractivité d'une enchère. Les annonces qui ne peuvent pas battre l'annonce contextuelle gagnante 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 forme de 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 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 exécutées à l'avance afin que la création publicitaire soit prête lorsque l'emplacement publicitaire devient visible.

Les vendeurs lancent l'enchère publicitaire, attribuent un score aux annonces candidates à l'aide d'une logique personnalisée fournie sous forme de fonction scoreAd() et sont responsables de la communication des 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 à :

• Éditeur de contenu, agissant pour son propre compte afin d'héberger du contenu publicitaire sur son site Web
• Plates-formes côté offre (SSP), qui travaillent avec l'éditeur d'annonces et fournissent d'autres services
• Scripts tiers agissant pour le compte d'éditeurs afin de leur permettre de participer aux enchères publicitaires.

Conditions préalables pour organiser une vente aux enchères

Un vendeur a besoin de deux fonctions JavaScript définies pour exécuter une enchère :

• scoreAd(), qui évalue un candidat publicitaire
• reportResult(), qui gère la communication des résultats des enchères au vendeur lui-même

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

scoreAd()

Un vendeur doit définir une fonction scoreAd() qui est diffusée à partir d'un point de terminaison qui lui appartient. 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 sont des métadonnées arbitraires sur la création publicitaire fournies par l'acheteur. Il s'agit d'un objet sérialisable JSON dont les vendeurs et les acheteurs devront définir et approuver 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 de la mise aux enchères à partir du serveur clé/valeur du vendeur. La plate-forme utilisera le renderUrl de l'annonce candidate comme clé pour cette recherche.
• browserSignals, qui est un objet construit par le navigateur, y compris les informations que le navigateur connaît et que le script d'enchères du vendeur peut vouloir vérifier.
• directFromSellerSignals est un objet qui peut 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 le renderUrl de l'annonce candidate est disponible via les signaux suivants :

{ '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 qui lui appartient. 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 les 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 reporting de l'acheteur gagnant. Cela doit inclure toutes les informations pertinentes que le vendeur peut fournir sur les enchères et dont l'acheteur a besoin pour ses rapports.

Exécuter une enchère de l'API Protected Audience

Un vendeur doit suivre quatre étapes principales pour organiser une enchère. Notez que ces étapes supposent que le marchand 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 à l'enchère, ainsi que de fournir les signaux qui peuvent être pertinents lors de la génération des enchères ou de la notation des annonces.
2. Exécutez l'enchère en appelant navigator.runAdAuction() et 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 les évaluent. L'objectif de cette étape est de créer un candidat-annonce qui peut être affiché.
3. Affichez l'annonce gagnante dans un frame ou un iframe cloisonné.
4. Signaler le résultat de l'enchère. Il existe une fonction, navigator.sendReportTo(), qui lance le signalement. Le vendeur recevra toujours un rapport sur les résultats des enchères. Seul l'acheteur qui a remporté l'enchère recevra un rapport. Pour envoyer des informations à son serveur, il utilise le reportResult() du marchand décrit plus haut dans ce guide.