Rapports sur les enchères de l'API Protected Audience

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Mesurer les données et les résultats des enchères de l'API Protected Audience

Cet article présente une vue d'ensemble des différents mécanismes disponibles pour enregistrer les données des enchères de l'API Protected Audience sur votre serveur, ainsi que les mécanismes de transition que vous pouvez utiliser pendant la migration en attendant que d'autres solutions soient disponibles.

Pour générer des rapports sur les métriques importantes que vous collectez à partir d'enchères publicitaires, l'API Protected Audience est compatible avec les éléments suivants:

• Agrégation privée, qui collecte les signaux et les résultats des enchères pour générer des rapports récapitulatifs.
• API Ads Reporting pour les cadres protégés et les iframes, qui sont des canaux dans les cadres permettant de communiquer avec les worklets de l'API Protected Audience. L'API permet d'associer des données au niveau des événements à des signaux d'enchères. Les rapports au niveau des événements de l'API Ads Reporting sont un mécanisme de transition en attendant la conception d'un mécanisme de reporting plus privé.
• Les rapports sur l'attribution, qui vous permettent d'associer les données de conversion aux signaux d'enchères.
• Shared Storage, qui vous permet d'écrire des signaux d'enchères dans un espace de stockage inter-origine, puis de générer des rapports sur ces données ultérieurement à l'aide de l'agrégation privée.

Présentation des rapports de l'API Protected Audience

Les données du flux d'enchères de l'API Protected Audience peuvent être transmises à votre serveur à trois périodes principales: au moment de l'enchère, lorsque l'enchère est exécutée à partir du site de l'éditeur, au moment de l'affichage, lorsque l'annonce est affichée dans un frame clôturé ou une iframe sur le site de l'éditeur, et au moment de la conversion, lorsque l'utilisateur effectue une action sur un autre site qui peut être attribuée à l'enchère.

Au moment des enchères, vous pouvez créer des rapports sur les données des enchères à l'aide de worklets de création de rapports. Au moment de l'affichage, vous pouvez générer des rapports sur les données d'engagement à partir d'un iframe ou d'un frame clôturé. Au moment de la conversion, vous pouvez générer des rapports sur les données d'attribution à partir de la page de destination à l'aide de l'API Attribution Reporting.

Emplacements de signalement

Dans une mise aux enchères, les acheteurs peuvent signaler les signaux disponibles dans les worklets generateBid() et reportWin(), et les vendeurs peuvent signaler les signaux disponibles dans les worklets scoreAd() et reportResult(). En dehors d'une mise aux enchères, les acheteurs et les vendeurs peuvent enregistrer les données d'un frame qui a affiché l'annonce et du site à partir duquel la conversion a été effectuée.

Pendant chacune des périodes indiquées, les acheteurs et les vendeurs auront accès à diverses API de création de rapports pour générer des données telles que des signaux d'enchères, des données au niveau des événements et des données de conversion.

Données disponibles dans une mise aux enchères de l'API Protected Audience

Les données suivantes peuvent être enregistrées dans un worklet de l'API Protected Audience lors des enchères.

Signaux

Les signaux sont les données contextuelles des enchères, les données utilisateur, les données en temps réel et les données du navigateur disponibles pour les acheteurs et les vendeurs dans un worklet afin de générer une enchère, d'évaluer une annonce et de générer des rapports sur les résultats d'une enchère.

L'objet auction config est la principale source de données fournies pour être disponibles en tant que signaux dans les worklets. L'éditeur et le vendeur peuvent fournir des données contextuelles et first party dans la configuration des enchères. Ces signaux peuvent être enrichis avec les données du groupe d'intérêt de l'acheteur, les données au niveau des événements du frame de rendu de l'annonce et les données d'attribution de la page de suivi du clic. Les données enregistrées peuvent être utilisées pour les rapports acheteur/vendeur, la facturation, la budgétisation, l'entraînement de modèles de ML, etc.

Autres données disponibles

• Données sur les résultats liées aux données sur les enchères remportées et perdues, comme le prix de l'enchère gagnante et le motif du refus de l'enchère.
• Données sur les performances contenant des informations sur la latence, telles que la durée d'extraction et d'exécution du worklet d'enchères.

Données disponibles en dehors d'une mise aux enchères de l'API Protected Audience

En dehors d'une mise aux enchères de l'API Protected Audience, il existe deux périodes pendant lesquelles les données peuvent être enregistrées dans les rapports.

Au moment de l'affichage, lorsque l'annonce est diffusée sur le site de l'éditeur, les données au niveau de l'événement provenant de l'iframe ou du frame clôturé peuvent être associées aux données d'enchères de l'API Protected Audience et envoyées à votre serveur. Les données au niveau de l'événement incluent, par exemple, les impressions d'annonces, les clics, les survols et tout autre événement qui se produit dans le frame.

Au moment de la conversion, lorsqu'un utilisateur effectue une action sur la page de suivi des clics qui est attribuée à l'enchère, les données au niveau de l'événement de la page de conversion peuvent être associées aux données d'enchères de l'API Protected Audience et envoyées à votre serveur.

Création de rapports au niveau des événements

Les rapports au niveau des événements fournissent des informations détaillées sur un ou plusieurs événements. Un événement peut être une victoire aux enchères, une impression d'annonce ou une conversion. Jusqu'en 2026 au moins, les rapports sur les enchères remportées au niveau des événements resteront en place. Les cadres clôturés ne seront pas nécessaires pour afficher une annonce Protected Audience, et un iframe avec un accès réseau illimité pourra être utilisé pour les rapports au niveau des événements. De plus, l'API Ads Reporting est disponible dans les cadres et les iFrames clôturés pour vous permettre d'associer les données d'enchères et de conversion aux données au niveau des événements du cadre. Cette mesure vise à faciliter la migration de l'écosystème, car vous pourrez continuer à utiliser votre infrastructure de création de rapports existante jusqu'en 2026 au moins, le temps de migrer votre système vers Protected Audience.

Rapports sur les enchères remportées au niveau des événements avec sendReportTo()

Le sendReportTo() function sur une enchère gagnante est un mécanisme permettant de générer des rapports sur les données au niveau des événements dans une enchère Protected Audience. La fonction est disponible dans les worklets de création de rapports pour les acheteurs et les vendeurs. Le navigateur envoie une requête GET à la chaîne d'URL fournie au début de l'affichage de l'annonce. Vous pouvez encoder n'importe quel signal disponible dans vos worklets en tant que paramètres de requête de l'URL.

Par exemple, un acheteur peut enregistrer le montant de l'enchère gagnante à partir du worklet reportWin() à des fins de facturation:

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

La fonction sendReportTo() permet de générer un rapport sur les enchères gagnantes pour le vendeur lorsqu'elle est appelée à partir de reportResult() et un rapport sur les enchères gagnantes pour l'acheteur lorsqu'elle est appelée à partir de reportWin(). La fonction sendReportTo() est disponible jusqu'en 2026 au moins.

Le rapport "Engagement"

Un rapport sur l'engagement contient des données au niveau des événements d'une création publicitaire, telles que les données sur les impressions ou les clics, qui sont associées aux signaux de l'enchère de l'API Protected Audience qui a généré l'annonce. Étant donné que l'annonce est affichée après la fin des enchères, les signaux d'enchères ne sont pas disponibles dans le frame qui affiche l'annonce. Pour associer ces données de différentes périodes, nous vous proposons deux mécanismes de transition pour générer des rapports sur l'engagement.

La fonction sendReportTo() décrite ci-dessus permet d'associer des données d'enchères à des données au niveau de l'événement à partir d'un iframe, mais elle ne fonctionne pas pour un frame clôturé, car un ID unique ne peut pas être transmis par l'intégrateur, car la communication entre l'intégrateur et le frame clôturé est limitée. Pour associer les données des enchères aux données au niveau des événements d'une annonce avec cadre délimité, vous pouvez utiliser l'API Ads Reporting.

API Ads Reporting pour les frames et les iFrames cloisonnés

L'API Ads Reporting pour les cadres et les iFrames clôturés vous permet d'associer les données au niveau des événements utilisateur d'un frame d'annonces aux signaux dans une enchère Protected Audience.

Dans un worklet de création de rapports de l'API Protected Audience, vous pouvez enregistrer une balise publicitaire avec la fonction registerAdBeacon() et transmettre votre URL de création de rapports avec les signaux ajoutés en tant que paramètres de requête. Vous devez également spécifier l'événement personnalisé que vous souhaitez associer à l'URL de création de rapports. Ensuite, lorsque l'annonce est affichée dans un cadre clôturé, vous pouvez déclencher l'événement personnalisé en appelant la fonction window.fence.reportEvent(). Les données disponibles dans le cadre clôturé peuvent être ajoutées en tant que charge utile.

La fonction registerAdBeacon() n'est disponible que dans les fonctions de création de rapports. Elle n'est pas disponible dans la logique d'enchères de l'acheteur ni dans la logique de notation du vendeur.

Dans l'exemple suivant, un ID de campagne est associé à une charge utile au niveau de l'événement avec les coordonnées du clic:

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

L'API de création de rapports sur les annonces avec cadres délimités sera également disponible jusqu'en 2026 au moins, pour les mêmes raisons que les rapports sur les victoires.

Pour en savoir plus, consultez la vidéo explicative.

Accès au réseau sans restriction

Les cadres cloisonnés permettent de charger des ressources réseau de la même manière qu'un iframe. Vous pouvez également envoyer des données au niveau de l'événement dans des cadres cloisonnés à votre serveur. Vous pouvez générer des rapports au niveau des événements côté serveur ultérieurement en associant les données au niveau des événements d'un frame clôturé aux données d'enchères envoyées avec sendReportTo(), comme indiqué dans la section Mécanisme de création de rapports au niveau des événements d'enchères ci-dessus.

L'accès au réseau sera limité à l'avenir.

Rapport sur l'attribution

Un rapport sur l'attribution vous permet d'associer une conversion sur un site Web à une annonce choisie lors d'une mise aux enchères de l'API Protected Audience. Par exemple, un utilisateur peut cliquer sur une annonce produit que vous diffusez, être redirigé vers le site de l'annonceur et y effectuer un achat. Vous souhaitez alors attribuer cet achat à l'annonce diffusée. L'API Attribution Reporting sera intégrée à l'API Protected Audience pour combiner les données d'enchères du site de l'éditeur et les données de conversion du site de l'annonceur.

En attendant que nous concevions une solution plus permanente, vous pouvez utiliser l'API Ads Reporting pour les cadres clôturés comme mécanisme de transition pour générer un rapport au niveau des événements et agrégable avec Attribution Reporting. Notez que ces rapports sont destinés à mesurer les conversions et sont distincts des rapports sur l'engagement au niveau des événements et agrégables générés à partir des enchères et du frame d'annonce. Nous publierons une vidéo expliquant une solution plus permanente lorsque nous serons prêts.

Mécanisme de transition

Lorsque vous enregistrez une balise publicitaire, vous pouvez utiliser le mot clé reserved.top_navigation, qui ajoute automatiquement l'en-tête Attribution-Reporting-Eligible pour que la balise puisse être enregistrée en tant que source d'attribution.

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

Pour joindre des données au niveau de l'événement à la balise que vous avez enregistrée, vous pouvez appeler setReportEventDataForAutomaticBeacons() à partir du frame clôturé avec la charge utile de l'événement.

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

Pour en savoir plus, consultez la section "Attribution Reporting" de la vidéo d'explication de l'API Ads Reporting.

Exemple de rapport sur l'engagement et les conversions

Dans cet exemple, nous allons l'examiner du point de vue de l'acheteur, qui souhaite associer les données de la mise aux enchères, du frame d'annonce et du site de conversion.

Dans ce workflow, l'acheteur se coordonne avec le vendeur pour envoyer un identifiant unique à la mise aux enchères. Lors de l'enchère, l'acheteur envoie cet identifiant unique avec les données d'enchères. Au moment de l'affichage et de la conversion, les données du frame ou de l'iFrame clôturé sont également envoyées avec le même identifiant unique. Par la suite, l'identifiant unique pourra être utilisé pour associer ces rapports.

Procédure :

1. Avant le début de l'enchère, l'acheteur envoie un ID unique au vendeur dans le cadre de sa réponse à l'enchère en temps réel (RTB) programmatique. L'ID peut être défini en tant que variable, par exemple auctionId. L'identifiant est transmis en tant que perBuyerSignals dans auctionConfig. Il devient disponible dans les worklets de l'acheteur.
2. Au moment des enchères, l'acheteur peut enregistrer une balise publicitaire à déclencher pendant le délai d'affichage de l'annonce et le délai de conversion (registerAdBeacon()).
   1. Pour associer des signaux d'enchères à un événement de frame d'annonce, définissez auctionId en tant que paramètre de requête de l'URL de la balise.
   2. Pour associer des signaux d'enchères à un événement de conversion, définissez auctionId dans l'URL de la balise.
3. Pendant le délai d'affichage de l'annonce, les balises que vous avez enregistrées au moment des enchères peuvent être déclenchées ou améliorées à l'aide de données au niveau des événements.
   1. Déclenchez l'événement de frame avec reportEvent() et transmettez les données au niveau de l'événement.
   2. Ajouter une charge utile au niveau de l'événement à la balise d'attribution avec setReportEventDataForAutomaticBeacons()
   3. Enregistrez l'annonce auprès de l'API Attribution Reporting en répondant aux requêtes de balise publicitaire avec l'en-tête Attribution-Reporting-Register-Source.
4. Au moment de la conversion, vous pouvez déclencher la source que vous avez enregistrée au moment des enchères.

Une fois le processus ci-dessus terminé, l'acheteur dispose d'un rapport sur les enchères, d'un rapport sur l'engagement et d'un rapport sur les conversions. Ces rapports sont tous liés par une seule clé unique qui permet de les associer les uns aux autres.

Un workflow similaire s'applique à un vendeur s'il a besoin d'accéder aux données d'attribution. Le vendeur peut également utiliser un identifiant unique à envoyer avec registerAdBeacon(). À partir du frame, l'appel reportEvent() contient une propriété de destination qui peut être utilisée pour envoyer le rapport à l'acheteur et au vendeur. Notez que le SSP doit également être présent sur la page de destination pour que le déclencheur soit attribué à la source.

Agréger les données Protected Audience

L'API Private Aggregation est le mécanisme utilisé pour générer un rapport récapitulatif à partir des données Protected Audience. Il s'agit d'un rapport agrégé et bruyant des données collectées dans des buckets. Un bucket est représenté par une clé d'agrégation, et certaines informations peuvent être encodées dans la clé.

Par exemple, un événement d'impression d'annonce peut être comptabilisé dans différents buckets, chacun représentant une campagne publicitaire différente. Un rapport récapitulatif diffère d'un rapport au niveau des événements en ce sens qu'il ne révèle pas d'informations sur chaque événement. Avec un rapport au niveau des événements, vous pouvez déterminer que les utilisateurs A, B et C ont vu la campagne 123. Les rapports récapitulatifs vous permettent de mesurer le nombre d'utilisateurs qui ont vu la campagne 123. Un bruit est ajouté pour protéger la confidentialité des utilisateurs.

Pour en savoir plus sur l'API, consultez l'article Agrégation privée.

Regrouper des signaux d'enchères

Vous pouvez agréger les signaux disponibles dans les worklets sur votre serveur à l'aide de l'agrégation privée. Pour l'agrégation des signaux, vous pouvez utiliser la méthode privateAggregation.contributeToHistogram() disponible dans les worklets d'enchères de l'acheteur, de notation du vendeur et de création de rapports pour l'acheteur/le vendeur.

Dans cet exemple, l'enchère gagnante est agrégée dans le bucket du propriétaire du centre d'intérêt:

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
} 

Il s'agit du mécanisme général à utiliser lorsque les signaux que vous souhaitez agréger ne sont pas associés à des données au niveau des événements et ne sont pas déclenchés par un événement en dehors de l'enchère. Pour en savoir plus sur les signaux d'enchères dans les rapports, consultez la présentation.

Agrégation des signaux d'enchères avec les données d'événements

Vous pouvez agréger des signaux d'enchères avec des informations limitées sur un événement qui se produit dans un frame d'annonce. Par exemple, vous pouvez mesurer de manière globale le nombre de clics enregistrés par une annonce pour une campagne en créant un bucket qui représente cette campagne et l'événement de clic. Notez que, depuis le frame de l'annonce, vous pouvez spécifier l'événement qui s'est produit, mais vous ne pouvez pas associer de charge utile au niveau de l'événement.

Pour agréger les signaux d'enchères par événement, vous pouvez utiliser privateAggregation.contributeToHistogramOnEvent(eventType, contribution), qui prend une chaîne qui spécifie le type d'événement et la contribution à signaler lorsque cet événement est déclenché. Vous pouvez appeler la méthode avec un type d'événement personnalisé, puis appeler window.fence.reportEvent(eventType) à partir du frame d'annonce pour déclencher l'envoi du rapport.

Imaginons que vous souhaitiez mesurer le nombre de clics enregistrés par une annonce d'une campagne.

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

Dans la fonction de génération d'enchères, vous pouvez définir un bucket comme étant la combinaison de l'ID de la campagne et de l'événement de clic, puis augmenter la valeur de ce bucket de 1 à chaque fois que l'événement se déclenche.

// Ad frame
window.fence.reportEvent('click');

Ensuite, à un moment ultérieur, à partir du frame de l'annonce, vous pouvez déclencher l'envoi du rapport en appelant reportEvent(eventType):

Pour en savoir plus sur le déclenchement de contributions d'agrégation privée à partir d'un frame, consultez la présentation.

Créer des rapports sur les résultats et les performances des enchères

Vous pouvez également agréger les résultats des enchères lorsque vous êtes déclenché par un événement de gain ou de perte d'enchères avec contributeToHistogramOnEvent(eventType, contribution) lorsque vous transmettez des mots clés de type d'événement réservés (reserved.win, reserved.loss et reserved.always).

L'agrégation privée fournit une liste de valeurs de base à partir de laquelle vous pouvez calculer le bucket et la valeur de votre contribution. Les valeurs de base disponibles pour les résultats des enchères sont la valeur de l'enchère de l'annonce gagnante, la valeur de l'enchère évaluée comme étant la deuxième plus élevée et la raison pour laquelle une enchère a été rejetée de l'enchère.

Lorsqu'une valeur de base est fournie, comme le montant de l'enchère gagnante, vous pouvez définir la valeur à ajouter ou à soustraire à cette valeur, puis enregistrer la valeur finale. Par exemple, si l'enchère gagnante de 5 € est indiquée comme valeur de base, vous pouvez soustraire votre enchère de 2 € pour calculer la valeur réelle de 3 € de votre enchère perdue.

Rapports sur les résultats des enchères

Imaginons que vous ayez perdu une enchère et que vous souhaitiez savoir à quel point votre enchère était éloignée du prix d'adjudication.

Pour savoir de combien vous avez perdu l'enchère, vous pouvez soustraire le prix de votre enchère au prix de l'enchère gagnante:

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

Lorsque le rapport est envoyé, la valeur réelle indiquée est la baseValue ajustée décalée par la valeur offset. Pour en savoir plus, consultez la présentation.

Rapports sur les performances

Les acheteurs et les vendeurs peuvent indiquer le temps d'exécution d'un script et le temps nécessaire pour récupérer les signaux fiables. Les vendeurs peuvent collecter l'heure de génération des enchères et l'heure du signal d'enchères de confiance de chaque acheteur avec son autorisation.

Pour en savoir plus, consultez la vidéo explicative.

Stocker des signaux d'enchères dans Shared Storage

Le stockage partagé est un espace de stockage non partitionné et multi-origine dans lequel vous pouvez écrire librement, mais qui est protégé par des barrières lors de la lecture et du traitement des valeurs stockées. L'une des passerelles disponibles pour l'API Shared Storage est Private Aggregation. Vous ne pouvez lire les valeurs du stockage partagé que depuis un worklet, et vous pouvez générer des rapports sur ces valeurs à l'aide de l'agrégation privée depuis le worklet.

Vous pouvez également écrire dans un espace de stockage partagé à partir des worklets d'enchères, d'évaluation et de création de rapports de l'API Protected Audience. Par la suite, vous pourrez transmettre ces valeurs dans l'espace de stockage partagé à votre serveur à l'aide de l'agrégation privée . Vous pouvez également utiliser les valeurs stockées pour l'opération Sélection d'URL.

À partir d'un worklet de l'API Protected Audience, vous pouvez écrire n'importe quelle clé et valeur dans l'espace de stockage partagé:

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

Vous pourrez ensuite charger un worklet de stockage partagé pour lire et envoyer cette valeur avec l'agrégation privée:

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

Pour en savoir plus sur Shared Storage, consultez la section sur Shared Storage du guide du développeur sur les rapports de l'API Protected Audience, la présentation, la démonstration en direct et le code de démonstration sur GitHub.

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