Guide du vendeur: lancer des enchères publicitaires

Guide de l'API pour les vendeurs et documentation de référence sur les enchères publicitaires de l'API Protected Audience.

Dans cet article, vous trouverez une référence technique sur la mise aux enchères, telle qu'elle est utilisée dans la version actuelle de l'API Protected Audience expérimentale.

Lisez le guide du développeur pour découvrir le cycle de vie complet de l'API Protected Audience, puis consultez la vidéo d'explication de l'API Protected Audience pour découvrir en détail comment les vendeurs effectuent 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 publicitaires de l'API Protected Audience ?

Les enchères publicitaires de l'API Protected Audience sont un ensemble de petits programmes JavaScript que le navigateur exécute sur l'appareil de l'utilisateur pour choisir une annonce. Pour des raisons de confidentialité, tous les codes d'enchères du vendeur et des acheteurs sont exécutés 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
Ce diagramme décrit chaque étape d'une mise aux enchères publicitaires de l'API Protected Audience.
  1. Un utilisateur visite un site qui affiche des annonces.
  2. 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().
  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 des données en temps réel, telles que le budget restant de la campagne publicitaire, à partir du service clé-valeur de l'acheteur.
  4. 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.
  5. 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.
  6. L'enchère est signalée au vendeur et aux acheteurs gagnants.

Quand la mise aux enchères a-t-elle lieu ?

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

  1. L'utilisateur consulte un site participant.
  2. Un autre vendeur lance une enchère programmatique afin de trouver une annonce contextuelle pour un espace publicitaire disponible.
  3. Les enchères de l'API Protected Audience sont lancées.
  4. scoreAd()compare les enchères de l'acheteur avec les résultats de la première mise aux enchères.

Les enchères qui ne peuvent pas l'emporter sur l'enchère contextuelle gagnante sont refusées.

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

Plusieurs parties peuvent participer à une mise aux enchères pour vendre des espaces publicitaires.

Exemple :

  • Éditeur de contenu: il agit en son nom pour héberger le contenu publicitaire sur son site Web.
  • Plate-forme côté offre (SSP): collaboration avec l'éditeur et fourniture d'autres services
  • Script tiers: agir pour le compte d'un éditeur, afin de permettre la participation aux enchères publicitaires.

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

  • Appliquez les règles de l'éditeur, qui déterminent quels acheteurs et quelles enchères sont éligibles.
  • Exécution de la logique d'enchères: JavaScript s'exécute dans des worklets pour calculer le score de désirabilité pour chaque enchère.
  • Générez un rapport sur le résultat de la mise aux enchères.

Ces tâches sont effectuées par programmation dans le code fourni par le vendeur lorsqu'il lance une enchère publicitaire en appelant la fonction JavaScript navigator.runAdAuction().

Fonctions de l'API

runAdAuction()

Le vendeur demande au navigateur de l'utilisateur de lancer une enchère publicitaire 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. Elle ne peut être décodée par le navigateur que lorsqu'elle est transmise à un frame cloisonné pour l'affichage: la page de l'éditeur ne peut pas inspecter l'annonce gagnante.

Le script decisionLogicUrl examine chaque annonce individuelle ainsi que l'enchère et les métadonnées associées, l'une après l'autre, 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 worklet d'enchères JavaScript.
trustedScoringSignalsUrl
Facultatif
Exemple: 'https://ssp.example/scoring-signals'
Rôle: URL du serveur de confiance du vendeur.
interestGroupBuyers
Obligatoire
Exemple: ['https://dsp.example', 'https://buyer2.example', ...]
Rôle: origines de tous les propriétaires de groupes de centres d'intérêt invités à enchérir dans la mise aux enchères.
Remarque: Le vendeur peut spécifier interestGroupBuyers: pour permettre à tous les groupes de centres d'intérêt d'enchérir. Les annonces sont ensuite acceptées ou refusées sur la base de critères autres que l'inclusion du propriétaire du groupe de centres d'intérêt. Par exemple, le vendeur peut examiner les créations publicitaires pour s'assurer qu'elles respectent ses règles.
auctionSignals
Facultatif
Exemple: {...}
Rôle: informations sur le vendeur concernant le contexte de la page, le type d'enchère, etc.
sellerSignals
Facultatif
Exemple: {...}
Rôle: informations basées sur les paramètres de l'éditeur, sur les demandes d'annonces contextuelles, etc.
sellerTimeout
Facultatif
Exemple: 100
Rôle: Durée d'exécution maximale (ms) du script scoreAd() du vendeur.
perBuyerSignals
Facultatif
Exemple : 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
Rôle: signaux contextuels sur la page de chaque acheteur spécifique, provenant de son serveur.
perBuyerTimeouts
Facultatif
Exemple: 50
Rôle: Durée maximale d'exécution (ms) des scripts generateBid() d'un acheteur spécifique.
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, transmis à 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 si elle est souhaitable.

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

browserSignals

browserSignals est un objet construit par le navigateur, qui inclut des informations connues de celui-ci 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 l'annonce contextuelle gagnante.

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 numérique de l'enchère.
trustedScoringSignals Valeurs récupérées au moment de l'enchère à partir du serveur de confiance du vendeur, et représentant l'opinion du vendeur concernant l'annonce.

Questions fréquentes

Comment le gagnant des enchères est-il désigné et qui le choisit ?

Le vendeur fournit la logique d'évaluation pour déterminer le niveau de souhaitabilité de chaque annonce, et le navigateur sélectionne le score le plus élevé en tant qu'annonce gagnante.

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 extérieur est limitée. Le navigateur ne évalue pas les annonces. Le navigateur est seul responsable d'exécuter la logique d'évaluation et de sélectionner l'enchère avec le score le plus élevé.

Toutes les documentations de référence 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.