Cette page a été traduite par l'API Cloud Translation.

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 du stockage partagé.

Pour fournir des fonctionnalités essentielles sur lesquelles s'appuie le Web, l'API Private Aggregation a été conçue pour agréger des données intersites et créer des rapports les concernant, tout en protégeant la confidentialité.

État de l'implémentation

Proposition	État
Empêcher les rapports non valides de l'API Private Aggregation grâce à la validation des rapports pour le stockage partagé Explication	Disponible dans Chrome
La disponibilité du mode débogage de l'agrégation privée dépend de l'éligibilité à 3PC Problème GitHub	Disponible dans Chrome M119
Réduire le délai de création des rapports Explication	Disponible dans Chrome M119
Compatibilité avec l'API Private Aggregation et le service d'agrégation pour Google Cloud Explication	Disponible dans Chrome M121
Marge intérieure pour les charges utiles de rapports agrégables Explication	Disponible dans Chrome M119
Mode débogage de l'agrégation privée disponible pour les rapports enchèreReportBuyers Explication	Disponible dans Chrome M123
Prise en charge des ID de filtrage Explication	Lancement initial prévu dans Chrome au deuxième trimestre 2024.

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

L'API Private Aggregation permet aux développeurs de générer des rapports de données agrégés avec des données de l'API Protected Audience et des données intersites de Shared Storage.

Cette API fournit actuellement une opération, sendHistogramReport(), mais d'autres seront peut-être compatibles à l'avenir. L'opération d'histogramme vous permet d'agréger des données sur les utilisateurs de 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 sous la forme d'un rapport récapitulatif. Par exemple, le rapport peut indiquer le nombre de sites sur lesquels chaque utilisateur a vu votre contenu ou rencontrer 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 le stockage partagé, vous pouvez utiliser l'API Private Aggregation pour créer un histogramme indiquant le nombre approximatif d'utilisateurs de New York ayant vu votre contenu sur plusieurs sites. Pour agréger les données de 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 collecte et traitement par lot. 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 de synthèse.

Attribution Reporting associe les données collectées à partir d'un événement d'impression et de conversion, qui se produisent à des moments différents. L'agrégation privée mesure un événement unique intersite.

Tester cette API

Vous pouvez tester l'API Private Aggregation en local en activant l'indicateur de test des API Privacy Sandbox Ads sur chrome://flags/#privacy-sandbox-ads-apis.

Activer le test des API Privacy Sandbox Ads pour utiliser ces API

Pour en savoir plus sur les tests, consultez l'article Faire un test et participer.

Utiliser la version de démonstration

La version de démonstration de l'API Private Aggregation pour le stockage partagé est accessible sur 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 qui est envoyé à votre serveur.

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

Cas d'utilisation

Private Aggregation est une API à usage général pour les mesures multisites. Elle est disponible dans les Worklets de stockage partagé et d'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, tandis que l'API Private Aggregation vous permet de mesurer les données intersites stockées dans le stockage partagé.

Mesure de la couverture unique

Vous pouvez déterminer le nombre d'utilisateurs uniques ayant vu leur contenu. L'API Private Aggregation peut fournir une réponse telle que "Environ 317 utilisateurs uniques ont vu Content ID 861".

Dans le stockage partagé, vous pouvez définir un indicateur 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 à l'agrégation privée est effectué, puis l'indicateur est défini. Lors des visites ultérieures de l'utilisateur, y compris sur plusieurs sites, vous pouvez vérifier le stockage partagé et ignorer l'envoi d'un rapport à l'agrégation privée si l'indicateur est défini.

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.

L'agrégation privée peut fournir une réponse telle que "Environ 317 utilisateurs uniques sont âgés de 18 à 45 ans et résident en Allemagne". Utilisez le stockage partagé pour accéder aux données démographiques d'un contexte tiers. Par la suite, vous pourrez générer un rapport avec l'agrégation privée en encodant les dimensions "tranche d'âge" et "pays" dans la clé d'agrégation.

Mesure de 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édéfinie de K.

L'agrégation privée peut fournir une réponse telle que "Environ 89 utilisateurs ont vu le Content ID 581 au moins trois fois". Un compteur peut être incrémenté dans le stockage partagé à partir de différents sites et peut être lu dans un worklet. Lorsque le nombre a atteint K, un rapport peut être envoyé via l'agrégation privée.

Avec l'API Protected Audience

L'API Protected Audience permet de recibler des cas d'utilisation d'audiences personnalisées, tandis que Private Aggregation vous permet de créer des rapports sur les événements de Worklets d'acheteurs et de vendeurs. L'API peut être utilisée pour des tâches telles que la mesure de la distribution des enchères.

À partir d'un worklet d'API Protected Audience, vous pouvez agréger vos données directement à l'aide de sendHistogramReport() et créer des rapports sur vos données en fonction d'un déclencheur en utilisant reportContributionForEvent(), 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 stockage partagé 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 comme value. Pour le paramètre bucket, un élément BigInt est requis. Pour le paramètre value, un nombre entier est requis.

Voici un exemple de la façon dont elle peut être appelée dans le stockage partagé pour mesurer 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 inter-sites est chargé. Le code iFrame charge le worklet, qui appelle l'API Private Aggregation avec l'ID 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 un déclencheur pour envoyer un rapport uniquement si un certain événement se produit. Cette fonction permet également que le bucket et la valeur dépendent de signaux qui ne sont pas encore disponibles à ce stade de l'enchère.

La méthode privateAggregation.reportContributionForEvent(eventType, contribution) utilise un eventType qui spécifie l'événement déclencheur et le contribution à envoyer lorsque l'événement est déclenché. L'événement déclencheur peut provenir de l'enchère elle-même une fois l'enchère terminée (par exemple, un événement de victoire ou de perte d'enchères) ou d'un frame cloisonné qui a affiché 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 à partir d'un frame 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 servir à 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 des rapports d'agrégation privés étendus.

enableDebugMode()

Même si les cookies tiers sont toujours disponibles, nous fournissons un mécanisme temporaire qui facilite 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 à celles de votre agrégation privée. 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 en mode silencieux. Cela signifie que lorsque les cookies tiers seront obsolètes, 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 à celles de la mesure Private Aggregation. Celles-ci ne peuvent être appelées qu'une seule fois par contexte. Tous les appels ultérieurs seront ignorés.

// 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 la légitimité des rapports agrégables que vous avez reçus en ajoutant un ID de contexte à l'appel d'opération de stockage partagé. L'ID sera joint au rapport envoyé. Par la suite, vous pourrez l'utiliser pour vérifier que le rapport a bien été envoyé depuis votre opération d'espace de stockage partagé.

Cette fonctionnalité est disponible à des fins de test dans Chrome M114 et versions ultérieures. La validation des rapports de 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 donner votre avis

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: consultez l'explication, soulevez des questions et participez à la discussion.
Assistance aux développeurs: posez des questions et participez à des discussions sur 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 suivre les dernières annonces concernant l'agrégation privée.