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 agrégées à l'aide des données de Protected Audience et des données intersites de Shared Storage.

Pour fournir des fonctionnalités essentielles sur lesquelles le Web s'appuie, l'API Private Aggregation a été conçue pour agréger et créer des rapports sur les données intersites de manière respectueuse de la confidentialité.

État de l'implémentation

Proposition	État
Empêcher les rapports incorrects de l'API Private Aggregation grâce à la validation des rapports pour Shared Storage Explication	Disponible dans Chrome
Disponibilité du mode débogage de l'agrégation privée en fonction de l'éligibilité des tiers Problème GitHub	Disponible dans Chrome M119
Réduire le délai de génération des rapports Explication	Disponible dans Chrome M119
Délai avant expiration de la contribution Private Aggregation pour le stockage partagé Explication	Disponible dans M119
Compatibilité avec l'API Private Aggregation et le service d'agrégation pour Google Cloud Présentation	Disponible dans Chrome M121
Marge intérieure pour les charges utiles de rapports agrégables Explication	Disponible dans Chrome M119
Mode de débogage de l'agrégation privée disponible pour les rapports auctionReportBuyers Explication	Disponible dans Chrome M123
Assistance liée au filtrage des ID Explication	Disponible dans Chrome M128
Fusion des contributions côté client Explication	Disponible dans Chrome M129

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ées avec les données de l'API Protected Audience et les données intersites de Shared Storage.

La fonction principale de cette API est appelée contributeToHistogram(). L'opération d'histogramme vous permet d'agréger les données de tous 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é 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 détecter 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 qui indique approximativement le nombre d'utilisateurs à 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 comptabiliser 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 groupés sont ensuite traités par le service d'agrégation, et 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 de l'API Private Aggregation.

Différences par rapport aux rapports sur l'attribution

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çue pour les mesures intersites en association avec des API telles que l'API Protected Audience et Shared Storage. Les deux API génèrent des rapports agrégables qui sont consommés par le backend du service d'agrégation pour générer des rapports récapitulatifs.

Les rapports sur l'attribution associent 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 de confidentialité des annonces sous chrome://settings/adPrivacy.

Pour en savoir plus sur les tests, consultez Tester et participer.

Utiliser la démo

Vous pouvez accéder à la démonstration de l'API Private Aggregation pour Shared Storage 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 produit 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éterminer précisément les informations que vous souhaitez collecter. Ces points de données constituent la base de vos clés d'agrégation.

Avec le stockage partagé

Shared Storage vous permet de lire et d'écrire des données intersites dans un environnement sécurisé pour éviter les fuites. L'API Private Aggregation vous permet de mesurer les données intersites stockées dans Shared Storage.

Mesure de la couverture unique

Vous pouvez mesurer le nombre d'utilisateurs uniques qui ont vu votre contenu. L'API Private Aggregation peut fournir une réponse telle que "Environ 317 utilisateurs uniques ont vu le contenu 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 à l'agrégation privée est effectué, puis l'indicateur est défini. Lors des visites ultérieures de l'utilisateur, y compris les visites intersites, vous pouvez vérifier le stockage partagé et ne pas envoyer de rapport à l'agrégation privée si l'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 vu votre contenu sur différents sites.

L'agrégation privée peut fournir une réponse, par exemple : "Environ 317 utilisateurs uniques ont entre 18 et 45 ans et sont situés en Allemagne." Utilisez Shared Storage pour accéder aux données démographiques à partir d'un contexte tiers. Vous pourrez générer un rapport avec l'agrégation privée ultérieurement en encodant les dimensions "Catégorie d'âge" et "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 de K prédéfinie.

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

Attribution multipoint

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

Avec l'API Protected Audience

L'API Protected Audience permet de retargeter les utilisateurs et d'utiliser des audiences personnalisées. Private Aggregation vous permet de créer des rapports sur les événements provenant des worklets acheteur et vendeur. L'API peut être utilisée pour des tâches telles que 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 l'API 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 obligatoire. Pour le paramètre value, un nombre entier est requis.

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';

    // Don't 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 précédent appelle l'agrégation privée chaque fois que le contenu de l'iframe intersites 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 n'envoyer un rapport que si un événement spécifique 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) prend 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ère), ou d'un frame clôturé qui a généré 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 cadre clôturé, définissez un type d'événement personnalisé. Pour déclencher l'événement à partir d'un frame clôturé, 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 des rapports d'agrégation privée étendue.

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 vous permet de comparer vos mesures basées sur les cookies à vos mesures d'agrégation privée. Il vous permet également de valider rapidement votre intégration d'API.

Appeler privateAggregation.enableDebugMode() dans le worklet active le mode débogage, ce qui entraîne l'inclusion de la charge utile non chiffrée (en 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.

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

Ils ne peuvent être appelés qu'une seule fois par contexte. Les appels suivants génèrent une exception.

// Enables debug mode
privateAggregation.enableDebugMode();

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

Validation du rapport

L'API Private Aggregation permet de mesurer les données entre les sites tout en protégeant la confidentialité des utilisateurs. Toutefois, les acteurs malintentionnés peuvent tenter de manipuler la justesse de ces mesures. Pour éviter cela, vous pouvez utiliser un ID de contexte pour vérifier l'authenticité des rapports.

Définir un ID de contexte permet de s'assurer que les données sont exactes lorsqu'elles contribuent aux résultats agrégés finaux. Pour ce faire, procédez comme suit:

Empêcher les rapports illégitimes ou non authentiques:assurez-vous que les rapports sont générés via des appels d'API légitimes et authentiques, ce qui rend la fabrication de rapports difficile pour les acteurs malveillants.
Empêcher la lecture des rapports:détectez et rejetez toute tentative de réutilisation d'anciens rapports, en vous assurant que chaque rapport ne contribue qu'une seule fois aux résultats agrégés.

Stockage partagé

Lorsque vous utilisez Shared Storage pour exécuter une opération pouvant envoyer un rapport agrégable, vous pouvez définir un ID imprévisible en dehors du worklet.

Cet ID est intégré au rapport créé à partir du widget. Vous pouvez le spécifier lorsque vous appelez les méthodes de stockage partagé run() ou selectURL(), dans l'objet d'options sous la clé privateAggregationConfig.

Exemple :

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

Une fois cet ID défini, vous pouvez l'utiliser pour vérifier que le rapport a été envoyé depuis votre opération de stockage partagé. Pour éviter toute fuite d'informations, un seul rapport est envoyé par opération de stockage partagé (même si aucune contribution n'est apportée), quel que soit le nombre d'appels contributeToHistogram().

L'API Private Aggregation envoie des rapports agrégables avec un délai aléatoire pouvant aller jusqu'à une heure. Toutefois, définir un ID de contexte pour valider un rapport réduit ce délai. Dans ce cas, un délai fixe et plus court de cinq secondes est appliqué au démarrage de l'opération de stockage partagé.

Exemple de workflow de validation des rapports

Exemple de workflow (comme illustré dans le diagramme ci-dessus):

L'opération de stockage partagé est exécutée avec une configuration d'agrégation privée spécifiant un ID de contexte, et un rapport agrégable est généré.
L'ID de contexte est intégré au rapport agrégable généré et envoyé à votre serveur.
Votre serveur collecte les rapports cumulables générés.
Les processus de votre serveur comparent l'ID de contexte de chaque rapport agrégable à vos ID de contexte stockés pour s'assurer de sa validité avant de regrouper les rapports et de les envoyer à votre service d'agrégation.

Validation de l'ID de contexte

Les rapports entrants sur votre serveur collecteur peuvent être validés de différentes manières avant d'être envoyés au service d'agrégation. Les rapports comportant des ID de contexte non valides peuvent être rejetés lorsque l'ID de contexte est:

Inconnu:si un rapport arrive avec un ID de contexte que votre système n'a pas créé, vous pouvez le supprimer. Cela empêche les acteurs inconnus ou malveillants d'injecter des données dans votre pipeline d'agrégation.
Un doublon:si vous recevez deux rapports (ou plus) avec le même ID de contexte, vous devez choisir celui que vous souhaitez supprimer.
Signalé par la détection de spam:
- Si vous détectez une activité suspecte de la part d'un utilisateur, par exemple un changement soudain de son activité, lorsque vous traitez son signalement, vous pouvez le supprimer.
- Vous pouvez stocker les rapports avec leurs ID de contexte et tous les signaux pertinents (par exemple, user-agent, source de référence, etc.). Plus tard, lorsque vous analyserez le comportement des utilisateurs et identifierez de nouveaux indicateurs de spam, vous pourrez réévaluer les rapports stockés en fonction de leurs ID de contexte et de leurs signaux associés. Vous pouvez ainsi supprimer les rapports d'utilisateurs présentant une activité suspecte, même s'ils n'ont pas été signalés initialement.

Interagir et envoyer 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 à nous faire, nous serions ravis de les recevoir.

GitHub: lisez la présentation, posez des questions et participez aux discussions.
Assistance pour les développeurs: posez des questions et participez aux discussions sur le dépôt d'assistance pour les développeurs de la Privacy Sandbox.
Rejoignez le groupe de l'API Shared Storage et le groupe de l'API Protected Audience pour obtenir les dernières annonces concernant l'agrégation privée.