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

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

Cet article vous présente les différents mécanismes disponibles pour envoyer les données d'enchères de l'API Protected Audience à votre serveur. Il décrit également les mécanismes de transition que vous pouvez utiliser dès maintenant 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 lors d'une mise aux enchères d'annonces, l'API Protected Audience fonctionne avec :

• Private Aggregation, qui collecte les signaux et les résultats des enchères pour générer des rapports récapitulatifs.
• L'API Ads Reporting pour les cadres clôturés et les iframes, qui est un canal 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. Le reporting au niveau des événements de l'API Ads Reporting est un mécanisme transitoire en attendant la conception d'un mécanisme de reporting plus respectueux de la confidentialité.
• Attribution Reporting, qui vous permet 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 stockage multi-origines, puis de générer des rapports sur ces données ultérieurement à l'aide de Private Aggregation.

Présentation des rapports de l'API Protected Audience

Il existe trois périodes principales pendant lesquelles les données du flux d'enchères de l'API Protected Audience peuvent être transmises à votre serveur : le moment de l'enchère, lorsque l'enchère est exécutée à partir du site de l'éditeur, le moment de l'affichage, lorsque l'annonce est affichée dans un frame clôturé ou un iFrame sur le site de l'éditeur, et le 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 générer des rapports sur les données d'enchères à l'aide de worklets de reporting. Lors du rendu, vous pouvez signaler des données d'engagement à partir d'un iframe ou d'un fenced frame. Au moment de la conversion, vous pouvez signaler les données d'attribution de la page de destination à l'aide de l'API Attribution Reporting.

Emplacements des rapports

Lors d'une enchère, 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 enchère, les acheteurs et les vendeurs peuvent signaler des données à partir d'un frame ayant affiché l'annonce et à partir du site sur lequel la conversion a été effectuée.

Pendant chacune des périodes listées, les acheteurs et les vendeurs auront accès à différentes API de reporting disponibles pour générer des rapports sur des données telles que les signaux d'enchères, les données au niveau de l'événement et les données de conversion.

Données disponibles dans une enchère de l'API Protected Audience

Les données suivantes peuvent être incluses dans les rapports à partir d'un worklet de l'API Protected Audience pendant les enchères.

Signaux

Les signaux sont les données contextuelles, utilisateur, en temps réel et de 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 rendre compte des résultats d'une enchère.

L'objet auction_config est la principale source de données fournies pour devenir 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 des groupes d'intérêt de l'acheteur, les données au niveau des événements du frame de rendu des annonces et les données d'attribution de la page de destination. Les données fournies peuvent être utilisées pour les rapports sur les acheteurs/vendeurs, la facturation, la budgétisation, l'entraînement des modèles de ML et plus encore.

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 de refus de l'enchère.
• Les données sur les performances qui contiennent des informations sur la latence, comme le temps nécessaire pour récupérer et exécuter le worklet d'enchères.

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

En dehors d'une enchère de l'API Protected Audience, les données peuvent être incluses dans les rapports pendant deux périodes.

Lors de l'affichage de l'annonce sur le site de l'éditeur, les données au niveau de l'événement provenant de l'iframe ou du fenced frame peuvent être associées aux données d'enchères de l'API Protected Audience et transmises à votre serveur. Par exemple, les données au niveau de l'événement incluent les impressions d'annonces, les clics, les pointeurs et tous les autres événements qui se produisent dans le frame.

Lors de la conversion, lorsqu'un utilisateur effectue une action sur la page de destination 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 transmises à 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. Au moins jusqu'en 2026, les rapports sur les enchères remportées au niveau des événements resteront en place. Les cadres cloisonnés ne seront pas nécessaires pour afficher une annonce Protected Audience, et un iframe avec un accès réseau non limité pourra être utilisé pour les rapports au niveau des événements. De plus, l'API Ads Reporting est disponible dans les cadres cloisonnés et les iframes pour vous permettre d'associer les données d'enchères et de conversions aux données au niveau de l'événement du cadre. L'objectif est de faciliter la migration de l'écosystème. Vous pourrez en effet continuer à utiliser votre infrastructure de reporting existante au moins jusqu'en 2026, le temps de migrer votre système vers Protected Audience.

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

Le mécanisme sendReportTo() function permet de générer des rapports sur les données au niveau des événements lors d'une enchère Protected Audience. Cette 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 lorsque le rendu de l'annonce commence. 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 signaler 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() peut être utilisée pour générer un rapport de victoire pour le vendeur lorsqu'elle est appelée à partir de reportResult(), et un rapport de victoire pour l'acheteur lorsqu'elle est appelée à partir de reportWin(). La fonctionnalité sendReportTo() sera disponible au moins jusqu'en 2026.

Le rapport "Engagement"

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

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

API Ads Reporting pour les cadres clôturés et les iframes

L'API Ads Reporting pour les cadres cloisonnés et les iframes vous permet d'associer les données au niveau des événements utilisateur d'un cadre d'annonce à des signaux dans une enchère Protected Audience.

Dans un worklet de reporting de l'API Protected Audience, vous pouvez enregistrer une balise publicitaire avec la fonction registerAdBeacon() et transmettre votre URL de reporting 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 rapport. Ensuite, à un moment ultérieur, lorsque l'annonce est affichée dans un cadre cloisonné, 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 reporting. Elle n'est pas disponible dans la logique d'enchères de l'acheteur ni dans la logique de scoring 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 Fenced Frames Ads Reporting sera également disponible au moins jusqu'en 2026 pour les mêmes raisons que le reporting des enchères gagnantes.

Pour en savoir plus, consultez l'explication.

Accès au réseau sans restriction

Les cadres isolés permettent de charger des ressources réseau de la même manière qu'une iframe. Vous pouvez envoyer des données au niveau de l'événement dans des cadres isolé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 enchère 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, y effectuer un achat, et vous souhaitez attribuer cet achat à l'annonce qui a été 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 de trouver une solution plus permanente, vous pouvez utiliser l'API Ads Reporting pour les cadres cloisonnés comme mécanisme de transition permettant de générer un rapport agrégable et au niveau des événements avec Attribution Reporting. Notez que ces rapports permettent de mesurer les conversions. Ils sont distincts des rapports agrégables et au niveau des événements sur l'engagement générés à partir de l'enchère et du cadre de l'annonce. Nous publierons un article explicatif pour une solution plus permanente lorsqu'elle sera prête.

Mécanisme de transition

Lorsque vous enregistrez une balise publicitaire, vous pouvez utiliser le mot clé reserved.top_navigation, qui ajoutera 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 associer des données au niveau de l'événement à la balise que vous avez enregistrée, vous pouvez appeler setReportEventDataForAutomaticBeacons() à partir du frame cloisonné 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 cadre 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 fenced frame ou de l'iframe 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'identifiant peut être défini en tant que variable, par exemple auctionId. L'ID 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 publicitaire, 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 du beacon.
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 au beacon 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. Pendant le délai de conversion, vous pouvez déclencher la source que vous avez enregistrée pendant le délai d'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 associés à une clé unique permettant de les mettre en corrélation.

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 la SSP doit également être présente 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 bruité 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, car il ne révèle pas d'informations sur chaque événement individuel. Un rapport au niveau de l'événement vous permet de 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 ayant vu la campagne 123. Du 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 les 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 scoring du vendeur et de reporting de l'acheteur/du vendeur.

Dans cet exemple, l'enchère gagnante est agrégée dans le bucket du propriétaire du groupe 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 de l'événement et ne sont pas déclenchés par un événement en dehors de l'enchère. Pour en savoir plus sur le signalement des signaux d'enchères, consultez l'explication.

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

Vous pouvez agréger les 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 agrégée le nombre de clics qu'une annonce d'une campagne a reçus 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 joindre de charge utile au niveau de l'événement.

Pour agréger les signaux d'enchères par événements, vous pouvez utiliser privateAggregation.contributeToHistogramOnEvent(eventType, contribution), qui prend une chaîne spécifiant 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 la combinaison de l'ID de campagne et de l'événement de clic, puis augmenter la valeur de ce bucket de 1 chaque fois que l'événement est déclenché.

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

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

Pour en savoir plus sur le déclenchement des contributions Private Aggregation à partir d'un frame, consultez l'explication.

Rapports sur les résultats et les performances des enchères

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

L'agrégation privée fournit une liste de valeurs de base à partir desquelles vous pouvez calculer le bucket et la valeur de votre contribution. Les valeurs de base disponibles pour les résultats d'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é refusée lors des enchères.

Lorsqu'une valeur de base est fournie, comme le montant de l'enchère gagnante, vous pouvez définir le montant à ajouter ou à soustraire à cette valeur, puis indiquer la valeur finale. Par exemple, si l'enchère gagnante de 5 € est fournie comme valeur de base, vous pouvez soustraire votre enchère de 2 € pour calculer la valeur réelle de 3 € correspondant à la différence entre votre enchère et celle du gagnant.

Rapports sur les résultats des enchères

Prenons l'exemple d'une enchère que vous avez perdue et pour laquelle vous souhaitez connaître l'écart entre votre enchère et le prix de clôture.

Pour connaître la différence entre votre enchère et celle gagnante, soustrayez votre enchère de celle 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 correspond à la valeur baseValue mise à l'échelle et décalée par la valeur offset. Pour en savoir plus, consultez l'explication.

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 le temps de génération des enchères et le temps des signaux d'enchères fiables de chaque acheteur avec son autorisation.

Pour en savoir plus, consultez l'explication.

Stocker les signaux d'enchères dans Shared Storage

Le stockage partagé est un stockage multi-origine non partitionné dans lequel vous pouvez écrire librement, mais qui est protégé par des portes d'accès lors de la lecture et du traitement des valeurs stockées. Private Aggregation est l'une des portes disponibles pour l'API Shared Storage. Vous ne pouvez lire les valeurs du stockage partagé qu'à l'intérieur d'un worklet, et vous pouvez les signaler à l'aide de l'agrégation privée à partir du worklet.

Vous pouvez également écrire dans le stockage partagé à partir des worklets d'enchères, de scoring et de reporting de l'API Protected Audience. Vous pourrez ensuite signaler ces valeurs dans le 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 de l'URL.

À partir d'un worklet de l'API Protected Audience, vous pouvez écrire des clés et des valeurs dans le stockage partagé :

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

Vous pourrez charger un worklet Shared Storage ultérieurement pour lire et envoyer cette valeur avec Private Aggregation :

// 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 le stockage partagé, consultez la section sur le stockage partagé du guide du développeur sur le reporting de l'API Protected Audience, l'explication, 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.