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

Dans cet article, vous trouverez une présentation générale des différents mécanismes disponibles pour signaler les données d'enchères de l'API Protected Audience à votre serveur, ainsi que les mécanismes de transition disponibles dès maintenant pendant la migration jusqu'à ce que d'autres solutions soient prêtes.

Pour générer des rapports sur les métriques importantes que vous collectez lors d'enchères publicitaires, l'API Protected Audience fonctionne avec:

• L'agrégation privée 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 cloisonnés et les iFrames est un canal dans les frames permettant de communiquer avec les Worklets de l'API Protected Audience. L'API permet d'associer des données au niveau de l'événement à des signaux d'enchères. La création de rapports au niveau des événements dans l'API Ads Reporting est un mécanisme de transition jusqu'à ce qu'un mécanisme de reporting plus privé soit conçu.
• Attribution Reporting, qui vous permet d'associer les données de conversion aux signaux d'enchères.
• Le stockage partagé vous permet d'écrire des signaux d'enchères dans un stockage multi-origine, puis de créer des rapports sur ces données par la suite à l'aide de Private Aggregation.

Présentation des rapports de l'API Protected Audience

</ph>

Il existe trois périodes principales au cours desquelles les données du flux d'enchères de l'API Protected Audience peuvent être enregistrées sur votre serveur: la date et l'heure de l'enchère lorsque l'enchère est exécutée à partir du site de l'éditeur, le délai d'affichage lorsque l'annonce est affichée dans un cadre clôturé ou un iFrame sur le site de l'éditeur, et la date et l'heure de la conversion lorsque l'utilisateur effectue une action sur un autre site qui peut être attribué à 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 création de rapports. Pendant le délai d'affichage, vous pouvez générer des rapports sur les données d'engagement à partir d'un iFrame ou d'un frame cloisonné. Au moment de la conversion, vous pouvez générer des rapports sur les données d'attribution depuis la page de destination à l'aide de l'API Attribution Reporting.

Zones géographiques signalées

Lors d'une mise aux enchères, les acheteurs peuvent signaler les signaux disponibles dans les Worklets generateBid() et reportWin(), tandis que les vendeurs peuvent signaler les signaux disponibles dans scoreAd() et reportResult(). En dehors des enchères, les acheteurs et les vendeurs peuvent fournir des données à partir d'un cadre ayant affiché l'annonce et sur le site à partir duquel la conversion a été effectuée.

Au cours de chacune des périodes indiquées, les acheteurs et les vendeurs ont accès à diverses API de création de rapports qui leur permettent de 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 mise aux enchères de l'API Protected Audience

Les données suivantes peuvent être enregistrées à partir d'un Worklet de l'API Protected Audience lors de l'enchère.

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 de navigateur mises à la disposition des acheteurs et des vendeurs dans un Worklet. Ils permettent de générer une enchère, de noter une annonce et de générer un rapport sur les résultats d'une mise aux enchères.

L'objet Configuration des enchères est la principale source de données fournies pour être disponibles sous forme de 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 sur les groupes d'intérêt de l'acheteur, les données au niveau de l'événement provenant du cadre de rendu de l'annonce et les données d'attribution de la page de destination. Les données indiquées peuvent être utilisées pour créer des rapports sur les acheteurs et les vendeurs, la facturation, la budgétisation, l'entraînement de modèles de ML et plus encore.

Autres données disponibles

• Données de résultats liées aux données sur les enchères remportées et perdues, telles que le prix de l'enchère gagnante et le motif du refus de l'enchère.
• Des données sur les performances qui contiennent des informations de latence, telles que 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 des enchères de l'API Protected Audience, les données peuvent être enregistrées pour deux périodes.

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 à l'intérieur du cadre iFrame ou cloisonné 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 survols et tout autre événement se produisant dans le frame.

Au moment de la conversion, lorsqu'un utilisateur effectue une action sur la page de clic qui est ré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. Il peut s'agir d'une mise aux enchères, d'une impression d'annonce ou d'une conversion. Jusqu'en 2026, les rapports sur les enchères gagnantes 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 illimité peut être utilisé pour le reporting au niveau des événements. De plus, l'API Ads Reporting est disponible dans des cadres cloisonnés et des cadres iFrame, ce qui vous permet d'associer les données d'enchères et de conversion aux données au niveau des événements du cadre. Cette approche est conçue pour faciliter la migration de l'écosystème, car vous pouvez continuer à utiliser votre infrastructure de reporting existante au moins jusqu'en 2026 pendant que vous migrez votre système vers Protected Audience.

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

Un mécanisme disponible pour créer des rapports sur les données au niveau des événements dans une enchère Protected Audience est l'sendReportTo() function lors d'une mise aux enchères remportée. Cette fonction est disponible dans les Worklets de création de rapports sur 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 indiquer le montant de l'enchère gagnante à partir du Worklet reportWin() pour la 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 victoires pour le vendeur lorsqu'elle est appelée depuis reportResult(), et un rapport sur les victoires pour l'acheteur lorsqu'elle est appelée depuis reportWin(). La fonction sendReportTo() est disponible au moins jusqu'en 2026,

Le rapport "Engagement"

Un rapport sur l'engagement contient les données au niveau de l'événement provenant d'une création publicitaire, telles que les données sur les impressions ou les clics, qui sont associées aux signaux de la mise aux enchères de l'API Protected Audience qui a déclenché la diffusion de l'annonce. Étant donné que l'annonce est diffusée une fois la mise aux enchères terminée, les signaux associés ne sont pas disponibles dans le cadre qui affiche l'annonce. Pour associer ces données de différentes périodes, nous vous proposons deux mécanismes de transition afin de 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 provenant d'un iFrame, mais elle ne fonctionne pas pour un frame cloisonné. En effet, un identifiant unique ne peut pas être transmis depuis l'outil d'intégration, car la communication entre celui-ci et le frame cloisonné est limitée. Vous pouvez utiliser l'API Ads Reporting pour associer des données d'enchères aux données au niveau de l'événement d'une annonce avec frames cloisonnés.

API Ads Reporting pour les cadres cloisonnés et iFrame

L'API Ads Reporting pour les cadres cloisonnés et les iFrames vous permet d'associer les données au niveau de l'événement utilisateur d'un frame publicitaire aux signaux d'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 rapport avec les signaux ajoutés en tant que paramètres de requête. Vous spécifiez également l'événement personnalisé que vous souhaitez associer à l'URL de rapport. Ensuite, lorsque l'annonce sera affichée dans un cadre cloisonné, vous pourrez déclencher l'événement personnalisé en appelant la fonction window.fence.reportEvent(). Les données disponibles dans la trame cloisonnée 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 d'évaluation 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 jusqu'en 2026 au moins pour les mêmes raisons que les rapports sur les victoires.

Pour en savoir plus, consultez l'explication.

Accès réseau illimité

Les frames cloisonnés permettent de charger des ressources réseau de la même manière qu'un iFrame, et vous pouvez envoyer à votre serveur des données au niveau de l'événement dans des frames cloisonnés. Par la suite, vous pourrez générer des rapports au niveau des événements côté serveur en associant les données au niveau de l'événement d'un frame cloisonné aux données d'enchères envoyées avec sendReportTo(). Ces données ont été abordées 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 sélectionnée à partir 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, y effectuer un achat, et vous souhaitez attribuer cet achat à l'annonce diffusée. L'API Attribution Reporting sera intégrée à l'API Protected Audience afin de combiner les données d'enchères du site de l'éditeur et les données de conversion du site de l'annonceur.

Nous concevons une solution plus permanente, mais vous pouvez utiliser l'API Ads Reporting pour les cadres cloisonnés. Il s'agit d'un mécanisme de transition pour générer un rapport agrégable au niveau des événements avec Attribution Reporting. Notez que ces rapports servent à mesurer les conversions. Ils sont distincts des rapports sur l'engagement au niveau des événements et des rapports agrégés sur l'engagement générés à partir des enchères et du frame d'annonce. Nous publierons une vidéo explicative 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. Celui-ci 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 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 description 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 du système d'enchères, du cadre publicitaire et du site de conversion.

Au cours de ce processus, 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 cadre cloisonné 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 la mise aux enchères, l'acheteur envoie un identifiant 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'ID est transmis en tant que perBuyerSignals dans auctionConfig et devient disponible dans les Worklets de l'acheteur.
2. Au moment des enchères, l'acheteur peut enregistrer une balise publicitaire qui sera déclenchée pendant le délai d'affichage de l'annonce et la date et l'heure de la conversion (registerAdBeacon()). <ph type="x-smartling-placeholder">
   </ph>
   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 la 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, tous regroupés par une seule clé unique qui peut être utilisée pour s'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 la SSP doit également être présente sur la page de destination pour que le déclencheur soit attribué à la source.

Agréger des données Protected Audience

L'API Private Aggregation est le mécanisme utilisé pour générer un rapport sur les données de l'API Protected Audience pour générer un rapport récapitulatif, qui est un rapport agrégé avec 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 ensembles, chaque segment représentant une campagne publicitaire différente. Le rapport récapitulatif diffère d'un rapport au niveau des événements, car il ne fournit aucune information 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. Grâce aux rapports récapitulatifs, vous pouvez mesurer le nombre d'utilisateurs ayant vu la campagne 123 et ajouter du bruit afin de protéger la confidentialité des utilisateurs.

Pour en savoir plus sur l'API, consultez l'article sur l'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 Private Aggregation. Pour l'agrégation des signaux, vous pouvez utiliser la méthode privateAggregation.contributeToHistogram() disponible dans le Worklet d'enchères de l'acheteur, le Worklet d'évaluation du vendeur et les Worklets de création de rapports Acheteur/Vendeur.

Dans cet exemple, l'enchère gagnante est agrégée dans l'ensemble des propriétaires du groupe de centres 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 ni déclenchés par un événement en dehors de la mise aux enchères. Pour en savoir plus sur les rapports sur les signaux des enchères, consultez l'explication.

Agréger les signaux d'enchères avec les données d'événement

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 globalement 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 qu'à partir du frame publicitaire, 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 de mise aux enchères par événement, vous pouvez utiliser privateAggregation.contributeToHistogramOnEvent(eventType, contribution), qui accepte 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 reçus par une annonce pour 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 segment correspondant à la combinaison de l'ID de campagne et de l'événement de clic, puis augmenter sa valeur de 1 chaque fois que l'événement est déclenché.

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

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

Pour en savoir plus sur le déclenchement de contributions à l'agrégation privée à partir d'un frame, consultez cette explication.

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 lorsqu'ils sont déclenchés par un événement de victoire ou de perte 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).

Private Aggregation 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 de l'enchère sont la valeur de l'enchère de l'annonce gagnante, la valeur de l'enchère qui a obtenu la deuxième note la plus élevée et le motif du refus d'une enchère de l'enchère.

Lorsqu'une valeur de base est fournie, comme le montant de l'enchère gagnante, vous pouvez définir le montant à ajouter ou soustraire de cette valeur, puis indiquer la valeur finale. Par exemple, si vous définissez l'enchère gagnante (5 €) comme valeur de base, vous pouvez soustraire votre enchère de 2 € afin de calculer la valeur réelle de 3 € du nombre de pertes que vous avez enregistrées lors de votre mise aux enchères.

Rapports sur les résultats des enchères

Prenons un exemple dans lequel vous avez perdu une enchère et vous souhaitez connaître la différence entre votre enchère et le prix d'équilibre.

Pour connaître le montant de votre perte lors de l'enchère, soustrayez le prix de l'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 
    }
  });
}

Lors de l'envoi du rapport, la valeur réelle indiquée correspond au baseValue mis à l'échelle décalé de la valeur offset. Pour en savoir plus, consultez l'explication.

Rapports sur les performances

Les acheteurs et les vendeurs peuvent indiquer la durée d'exécution d'un script et le temps nécessaire pour extraire les signaux fiables. Avec leur autorisation, 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.

Pour en savoir plus, consultez l'explication.

Stocker les signaux d'enchères dans Shared Storage

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

Vous pouvez également écrire sur un espace de stockage partagé à partir des outils d'enchères, d'évaluation et de reporting de l'API Protected Audience. Par la suite, vous pourrez enregistrer ces valeurs dans le stockage partagé sur votre serveur à l'aide de Private Aggregation . Vous pouvez également utiliser les valeurs stockées pour l'opération de 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);
}

Par la suite, vous pouvez charger un Worklet de stockage partagé pour lire et envoyer cette valeur à l'aide de 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 dédiée au stockage partagé du guide du développeur concernant les rapports de l'API Protected Audience, une explication, une 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.