Guide du vendeur: lancer des enchères publicitaires

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

Cet article fournit une référence technique pour 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 découvrir le cycle de vie complet de l'API Protected Audience. Reportez-vous également à la présentation de l'API Protected Audience pour en savoir plus sur la façon dont les vendeurs organisent 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 l'enchère d'annonces de l'API Protected Audience ?

Une enchère publicitaire 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.

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.

Quand l'enchère a-t-elle lieu ?

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

1. L'utilisateur visite un site participant.
2. Une enchère programmatique est organisée par un autre vendeur pour trouver une annonce contextuelle pour un emplacement publicitaire disponible.
3. La mise aux enchères de l'API Protected Audience est exécutée.
4. scoreAd()compare les offres de l'acheteur avec les résultats de la première enchère.

Les enchères qui ne peuvent pas battre le gagnant contextuel sont refusées.

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

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

Exemple :

• Éditeur de contenu : agit pour son propre compte afin d'héberger du contenu publicitaire sur son site Web.
• Plate-forme côté offre (SSP) : elle travaille avec l'éditeur et fournit d'autres services.
• Script tiers : agissant pour le compte d'un éditeur, pour permettre la 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.
• Signalez 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 vente 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 vente 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 un URN (urn:uuid:<something>) représentant le résultat de l'enchère publicitaire. Le navigateur ne peut décoder cette valeur que lorsqu'elle est transmise à un cadre clôturé pour le rendu : la page de l'éditeur ne peut pas inspecter l'annonce gagnante.

Le script decisionLogicUrl examine chaque annonce individuellement, ainsi que l'enchère et les métadonnées associées, 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 JavaScript du worklet d'enchères.

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 d'intérêt invités à enchérir lors de l'enchère.

Remarques : Le vendeur peut spécifier interestGroupBuyers: pour autoriser tous les groupes d'intérêt à enchérir. Les annonces sont ensuite acceptées ou refusées en fonction de critères autres 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, qui effectue une demande 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, depuis son serveur.

perBuyerTimeouts

Facultatif

Exemple : 50

Rôle : durée d'exécution maximale (en 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, 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, qui inclut 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 enchère, le vendeur trouve la meilleure annonce contextuelle pour l'emplacement 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 :

Questions fréquentes

Comment le gagnant des enchères est-il désigné 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 le score le plus élevé comme annonce gagnante.

Le marchand 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 de celui-ci est limitée. Le navigateur lui-même n'attribue pas de note aux annonces. Le navigateur est exclusivement responsable de l'exécution de la logique de notation et de la sélection de l'enchère ayant obtenu 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:

• Guide du développeur de l'API Protected Audience
• Guide des acheteurs d'annonces pour les groupes de centres d'intérêt et la génération d'enchères de l'API Protected Audience
• Guide des vendeurs publicitaires pour les enchères publicitaires Protected Audience
• Guide sur la création de rapports sur les résultats des enchères
• Bonnes pratiques concernant la latence des enchères publicitaires Protected Audience
• Résoudre les problèmes liés à Protected Audience

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