Guide du vendeur: lancer des enchères publicitaires

Guide de l'API du vendeur et références pour les enchères publicitaires de l'API Protected Audience.

Cet article contient une référence technique sur les enchères publicitaires, telles qu'elles sont utilisées dans l'itération actuelle de l'API Protected Audience expérimentale.

Consultez 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 en savoir plus sur la façon dont les vendeurs exécutent des enchères sur l'appareil.

Vous n'êtes pas développeur ? Consultez la présentation de l'API Protected Audience.

Qu'est-ce que les enchères d'annonces de l'API Protected Audience ?

Une mise aux enchères d'annonces de l'API Protected Audience est un ensemble de petits programmes JavaScript que le navigateur exécute sur l'appareil de l'utilisateur pour choisir une annonce. Pour préserver la confidentialité, tout le code d'enchères publicitaires du vendeur et des acheteurs est exécuté dans des worklets JavaScript isolés qui ne peuvent pas communiquer avec le monde extérieur.

Six étapes d'une enchère publicitaire de l'API Protected Audience
Six étapes d'enchères publicitaires avec l'API Protected Audience
Ce diagramme décrit chaque étape d'enchères publicitaires avec l'API Protected Audience.
  1. Un utilisateur consulte un site qui diffuse des annonces.
  2. Le code du vendeur exécute navigator.runAdAuction(). Il indique 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.

Quand aura lieu la mise aux enchères ?

L'API Protected Audience peut être exécutée seule ou avec des enchères programmatiques. Dans une vente programmatique multivendeur:

  1. L'utilisateur consulte un site participant.
  2. Un autre vendeur exécute une enchère programmatique pour trouver une annonce contextuelle pour un espace publicitaire disponible.
  3. L'enchère de l'API Protected Audience est exécutée.
  4. scoreAd()compare les enchères de l'acheteur aux résultats de la première mise aux enchères.

Les enchères qui ne peuvent pas battre l'enchère gagnante contextuelle sont rejetées.

Qui gère les enchères publicitaires de l'API Protected Audience ?

Plusieurs parties peuvent organiser des enchères pour vendre des espaces publicitaires.

Exemple :

  • Éditeur de contenu: personne qui héberge elle-même du contenu publicitaire sur son site Web.
  • Plate-forme côté offre (SSP): travaille avec l'éditeur et fournit d'autres services.
  • Script tiers: agit pour un éditeur afin de permettre sa participation aux enchères publicitaires.

Avec l'API Protected Audience, un vendeur a trois tâches à accomplir:

  • Appliquer les règles de l'éditeur: quels acheteurs et quelles enchères sont éligibles.
  • Exécuter la logique d'enchères: JavaScript exécuté dans des worklets pour calculer un score de désirabilité pour chaque enchère.
  • Enregistrez le résultat des enchères.

Ces tâches sont effectuées de manière programmatique, dans le code fourni par le vendeur lorsqu'il lance une mise aux enchères d'annonces en appelant la fonction JavaScript navigator.runAdAuction().

Fonctions de l'API

runAdAuction()

Le vendeur envoie une requête au navigateur de l'utilisateur pour lancer une mise aux enchères d'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': ...,
      ...
    },
    ...
  ]
};

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

runAdAuction() renvoie une promesse qui se résout en URN (urn:uuid:<something>) qui représente le résultat de l'enchère publicitaire. Le navigateur ne peut le décoder que lorsqu'il est transmis à un cadre clôturé pour l'affichage. La page de l'éditeur ne peut pas inspecter l'annonce gagnante.

Le script decisionLogicUrl examine chaque annonce individuelle, ainsi que son enchère et ses métadonnées associées, une par une, puis lui attribue un score de désirabilité numérique.

auctionConfig établissements

seller
Obligatoire
Exemple: 'https://ssp.example'
Rôle: origine du vendeur.
decisionLogicUrl
Obligatoire
Exemple: 'https://ssp.example/auction-decision-logic.js'
Rôle: URL du code JavaScript du worklet d'enchères.
trustedScoringSignalsUrl
Facultatif
Exemple: 'https://ssp.example/scoring-signals'
Rôle: URL du serveur approuvé du vendeur.
interestGroupBuyers
Obligatoire
Exemple: ['https://dsp.example', 'https://buyer2.example', ...]
Rôle: origines de tous les propriétaires de groupes d'intérêts invités à enchérir lors de la mise aux enchères.
Remarques: 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 d'autres critères que l'inclusion du propriétaire du groupe d'intérêt. Par exemple, le vendeur peut examiner les créations publicitaires pour vérifier qu'elles respectent ses règles.
auctionSignals
Facultatif
Exemple: {...}
Rôle: informations du vendeur sur le contexte de la page, le type d'enchères, etc.
sellerSignals
Facultatif
Exemple: {...}
Rôle: informations basées sur les paramètres de l'éditeur, envoi d'une requête d'annonce contextuelle, etc.
sellerTimeout
Facultatif
Exemple: 100
Rôle: durée d'exécution maximale (en ms) du script scoreAd() du vendeur.
perBuyerSignals
Facultatif
Exemple: 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
Rôle: signaux contextuels sur la page pour chaque acheteur spécifique, à partir de son serveur.
perBuyerTimeouts
Facultatif
Exemple: 50
Rôle: durée d'exécution maximale (en ms) des scripts generateBid() d'un acheteur particulier.
componentAuctions
Facultatif
Exemple: 
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
Rôle: configurations supplémentaires pour les enchères de composants.

decisionLogicUrl

decisionLogicUrl est une propriété de l'objet de configuration des enchères, transmise à runAdAuction(). Cette URL doit inclure un script pour la fonction scoreAd(). Cette logique est exécutée une fois pour chaque annonce afin de déterminer son attrait.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

browserSignals

browserSignals 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:

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}

Avant le début d'une mise aux enchères, le vendeur trouve la meilleure annonce contextuelle pour l'espace publicitaire disponible. Une partie de la logique scoreAd() rejette toute annonce qui ne peut pas battre le gagnant contextuel.

scoreAd()

scoreAd() utilise les arguments suivants :

Argument Rôle
adMetadata Métadonnées arbitraires fournies par l'acheteur.
auctionConfig Objet de configuration des enchères transmis à navigator.runAdAuction().
bid Valeur d'enchère numérique.
trustedScoringSignals Valeurs récupérées au moment des enchères à partir du serveur approuvé du vendeur, représentant l'opinion du vendeur sur l'annonce.

Questions fréquentes

Comment le gagnant de l'enchère est-il déterminé et qui le choisit ?

Le vendeur fournit la logique de notation pour déterminer le score de désirabilité de chaque annonce, et le navigateur sélectionne l'annonce gagnante en fonction du score le plus élevé.

Le vendeur inclut une logique dans la fonction scoreAd(), et le navigateur exécute la fonction dans un worklet dont la communication avec le code en dehors est limitée. Le navigateur lui-même n'attribue pas de score aux annonces. Le navigateur est le seul responsable de l'exécution de la logique de notation et de la sélection de l'enchère ayant le score le plus élevé.

Toutes les références de l'API Protected Audience

Des guides de référence de l'API sont disponibles:

L'article explicatif de l'API Protected Audience fournit également des informations détaillées sur la compatibilité des fonctionnalités et les contraintes.