Découvrez comment configurer une enchère de l'API Protected Audience.
Enchères sur l'appareil organisées par les vendeurs
Une mise aux enchères Protected Audience sur l'appareil est exécutée sur un site qui vend des espaces publicitaires. La partie qui exécute la mise aux enchères est appelée "vendeur". De nombreuses parties peuvent agir en tant que vendeurs : un site peut organiser sa propre vente aux enchères d'annonces, inclure un script tiers pour l'organiser à sa place ou utiliser une SSP qui combine l'organisation d'une vente aux enchères sur l'appareil avec d'autres activités de vente aux enchères d'annonces côté serveur. Les vendeurs ont trois tâches de base à effectuer dans les enchères publicitaires sur l'appareil :
- Les vendeurs décident (a) quels acheteurs peuvent participer et (b) quelles enchères des groupes d'intérêt de ces acheteurs peuvent être incluses dans les enchères. Cela permet au vendeur d'appliquer les règles du site concernant les annonces autorisées à s'afficher sur la page.
- Les vendeurs sont responsables de la logique métier de l'enchère : code JavaScript qui prend en compte le prix et les métadonnées de chaque enchère, et calcule un score de "souhaitabilité". L'enchère avec le score de désirabilité le plus élevé remporte l'enchère.
- Les vendeurs fournissent des rapports sur les résultats des enchères, y compris des informations sur le prix de compensation et les autres paiements. Les acheteurs gagnants et perdants peuvent également générer leurs propres rapports.
Ce document explique comment configurer et lancer une enchère sur l'appareil.
Configurer une mise aux enchères d'annonces avec l'API Protected Audience
Pour lancer des enchères publicitaires avec l'API Protected Audience, la première étape consiste à configurer les enchères. Pour ce faire, créez un objet auctionConfig.
Voici un exemple de configuration :
const auctionConfig = {
seller: 'https://seller.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://buyer-1.example': {...},
'https://buyer-2.example': {...},
...
},
perBuyerTimeouts: {
'https://buyer-1.example': 50,
'https://buyer-2.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://component-seller.example',
'decisionLogicUrl': ...,
...
},
...
],
resolveToConfig: [true|false],
};
AuctionConfig établissements
Propriétés obligatoires
Les seules propriétés requises pour auctionConfigs sont seller, decisionLogicUrl et interestGroupBuyers.
| Propriété | Exemple | Rôle |
|---|---|---|
| vendeur | https://seller.example | Origine du vendeur. |
| decisionLogicUrl | https://seller.example/decision-logic.js | URL du worklet de logique de décision JavaScript pour les enchères. Ce champ doit avoir la même origine que le champ "Vendeur". |
| interestGroupBuyers | [https://buyer-1.example, https://buyer-2.example, ...] |
Origines de tous les propriétaires de groupes d'intérêt invités à enchérir lors des enchères |
Propriétés facultatives
Les autres propriétés de auctionConfigs sont facultatives.
| Propriété | Exemple | Rôle |
|---|---|---|
| trustedScoringSignalsUrl | https://seller.example/scoring-signals | URL du serveur de clés/valeurs du vendeur. Cette valeur sera interrogée lors du processus de notation des annonces, en utilisant l'URL de rendu de la création comme clé. Ce champ doit avoir la même origine que le champ "Vendeur". |
| auctionSignals | {"category":"news"} | Objet sérialisable JSON représentant les signaux disponibles pour tous les acheteurs et vendeurs participant aux enchères. |
| sellerSignals | {...} | Objet sérialisable JSON représentant les signaux disponibles uniquement pour les vendeurs. |
| perBuyerSignals | {https://dsp.example: {...}, https://another-buyer.example: {...}, ... } |
Signaux disponibles pour un acheteur spécifique. Les signaux peuvent provenir des vendeurs, mais aussi des acheteurs eux-mêmes. |
| perBuyerTimeouts | {https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...}, |
Durée d'exécution maximale en millisecondes du script generateBid() d'un acheteur spécifique. Un caractère générique sera appliqué à chaque acheteur pour lequel aucun délai d'expiration spécifique n'a été défini. |
| sellerTimeout | 100 | Durée d'exécution maximale en millisecondes d'un script scoreAd() de vendeur. |
| componentAuctions | [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] | Configurations supplémentaires pour les enchères de composants. |
| resolveToConfig | true|false | Valeur booléenne indiquant si la promesse renvoyée par runAdAuction() doit être résolue en FencedFrameConfig si la valeur est "true" (pour une utilisation dans un <fencedframe>) ou en URL urn:uuid opaque si la valeur est "false" (pour une utilisation dans un <iframe>). La valeur par défaut est "false". |
Fournir des signaux de manière asynchrone
Les valeurs de certains signaux (ceux configurés par les champs auctionSignals, sellerSignals, perBuyerSignals et perBuyerTimeouts) peuvent éventuellement être fournies non pas en tant que valeurs concrètes, mais en tant que Promesses. Cela permet à certaines parties de l'enchère, comme le chargement de scripts et de signaux fiables, et le lancement de processus de worklet isolés, de chevaucher le calcul (ou la récupération réseau) de ces valeurs. Les scripts de worklet ne verront que les valeurs résolues. Si une telle promesse est refusée, l'enchère sera abandonnée, sauf si elle a déjà échoué ou a été abandonnée d'une autre manière.
Configurer une enchère avec plusieurs vendeurs
Dans certains cas, plusieurs vendeurs peuvent souhaiter participer à une enchère, les gagnants des différentes enchères étant ensuite transmis à une autre enchère, gérée par un autre vendeur. Ces enchères distinctes transmises sont appelées "enchères de composants".
Pour faciliter ces enchères de composants, l'objet componentAuctions peut contenir des configurations d'enchères supplémentaires pour les enchères de composants de chaque vendeur. L'enchère gagnante de chacune de ces enchères de composants sera transmise à l'enchère de "niveau supérieur", qui déterminera le résultat final de l'enchère. Les auctionConfig des enchères de composants peuvent ne pas avoir leur propre componentAuctions. Lorsque componentAuctions n'est pas vide, interestGroupBuyers doit l'être. Autrement dit, pour toute enchère Protected Audience donnée, il n'y a qu'un seul vendeur et aucune enchère de composant, ou bien toutes les enchères proviennent d'enchères de composant et l'enchère de premier niveau ne peut choisir que parmi les gagnants des enchères de composant.
Exécuter les enchères
Le vendeur envoie une requête au navigateur de l'utilisateur pour lancer des enchères publicitaires en appelant navigator.runAdAuction().
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
L'appel runAdAuction() renvoie une promesse qui se résout à l'annonce. Il est impossible pour tout code sur la page de l'éditeur d'inspecter l'annonce gagnante ou d'en savoir plus sur son contenu à partir du résultat de runAdAuction(). Si le flag resolveToConfig a été défini sur "true" dans AuctionConfig, un objet FencedFrameConfig est renvoyé. Il ne peut être affiché que dans un cadre clôturé. Si le flag est défini sur "false", un URN opaque est renvoyé et peut être affiché dans un iFrame. Il est possible que runAdAuction renvoie une valeur nulle, indiquant qu'aucune annonce n'a été sélectionnée. Dans ce cas, le vendeur peut choisir d'afficher une annonce ciblée contextuellement.