Présentation de l'API Private Aggregation

Générez des rapports de données globales à l'aide des données de l'API Protected Audience et des données intersites issues de Shared Storage.

Pour fournir les fonctionnalités essentielles sur lesquelles s'appuie le Web, Private Aggregation L'API a été conçue pour agréger des données intersites et générer des rapports les concernant tout en préservant la confidentialité.

État d'implémentation

Proposition État
Évitez les rapports de l'API Private Aggregation non valides grâce à la validation des rapports pour le stockage partagé
Explication		 Disponible dans Chrome
Disponibilité du mode débogage de l'agrégation privée en fonction de l'éligibilité des cookies tiers
Problème GitHub		 Disponible dans Chrome M119
Réduction du délai de signalement
Contenu explicatif		 Disponible dans Chrome M119
Compatibilité avec l'API Private Aggregation et le service d'agrégation pour Google Cloud
Contenu explicatif		 Disponible dans Chrome M121
Marge intérieure pour les charges utiles de rapports agrégables
Contenu explicatif		 Disponible dans Chrome M119
Mode de débogage de l'agrégation Private Aggregation disponible pour les rapports purchaseReportBuyers
Contenu explicatif		 Prévues dans Chrome M123
Filtrage de la compatibilité des ID
Contenu explicatif		 Prévues dans Chrome M128

Qu'est-ce que l'API Private Aggregation ?

L'API Private Aggregation permet aux développeurs de générer des rapports sur les données agrégées à l'aide des données de l'API Protected Audience et des données intersites depuis Stockage partagé.

Cette API fournit actuellement une opération, contributeToHistogram(), mais d'autres peuvent être à l'avenir. L'opération d'histogramme vous permet d'agréger des données pour plusieurs utilisateurs dans chaque bucket (appelé clé d'agrégation dans l'API) que vous définissez. Votre appel d'histogramme accumule des valeurs et renvoie un résultat agrégé avec bruit dans sous la forme d'un rapport récapitulatif. Par exemple, il peut indiquer le nombre sur les sites sur lesquels chaque utilisateur a vu votre contenu ou qui a rencontré un bug dans votre script tiers. Cette opération est effectuée dans le Worklet d'une autre API.

Par exemple, si vous avez déjà enregistré des données démographiques et géographiques dans Shared Storage, vous pouvez utiliser l'API Private Aggregation pour créer un histogramme indiquant le nombre approximatif d'utilisateurs de New York qui ont vu votre contenu sur plusieurs sites. Pour agréger cette mesure, vous pouvez encoder la dimension géographique dans la clé d'agrégation et compter les utilisateurs dans la valeur agrégable.

Concepts clés

Lorsque vous appelez l'API Private Aggregation avec une clé d'agrégation et une valeur agrégable, le navigateur génère un rapport agrégable.

Les rapports agrégables sont envoyés à votre serveur pour être collectés et regroupés. Les rapports par lot sont traités ultérieurement par le service d'agrégation, puis un rapport récapitulatif est généré.

Consultez le document Principes de base de l'API Private Aggregation pour en savoir plus sur les concepts clés associés à l'API Private Aggregation.

Différences par rapport à Attribution Reporting

L'API Private Aggregation présente de nombreuses similitudes avec l'API Attribution Reporting. Attribution Reporting est une API autonome conçue pour mesurer les conversions, tandis que Private Aggregation est conçu pour les mesures intersites conjointement avec des API telles que l'API Protected Audience et Shared Storage. Les deux API produisent des rapports agrégables qui sont utilisés par le backend du service d'agrégation pour générer des rapports récapitulatifs.

Attribution Reporting associe les données collectées à partir d'un événement d'impression et d'un événement de conversion, qui se produisent à des moments différents. Private Aggregation mesure un seul événement intersites.

Tester cette API

Pour tester l'API Private Aggregation en local, activez toutes les API Ad Privacy sous chrome://settings/adPrivacy.

En savoir plus sur les tests et participation

Utiliser la version de démonstration

La démonstration de l'API Private Aggregation pour le stockage partagé est disponible à l'adresse goo.gle/shared-storage-demo, et le code est disponible sur GitHub. La démonstration implémente les opérations côté client et génère un rapport agrégable envoyé à votre serveur.

Une démonstration de l'API Private Aggregation pour l'API Protected Audience sera publiée à l'avenir.

Cas d'utilisation

Private Aggregation est une API à usage général pour les mesures intersites, disponible dans les Worklets Shared Storage et Protected Audience. La première étape consiste à décider précisément quelles informations vous souhaitez collecter. Ces points de données constituent la base de vos clés d'agrégation.

Avec stockage partagé

Le stockage partagé vous permet de lire et d'écrire des données intersites dans un environnement sécurisé pour éviter les fuites. De plus, l'API Private Aggregation vous permet de mesurer les données intersites stockées dans le stockage partagé.

Mesure de la Unique Reach

Vous voudrez peut-être mesurer le nombre d'utilisateurs uniques ayant vu son contenu. L'API Private Aggregation peut fournir une réponse telle que "Environ 317 utilisateurs uniques ont vu le Content ID 861".

Vous pouvez définir un indicateur dans Shared Storage pour indiquer si l'utilisateur a déjà vu le contenu ou non. Lors de la première visite où l'indicateur n'existe pas, un appel à Private Aggregation est effectué, puis l'indicateur est défini. Lors des visites ultérieures de l'utilisateur, y compris des visites intersites, vous pouvez vérifier le stockage partagé et ignorer l'envoi d'un rapport à Private Aggregation si cet indicateur est défini. Pour en savoir plus sur les méthodes d'implémentation de ces mesures, consultez notre livre blanc sur la couverture.

Mesure des données démographiques

Vous pouvez mesurer les données démographiques des utilisateurs qui ont consulté votre contenu sur différents sites.

Private Aggregation peut fournir une réponse, par exemple "Environ 317 utilisateurs uniques de 18 à 45 ans proviennent d'Allemagne". Utilisez le stockage partagé pour accéder à des données démographiques provenant d'un contexte tiers. Vous pourrez ensuite générer un rapport avec l'agrégation privée en codant les dimensions de tranche d'âge et de pays dans la clé d'agrégation.

Mesure de la fréquence K+

Vous pouvez mesurer le nombre d'utilisateurs ayant vu un contenu ou une annonce au moins K fois dans un navigateur donné, pour une valeur présélectionnée de K.

L'agrégation privée peut fournir une réponse du type "Environ 89 utilisateurs ont vu l'ID de contenu 581 au moins trois fois". Un compteur peut être incrémenté dans Shared Storage à partir de différents sites et lu au sein d'un Worklet. Lorsque le nombre a atteint K, un rapport peut être envoyé via Private Aggregation.

Avec l'API Protected Audience

L'API Protected Audience permet de recibler des audiences personnalisées et de personnaliser les cas d'utilisation, tandis que Private Aggregation vous permet de créer des rapports sur les événements des Worklets d'acheteurs et de vendeurs. L'API peut servir, par exemple, à mesurer la distribution des enchères.

À partir d'un Worklet de l'API Protected Audience, vous pouvez agréger vos données directement à l'aide de contributeToHistogram() et générer des rapports sur vos données en fonction d'un déclencheur à l'aide de contributeToHistogramOnEvent(), qui est une extension spéciale pour l'API Protected Audience.

Fonctions disponibles

Les fonctions suivantes sont disponibles dans l'objet privateAggregation disponible dans les Worklets de Shared Storage et de l'API Protected Audience.

contributeToHistogram()

Vous pouvez appeler privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }), où la clé d'agrégation est bucket et la valeur agrégable en value. Pour le paramètre bucket, un BigInt est requis. Pour le paramètre value, vous devez saisir un nombre entier.

Voici un exemple d'appel dans Shared Storage pour la mesure de la couverture:

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', { 
  data: { contentId: '1234' } 
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){ 
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling" 
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await this.sharedStorage.get(key) === 'true';

    // Do not send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId), 
      value: 1 * SCALE_FACTOR 
    });

    // Set the flag in Shared Storage
    await this.sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

L'exemple de code ci-dessus appelle Private Aggregation chaque fois que le contenu iFrame intersite est chargé. Le code iFrame charge le Worklet, qui appelle l'API Private Aggregation avec l'identifiant de contenu converti en clé d'agrégation (bucket).

contributeToHistogramOnEvent()

Dans les Worklets de l'API Protected Audience uniquement, nous fournissons un mécanisme basé sur des déclencheurs pour envoyer un rapport uniquement si un certain événement se produit. Cette fonction permet également au bucket et à la valeur de dépendre de signaux qui ne sont pas encore disponibles à ce stade de l'enchère.

La méthode privateAggregation.contributeToHistogramOnEvent(eventType, contribution) utilise un élément eventType qui spécifie l'événement déclencheur et l'élément contribution à envoyer lorsque l'événement est déclenché. L'événement déclencheur peut provenir de l'enchère elle-même après la fin de celle-ci (par exemple, une victoire ou une défaite) ou d'un frame cloisonné ayant diffusé l'annonce. Pour envoyer un rapport sur les événements d'enchères, vous pouvez utiliser deux mots clés réservés : reserved.win, reserved.loss et reserved.always. Pour envoyer un rapport déclenché par un événement dans un cadre cloisonné, définissez un type d'événement personnalisé. Pour déclencher l'événement à partir d'un frame cloisonné, utilisez la méthode fence.reportEvent() disponible dans l'API Fenced Frames Ads Reporting.

L'exemple suivant envoie un rapport sur les impressions lorsque l'événement d'enchères remportées est déclenché, ainsi qu'un rapport sur les clics si un événement click est déclenché à partir du frame cloisonné qui a diffusé l'annonce. Ces deux valeurs peuvent être utilisées pour calculer le taux de clics. 

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

Pour en savoir plus, consultez la présentation de l'API Extended Private Aggregation Reporting.

enableDebugMode()

Bien que les cookies tiers soient toujours disponibles, nous fournirons un mécanisme temporaire qui facilitera le débogage et les tests en activant le mode débogage. Un rapport de débogage est utile pour comparer vos mesures basées sur les cookies à vos mesures Private Aggregation. Il vous permet également de valider rapidement votre intégration d'API.

L'appel de privateAggregation.enableDebugMode() dans le Worklet active le mode de débogage, ce qui entraîne l'inclusion de la charge utile non chiffrée (texte clair) dans les rapports agrégables. Vous pouvez ensuite traiter ces charges utiles avec l'outil de test local du service d'agrégation.

Le mode débogage n'est disponible que pour les appelants autorisés à accéder aux cookies tiers. Si l'appelant n'a pas accès aux cookies tiers, enableDebugMode() échouera silencieusement. Cela signifie que lorsqu'un tiers les cookies sont obsolètes et le mode débogage ne sera plus disponible.

Vous pouvez également définir la clé de débogage en appelant privateAggregation.enableDebugMode({ <debugKey: debugKey> }), où une BigInt peut être utilisée comme clé de débogage. La clé de débogage peut être utilisée pour associer les données d'une mesure basée sur les cookies et celles provenant de la mesure Private Aggregation.

Ceux-ci ne peuvent être appelés qu'une seule fois par contexte. Tous les appels ultérieurs génèrent une exception.

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

Signaler la validation

Pour le stockage partagé, vous pouvez vérifier que les rapports agrégables que vous avez reçus sont légitimes en ajoutant un ID de contexte à l'appel d'opération de stockage partagé. L'ID est joint au rapport envoyé. Vous pourrez l'utiliser ultérieurement pour vérifier que le rapport a bien été envoyé depuis votre espace de stockage partagé.

Cette fonctionnalité peut être testée dans Chrome M114 ou version ultérieure. La validation des rapports pour l'API Protected Audience n'est pas encore disponible à des fins de test.

Pour en savoir plus, consultez la présentation de la validation des rapports.

Interagir et partager des commentaires

L'API Private Aggregation est en cours de discussion et est susceptible d'être modifiée à l'avenir. Si vous essayez cette API et que vous avez des commentaires, n'hésitez pas à nous en faire part.