Générer des rapports sur les résultats des enchères de l'API Protected Audience

Guide du vendeur et de l'acheteur pour générer des rapports sur les enchères de l'API Protected Audience.

Cet article est une documentation de référence technique permettant de générer des rapports sur les enchères remportées par l'API Protected Audience, telles qu'elles sont utilisées dans l'itération actuelle de l'API expérimentale Protected Audience.

Consultez le guide du développeur pour tout savoir sur le cycle de vie complet de l'API Protected Audience, et reportez-vous à la vidéo d'explication correspondante pour en savoir plus sur la création de rapports au niveau des événements (temporaire).

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

Que renvoie l'API Protected Audience ?

Deux rapports de l'API Protected Audience sont disponibles:

  • Rapport sur le vendeur: informe le vendeur du gagnant de l'enchère publicitaire.
  • Rapport sur les acheteurs: uniquement disponible pour les acheteurs gagnants, afin de savoir s'ils ont remporté une mise aux enchères.

L'objectif à long terme est de permettre au navigateur de communiquer les résultats des enchères pour le vendeur et les acheteurs à l'aide des API Private Aggregation. Comme mécanisme de création de rapports temporaire au niveau des événements, le code qui implémente reportResult() pour le vendeur et reportWin() pour l'enchérisseur gagnant peut appeler la fonction sendReportTo(). Elle n'accepte qu'un seul argument: une chaîne représentant une URL récupérée une fois l'enchère terminée, qui encode les informations au niveau de l'événement à signaler.

Fonctions de l'API

Vendeur: reportResult()

Le JavaScript du vendeur fourni dans decisionLogicUrl (qui fournit également scoreAd()) peut inclure une fonction reportResult() pour indiquer le résultat de l'enchère.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Les arguments transmis à cette fonction sont les suivants:

auctionConfig

Objet de configuration des enchères transmis à navigator.runAdAuction().

browserSignals

Objet construit par le navigateur et fournissant des informations sur l'enchère. Exemple :

  {
    'topWindowHostname': 'publisher.example',
    'interestGroupOwner': 'https://dsp.example',
    'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
    'bid': <bidValue>,
    'desirability': <winningAdScore>
  }

La valeur renvoyée par cette fonction est utilisée comme argument sellerSignals pour la fonction reportWin() de l'enchérisseur gagnant.

Acheteur: reportWin()

Le code JavaScript de l'enchérisseur gagnant (qui a également fourni generateBid()) peut inclure une fonction reportWin() pour indiquer le résultat de la mise aux enchères.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

Les arguments transmis à cette fonction sont les suivants:

auctionSignals et perBuyerSignals

Les mêmes valeurs ont été transmises à generateBid() pour l'enchérisseur gagnant.

sellerSignals

La valeur renvoyée de reportResult(), qui permet au vendeur de transmettre des informations à l'acheteur.

browserSignals

Objet construit par le navigateur et fournissant des informations sur l'enchère. Exemple :

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid': <bidValue>
}

Implémentation temporaire de rapports

Pour créer des rapports sur les enchères, deux méthodes sont disponibles temporairement dans Chrome:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Ces méthodes utilisent chacune un seul argument: une URL à récupérer une fois l'enchère terminée. Elles peuvent être appelées plusieurs fois, dans scoreAd() et generateBid(), avec des arguments d'URL différents.

Chrome n'envoie des rapports de débogage de perte/gagnement que lorsqu'une enchère est terminée. Si une mise aux enchères est annulée (en raison d'une nouvelle navigation, par exemple), aucun rapport n'est généré.

Ces méthodes sont disponibles par défaut dans Chrome lorsque vous activez toutes les API de confidentialité des annonces sous chrome://settings/adPrivacy. Si vous exécutez Chrome avec des indicateurs de ligne de commande pour activer l'API Protected Audience, vous devez activer explicitement les méthodes en incluant l'option BiddingAndScoringDebugReportingAPI. Si l'indicateur n'est pas activé, les méthodes restent disponibles, mais ne font rien.

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.

Étape suivante

Nous souhaitons discuter avec vous d'une API adaptée à tous les utilisateurs.

Discuter de l'API

Comme d'autres API de la Privacy Sandbox, cette API est documentée et consultée publiquement.

Tester l'API

Vous pouvez tester l'API Protected Audience et y participer.