Présentation de l'API Private Aggregation

Générez des rapports de données agrégées à l'aide des données de Protected Audience et des données intersites 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 de l'implémentation

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

La fonction principale de cette API est appelée contributeToHistogram(). 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 cumulables 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 polyvalente pour la mesure intersites. Elle peut être utilisée dans les worklets Shared Storage et API 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.

Attribution multitouch

Ces conseils doivent être publiés sur le site pour les développeurs afin que les technologies publicitaires puissent comprendre comment implémenter MTA dans le stockage partagé et l'agrégation privée.

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 la base d'un déclencheur à l'aide de contributeToHistogramOnEvent(), une extension spéciale de 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 est 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 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 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 qui permet d'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 de gain d'enchère est déclenché, et un rapport sur les clics si un événement click est déclenché à partir du frame clôturé qui a affiché 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 les 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é.

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.

• GitHub: lisez l'explication, posez des questions et participez à la discussion.
• Assistance aux développeurs: posez des questions et participez à des discussions dans le dépôt de l'assistance aux développeurs Privacy Sandbox.
• Rejoignez le groupe de l'API Shared Storage et le groupe de l'API Protected Audience pour recevoir les dernières annonces sur Private Aggregation.