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 via l'API Protected Audience

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

Lisez le guide du développeur pour connaître le cycle de vie complet de l'API Protected Audience, puis consultez la vidéo d'explication de l'API Protected Audience pour une discussion approfondie sur les rapports au niveau des événements (temporaires).

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

Que rapporte 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: disponible uniquement pour les acheteurs ayant remporté l'enchère, pour savoir qu'ils ont remporté une mise aux enchères.

L'objectif à long terme est d'autoriser le navigateur à communiquer les résultats des enchères pour le vendeur et les acheteurs à l'aide des API Private Aggregation. En tant que 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(). Cette fonction accepte 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 code JavaScript du vendeur fourni dans decisionLogicUrl (qui fournit également scoreAd()) peut inclure une fonction reportResult() pour enregistrer le résultat de la mise aux enchères.

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

Les arguments transmis à cette fonction sont les suivants:

auctionConfig

Objet de configuration de la mise aux 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 de 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 signaler le résultat de l'enchère.

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

Les arguments transmis à cette fonction sont les suivants:

auctionSignals et perBuyerSignals

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

sellerSignals

Valeur renvoyée de reportResult(), qui donne au vendeur la possibilité 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 de la création de rapports temporaires

Deux méthodes sont temporairement disponibles dans Chrome pour la création de rapports sur les enchères:

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

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

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

Ces méthodes sont disponibles par défaut dans Chrome si chrome://flags/#privacy-sandbox-ads-apis est activé. Toutefois, si vous exécutez Chrome avec des indicateurs de ligne de commande pour activer l'API Protected Audience, vous devrez activer explicitement les méthodes en incluant l'indicateur BiddingAndScoringDebugReportingAPI. Si l'indicateur n'est pas activé, les méthodes restent disponibles, mais ne font rien.

Toutes les documentations de référence de l'API Protected Audience

API reference guides are available:

The Protected Audience API explainer also provides detail about feature support and constraints.

É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.