Principes de base de l'API Private Agrégation

Concepts clés de l'API Private Aggregation

À qui s'adresse ce document ?

L'API Private Aggregation permet de collecter des données agrégées à partir de worklets ayant accès aux données multisites. Les concepts présentés ici sont importants pour les développeurs qui créent des fonctions de reporting dans les API Shared Storage et Protected Audience.

• Si vous êtes un développeur qui crée un système de reporting pour la mesure multisite.
• Si vous êtes responsable marketing, data scientist ou autre consommateur de rapports récapitulatifs, comprendre ces mécanismes vous aidera à prendre des décisions de conception pour récupérer un rapport récapitulatif optimisé.

Termes clés

Avant de lire ce document, il est utile de vous familiariser avec les termes et concepts clés. Chacun de ces termes sera décrit en détail ici.

• Une clé d'agrégation (également appelée "bucket") est une collection prédéterminée de points de données. Par exemple, vous pouvez collecter un bucket de données de localisation où le navigateur indique le nom du pays. Une clé d'agrégation peut contenir plusieurs dimensions (par exemple, le pays et l'ID de votre widget de contenu).
• Une valeur agrégable est un point de données individuel collecté dans une clé d'agrégation. Si vous souhaitez mesurer le nombre d'utilisateurs en France qui ont vu votre contenu, France est une dimension dans la clé d'agrégation, et viewCount de 1 est la valeur agrégable.
• Les rapports agrégables sont générés et chiffrés dans un navigateur. Pour l'API Private Aggregation, il contient des données sur un seul événement.
• Le service d'agrégation traite les données des rapports agrégables pour créer un rapport récapitulatif.
• Un rapport récapitulatif est le résultat final du service d'agrégation. Il contient des données utilisateur agrégées bruitées et des données de conversion détaillées.
• Un worklet est un élément d'infrastructure qui vous permet d'exécuter des fonctions JavaScript spécifiques et de renvoyer des informations au demandeur. Dans un worklet, vous pouvez exécuter du code JavaScript, mais vous ne pouvez pas interagir ni communiquer avec la page externe.

Workflow Private Aggregation

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 sont envoyés à votre serveur, qui les regroupe. Les rapports par lot sont traités ultérieurement par le service d'agrégation, et un rapport récapitulatif est généré.

1. Lorsque vous appelez l'API Private Aggregation, le client (navigateur) génère et envoie le rapport agrégable à votre serveur pour qu'il soit collecté.
2. Votre serveur collecte les rapports des clients et les regroupe en lots à envoyer au service d'agrégation.
3. Une fois que vous avez collecté suffisamment de rapports, vous les regroupez et les envoyez au service d'agrégation, qui s'exécute dans un environnement d'exécution sécurisé, pour générer un rapport récapitulatif.

Le workflow décrit dans cette section est semblable à l'API Attribution Reporting. Toutefois, 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 multisite.

Clé d'agrégation

Une clé d'agrégation (ou "clé" en abrégé) représente le bucket dans lequel les valeurs agrégables seront cumulées. Une ou plusieurs dimensions peuvent être encodées dans la clé. Une dimension représente un aspect sur lequel vous souhaitez obtenir plus d'informations, comme la tranche d'âge des utilisateurs ou le nombre d'impressions d'une campagne publicitaire.

Par exemple, vous pouvez avoir un widget intégré à plusieurs sites et vouloir analyser le pays des utilisateurs qui l'ont vu. Vous souhaitez répondre à des questions telles que "Combien d'utilisateurs ayant vu mon widget proviennent du pays X ?". Pour générer des rapports sur cette question, vous pouvez configurer une clé d'agrégation qui encode deux dimensions : l'ID du widget et l'ID du pays.

La clé fournie à l'API Private Aggregation est un BigInt, qui se compose de plusieurs dimensions. Dans cet exemple, les dimensions sont l'ID du widget et l'ID du pays. Supposons que l'ID du widget puisse comporter jusqu'à quatre chiffres, comme 1234, et que chaque pays soit associé à un nombre dans l'ordre alphabétique (par exemple, l'Afghanistan est 1, la France est 61 et le Zimbabwe est 195). La clé agrégable comportera donc sept chiffres, dont les quatre premiers sont réservés à WidgetID et les trois derniers à CountryID.

Supposons que la clé représente le nombre d'utilisateurs en France (ID de pays 061) ayant vu le widget ID 3276. La clé d'agrégation est 3276061.

La clé d'agrégation peut également être générée avec un mécanisme de hachage, tel que SHA-256. Par exemple, la chaîne {"WidgetId":3276,"CountryID":67} peut être hachée, puis convertie en valeur BigInt de 42943797454801331377966796057547478208888578253058197330928948081739249096287n. Si la valeur de hachage comporte plus de 128 bits, vous pouvez la tronquer pour vous assurer qu'elle ne dépasse pas la valeur de bucket maximale autorisée de 2^128−1.

Dans un worklet Shared Storage, vous pouvez accéder aux modules crypto et TextEncoder qui peuvent vous aider à générer un hachage. Pour en savoir plus sur la génération d'un hachage, consultez SubtleCrypto.digest() sur MDN.

L'exemple suivant décrit comment générer une clé de bucket à partir d'une valeur hachée :

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

Valeur agrégable

Les valeurs agrégables sont additionnées par clé pour de nombreux utilisateurs afin de générer des insights agrégés sous la forme de valeurs récapitulatives dans les rapports récapitulatifs.

Revenons à la question posée précédemment : "Combien d'utilisateurs ayant vu mon widget sont originaires de France ?" La réponse à cette question ressemblera à quelque chose comme "Environ 4 881 utilisateurs ayant vu mon widget ID 3276 sont originaires de France". La valeur agrégable est de 1 pour chaque utilisateur, et "4 881 utilisateurs" correspond à la valeur agrégée, qui est la somme de toutes les valeurs agrégables pour cette clé d'agrégation.

Dans cet exemple, nous incrémentons la valeur de 1 pour chaque utilisateur qui voit le widget. En pratique, la valeur agrégable peut être mise à l'échelle pour améliorer le rapport signal/bruit.

Budget de contribution

Chaque appel à l'API Private Aggregation est appelé contribution. Pour protéger la confidentialité des utilisateurs, le nombre de contributions pouvant être collectées auprès d'une même personne est limité.

Lorsque vous additionnez toutes les valeurs agrégables pour toutes les clés d'agrégation, la somme doit être inférieure au budget de contribution. Le budget est défini par origine de worklet et par jour. Il est distinct pour les worklets de l'API Protected Audience et de Shared Storage. Une période glissante d'environ 24 heures est utilisée pour la journée. Si un nouveau rapport agrégable entraîne un dépassement du budget, il n'est pas créé.

Le budget de contribution est représenté par le paramètre L₁ et est défini sur 2¹⁶ (65 536) par tranche de 10 minutes par jour, avec un plafond de 2²⁰ (1 048 576). Pour en savoir plus sur ces paramètres, consultez l'explication.

La valeur du budget de contribution est arbitraire, mais le bruit est mis à l'échelle. Vous pouvez utiliser ce budget pour maximiser le rapport signal/bruit sur les valeurs récapitulatives (voir la section Bruit et mise à l'échelle pour en savoir plus).

Pour en savoir plus sur les budgets de contribution, consultez l'explication. Pour en savoir plus, consultez Budget de contribution.

Limite de contribution par rapport

La limite de contribution peut varier selon l'appelant. Pour le stockage partagé, ces limites sont des valeurs par défaut qui peuvent être remplacées. Pour le moment, les rapports générés pour les appelants de l'API Shared Storage sont limités à 20 contributions par rapport. En revanche, les appelants de l'API Protected Audience sont limités à 100 contributions par rapport. Ces limites ont été choisies pour équilibrer le nombre de contributions pouvant être intégrées et la taille de la charge utile.

Pour le stockage partagé, les contributions effectuées au cours d'une même opération run() ou selectURL() sont regroupées dans un seul rapport. Pour Protected Audience, les contributions d'une même origine dans une enchère sont regroupées.

Contributions avec marge intérieure

Les contributions sont ensuite modifiées à l'aide d'une fonctionnalité de marge intérieure. L'action de compléter la charge utile protège les informations sur le nombre réel de contributions intégrées dans le rapport agrégable. Le remplissage augmente la charge utile avec null contributions (c'est-à-dire avec une valeur de 0) pour atteindre une longueur fixe.

Rapports agrégables

Une fois que l'utilisateur appelle l'API Private Aggregation, le navigateur génère des rapports agrégables qui seront traités ultérieurement par le service d'agrégation pour générer des rapports récapitulatifs. Un rapport agrégable est au format JSON et contient une liste chiffrée de contributions, chacune étant une paire {aggregation key, aggregatable value}. Les rapports agrégables sont envoyés avec un délai aléatoire pouvant aller jusqu'à une heure.

Les contributions sont chiffrées et ne sont pas lisibles en dehors du service d'agrégation. Le service d'agrégation déchiffre les rapports et génère un rapport récapitulatif. La clé de chiffrement pour le navigateur et la clé de déchiffrement pour le service d'agrégation sont émises par le coordinateur, qui fait office de service de gestion des clés. Le coordinateur conserve une liste des hachages binaires de l'image de service pour vérifier que l'appelant est autorisé à recevoir la clé de déchiffrement.

Exemple de rapport agrégable avec le mode débogage activé :

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

Vous pouvez examiner les rapports agrégables sur la page chrome://private-aggregation-internals :

À des fins de test, le bouton "Envoyer les rapports sélectionnés" peut être utilisé pour envoyer immédiatement le rapport au serveur.

Collecter et regrouper les rapports agrégables

Le navigateur envoie les rapports agrégables à l'origine du worklet contenant l'appel à l'API Private Aggregation, en utilisant le chemin d'accès connu indiqué :

• Pour Shared Storage : /.well-known/private-aggregation/report-shared-storage
• Pour Protected Audience : /.well-known/private-aggregation/report-protected-audience

À ces points de terminaison, vous devrez utiliser un serveur (qui fait office de collecteur) qui reçoit les rapports cumulables envoyés par les clients.

Le serveur doit ensuite regrouper les rapports et envoyer le lot au service d'agrégation. Créez des lots en fonction des informations disponibles dans la charge utile non chiffrée du rapport agrégable, comme le champ shared_info. Idéalement, les lots doivent contenir au moins 100 rapports chacun.

Vous pouvez choisir de regrouper les paiements sur une base quotidienne ou hebdomadaire. Cette stratégie est flexible. Vous pouvez modifier votre stratégie de regroupement pour des événements spécifiques où vous prévoyez un volume plus important (par exemple, les jours de l'année où vous attendez plus d'impressions). Les lots doivent inclure des rapports de la même version d'API, de la même origine de rapport et de la même heure de rapport planifiée.

ID de filtre

L'API Private Aggregation et le service d'agrégation permettent d'utiliser des ID de filtrage pour traiter les mesures à un niveau plus précis, par exemple par campagne publicitaire, plutôt que de traiter les résultats dans des requêtes plus volumineuses.

Pour commencer à l'utiliser dès aujourd'hui, voici quelques étapes générales à appliquer à votre implémentation actuelle.

Étapes de Shared Storage

Si vous utilisez l'API Shared Storage dans votre flux :

1. Définissez l'emplacement où vous déclarerez et exécuterez votre nouveau module Shared Storage. Dans l'exemple suivant, nous avons nommé le fichier de module filtering-worklet.js, enregistré sous filtering-example.

   (async function runFilteringIdsExample () {
   await window.sharedStorage.worklet.addModule('filtering-worklet.js');
   await window.sharedStorage.run('filtering-example', {
     keepAlive: true,
     privateAggregationConfig: {
       contextId: 'example-id',
       filteringIdMaxBytes: 8 // optional
     }
   }});
   })();
   

   Notez que filteringIdMaxBytes est configurable par rapport et, s'il n'est pas défini, la valeur par défaut est 1. Cette valeur par défaut vise à éviter d'augmenter inutilement la taille de la charge utile, et donc les coûts de stockage et de traitement. Pour en savoir plus, consultez l'explication sur les contributions flexibles.

2. Dans filtering-worklet.js, lorsque vous transmettez une contribution à privateAggregation.contributeToHistogram(...) dans le worklet Shared Storage, vous pouvez spécifier un ID de filtrage.

   // Within  filtering-worklet.js
   class FilterOperation {
     async run() {
       let contributions = [{
         bucket: 1234n,
         value: 56,
         filteringId: 3n // defaults to 0n if not assigned, type bigint
       }];
   
       for (const c of contributions) {
         privateAggregation.contributeToHistogram(c);
       }
       …
   }
   });
   
   register('filtering-example', FilterOperation);
   

3. Les rapports agrégables seront envoyés au point de terminaison /.well-known/private-aggregation/report-shared-storage que vous avez défini. Consultez le guide sur les ID de filtrage pour en savoir plus sur les modifications à apporter aux paramètres des tâches du service d'agrégation.

Une fois le traitement par lot terminé et envoyé à votre service d'agrégation déployé, vos résultats filtrés devraient être reflétés dans votre rapport récapitulatif final.

Étapes de Protected Audience

Si vous utilisez l'API Protected Audience dans votre flux :

1. Dans votre implémentation actuelle de Protected Audience, vous pouvez définir les éléments suivants pour vous connecter à l'agrégation privée. Contrairement à Shared Storage, il n'est pas encore possible de configurer la taille maximale des ID de filtrage. Par défaut, la taille maximale de l'ID de filtrage est de 1 octet et est définie sur 0n. N'oubliez pas que ces valeurs seront définies dans vos fonctions de reporting Protected Audience (par exemple, reportResult() ou generateBid()).

   const contribution = {
     ...
     filteringId: 0n
   };
   
   privateAggregation.contributeToHistogram(contribution);
   

2. Les rapports agrégables seront envoyés au point de terminaison /.well-known/private-aggregation/report-protected-audience que vous avez défini. Une fois le traitement par lot terminé et envoyé à votre service d'agrégation déployé, vos résultats filtrés doivent être reflétés dans votre rapport récapitulatif final. Les documents explicatifs suivants pour l'API Attribution Reporting et l'API Private Aggregation sont disponibles, ainsi que la proposition initiale.

Consultez notre guide sur le filtrage des ID dans le service d'agrégation ou accédez aux sections sur l'API Attribution Reporting pour en savoir plus.

Service d'agrégation

Le service d'agrégation reçoit les rapports agrégables chiffrés du collecteur et génère des rapports récapitulatifs. Pour découvrir d'autres stratégies de traitement par lot des rapports cumulables dans votre collecteur, consultez notre guide sur le traitement par lot.

Le service s'exécute dans un environnement d'exécution sécurisé (TEE), qui offre un certain niveau d'assurance pour l'intégrité des données, leur confidentialité et l'intégrité du code. Pour en savoir plus sur l'utilisation des coordinateurs avec les TEE, consultez leur rôle et leur objectif.

Rapports récapitulatifs

Les rapports récapitulatifs vous permettent de consulter les données que vous avez collectées, auxquelles du bruit a été ajouté. Vous pouvez demander des rapports récapitulatifs pour un ensemble de clés donné.

Un rapport récapitulatif contient un ensemble de paires clé/valeur de type dictionnaire JSON. Chaque paire contient les éléments suivants :

• bucket : clé d'agrégation sous forme de chaîne de nombre binaire. Si la clé d'agrégation utilisée est "123", le bucket est "1111011".
• value : valeur récapitulative pour un objectif de mesure donné, obtenue en additionnant tous les rapports agrégables disponibles auxquels du bruit a été ajouté.

Exemple :

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

Bruit et scaling

Pour préserver la confidentialité des utilisateurs, le service d'agrégation ajoute du bruit une fois à chaque valeur récapitulative chaque fois qu'un rapport récapitulatif est demandé. Les valeurs de bruit sont tirées au hasard d'une distribution de probabilité de Laplace. Bien que vous ne contrôliez pas directement la façon dont le bruit est ajouté, vous pouvez influencer son impact sur les données de mesure.

La distribution du bruit est la même, quelle que soit la somme de toutes les valeurs agrégables. Par conséquent, plus les valeurs agrégables sont élevées, moins le bruit est susceptible d'avoir un impact.

Par exemple, supposons que la distribution du bruit ait un écart-type de 100 et soit centrée sur zéro. Si la valeur agrégable collectée du rapport (ou "valeur agrégable") n'est que de 200, l'écart-type du bruit sera de 50 % de la valeur agrégée. Toutefois, si la valeur agrégable est de 20 000,l'écart-type du bruit ne représenterait que 0, 5 % de la valeur agrégée. Ainsi, la valeur agrégable de 20 000 aurait un rapport signal/bruit beaucoup plus élevé.

Par conséquent, multiplier votre valeur agrégable par un facteur de scaling peut aider à réduire le bruit. Le facteur d'échelle représente l'ampleur de la mise à l'échelle d'une valeur agrégable donnée.

Si vous augmentez les valeurs en choisissant un facteur de scaling plus élevé, le bruit relatif diminue. Toutefois, cela entraîne également une augmentation plus rapide de la somme de toutes les contributions dans tous les buckets jusqu'à la limite du budget de contribution. En réduisant les valeurs en choisissant une constante de facteur de scaling plus petite, le bruit relatif augmente, mais le risque d'atteindre la limite de budget diminue.

Pour calculer un facteur de scaling approprié, divisez le budget de contribution par la somme maximale des valeurs agrégables pour toutes les clés.

Pour en savoir plus, consultez la documentation sur le budget de contribution.

Interagir et envoyer des commentaires

L'API Private Aggregation fait l'objet de discussions actives 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 les faire parvenir.

• GitHub : lisez l'explication, posez des questions et participez à la discussion.
  • Assistance pour les développeurs : posez des questions et participez à des discussions sur le dépôt d'assistance pour les 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 concernant Private Aggregation.