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

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 globales à partir de Worklets avec accès à des données intersites. Les concepts présentés ici sont importants pour les développeurs qui créent des rapports dans Shared Storage et l'API Protected Audience.

Vous êtes un développeur créant un système de création de rapports pour l'analyse intersites les mesures.
Si vous êtes responsable marketing, data scientist ou autre rapport récapitulatif consommateur, comprendre ces mécanismes vous aidera à rendre la conception pour récupérer un rapport de synthèse optimisé.

Termes clés

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

Une clé d'agrégation (également appelée "bucket") est un une collecte prédéterminée de points de données. Par exemple, vous pouvez collecter un ensemble de données de localisation, dans lequel le navigateur indique le pays ; son nom. Une clé d'agrégation peut contenir plusieurs dimensions (par exemple, le pays et l'identifiant de votre widget de contenu).
Une valeur agrégable est un point de données individuel collectées dans une clé d'agrégation. Si vous voulez mesurer le nombre d'utilisateurs français ont vu votre contenu, alors France est une dimension du clé d'agrégation, et le viewCount de 1 est la valeur agrégable.
Les rapports agrégables sont générés et chiffrés dans un navigateur. Pour le l'API Private Aggregation, qui 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 la sortie finale du service d'agrégation. contient des données utilisateur agrégées comportant du bruit et des données de conversion détaillées.
Un worklet est un élément de l'infrastructure, ce qui vous permet d'exécuter des fonctions JavaScript spécifiques renvoyer des informations au demandeur. Dans un Worklet, vous pouvez exécuter en JavaScript, mais vous ne pouvez pas interagir avec la page extérieure ni communiquer avec elle.

Workflow d'agrégation privée

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

Les données circulent du client vers le collecteur, puis vers l'agrégation
Service permettant de générer un rapport récapitulatif.

Lorsque vous appelez l'API Private Aggregation, le client (navigateur) génère et envoie le rapport agrégable à votre serveur pour être collecté.
Votre serveur collecte les rapports auprès des clients et les regroupe envoyées au service d'agrégation.
Une fois que vous avez collecté suffisamment de rapports, vous pouvez les regrouper et les envoyer le service d'agrégation, qui s'exécute dans un environnement d'exécution approuvé, pour générer un rapport récapitulatif.

Le flux de travail décrit dans cette section est semblable à celui de l'atelier Attribution Reporting API. Toutefois, l'attribution Les rapports associent les données collectées à partir d'un événement d'impression et d'une conversion qui se produisent à des moments différents. L'agrégation privée mesure un seul intersites.

Clé d'agrégation

Une clé d'agrégation ("clé") représente le bucket dans lequel des valeurs agrégables sont alors cumulées. Une ou plusieurs dimensions peuvent être encodées dans la clé. Une dimension représente un aspect que vous souhaitez obtenir des insights comme la tranche d'âge des utilisateurs ou le nombre d'impressions d'une annonce campagne.

Par exemple, vous pouvez avoir un widget intégré sur plusieurs sites et vous voulez analyser le pays des utilisateurs qui ont vu votre widget. Vous êtes en train de regarder pour répondre à des questions telles que "Combien d'utilisateurs ayant vu mon widget du pays X ?" Pour générer un rapport sur cette question, vous pouvez configurer une clé d'agrégation qui encode deux dimensions: l'identifiant du widget et l'identifiant du pays.

La clé fournie à l'API Private Aggregation est une clé BigInt qui comprend plusieurs dimensions. Dans cet exemple, les dimensions correspondent l'identifiant du widget et l'identifiant du pays. Imaginons que l'ID de widget peut comporter jusqu'à 4 chiffres long comme 1234, et chaque pays est associé à un chiffre alphabétique pour l'Afghanistan, 1, 61 pour la France et "195" pour le Zimbabwe. Par conséquent, la clé agrégable comporterait 7 chiffres, où les 4 premiers sont réservés à WidgetID et les trois derniers caractères sont réservé pour CountryID.

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

Clé d'agrégation
ID du widget	Identifiant du pays
3276	061

Exemple:Si un espace clé est disponible pour une dimension pour plusieurs chiffres, mais que la valeur en a moins, ajoutez des zéros au début. Par exemple : Si l'identifiant du pays comporte trois chiffres, l'identifiant du pays pour l'Algérie est 003

La clé d'agrégation peut également être générée à l'aide d'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 a plus de 128 bits, vous pouvez la tronquer pour vous assurer dépassent la valeur maximale autorisée de 2^128−1 pour le bucket.

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

L'exemple suivant explique comment générer une clé de bucket à partir d'une clé 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 des insights sous la forme de valeurs récapitulatives dans les rapports de synthèse.

Maintenant, revenons à l'exemple de question posé précédemment : « Combien d'utilisateurs qui ont vu mon widget viennent de France ?" La réponse à cette question sera quelque chose comme « Environ 4 881 utilisateurs ayant vu mon identifiant de widget 3276 sont 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.

Clé d'agrégation		Valeur agrégable
ID du widget	Identifiant du pays	Nombre de vues
3276	061	1

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

Budget de contribution

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

Lorsque vous additionnez toutes les valeurs agrégables de toutes les clés d'agrégation, la somme doit être inférieur au budget de contribution. Le budget est défini par workflow origin, par jour, et est pour l'API Protected Audience et les Worklets Shared Storage. Un rouleau d'environ 24 heures est utilisée pour la journée. Si un nouveau rapport agrégable entraînerait un dépassement du budget, le rapport n'est pas créé.

Le budget de contribution est représenté par le paramètre L₁. définie sur 2¹⁶ (65 536) toutes les 10 minutes par jour avec un arrêt arrière de 2²⁰

(1 048 576). Consultez le expliquer pour en savoir plus sur ces paramètres.

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

Pour en savoir plus sur les budgets de contribution, consultez les . Consultez également Contributions Budget pour en savoir plus.

Rapports agrégables

Une fois que l'utilisateur a appelé l'API Private Aggregation, le navigateur génère rapports agrégables à traiter ultérieurement par le service d'agrégation à temps pour générer un récapitulatif rapports. Une agrégable est au format JSON et contient une liste chiffrée des contributions, chacune étant une paire {aggregation key, aggregatable value}. Les rapports agrégables sont envoyés dans un délai aléatoire d'une heure maximum.

Les contributions sont chiffrées et illisibles 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 de chiffrement pour le navigateur et la clé de déchiffrement pour l'agrégation Les services sont émis par le coordinateur, qui agit en tant que service de gestion des clés. Le coordinateur conserve une liste des hachages binaires de l'image du service à vérifier. que l'appelant est autorisé à recevoir la clé de déchiffrement.

Exemple de rapport agrégable avec débogage :

  "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\"}"

Les rapports agrégables peuvent être inspectés à partir de la Page chrome://private-aggregation-internals:

capture d'écran de la page "Internals" de l'API Private Aggregation

À des fins de test, "Envoyer les rapports sélectionnés" permet d'envoyer communiquer immédiatement au serveur.

Collecter et regrouper des rapports agrégables par lot

Le navigateur envoie les rapports agrégables à l'origine du Worklet contenant l'appel à l'API Private Aggregation, à l'aide de la méthode chemin:

Pour le stockage partagé: /.well-known/private-aggregation/report-shared-storage
Pour Protected Audience: /.well-known/private-aggregation/report-protected-audience

À ces points de terminaison, vous devrez faire fonctionner un serveur, qui agira en tant que collecteur, qui reçoit les rapports agrégables envoyés par les clients.

Le serveur doit ensuite traiter les rapports par lot et envoyer le lot au processus de service. Créer des lots en fonction des informations disponibles dans le fichier charge utile du rapport agrégable, telle que le champ shared_info. Dans l’idéal, les lots doivent contenir au moins 100 rapports par lot.

Vous pouvez décider d'effectuer des traitements par lot sur une base quotidienne ou hebdomadaire. Cette stratégie est flexible, Vous pouvez modifier votre stratégie de traitement par lot pour des événements spécifiques Volume plus important, par exemple, les jours de l'année où davantage d'impressions sont attendues. Les lots doivent inclure des rapports issus de la même version d'API, de la même origine et planifier l'heure du rapport.

Service d'agrégation

Le service s'exécute dans un TEE, déchiffre les rapports agrégables et ajoute
du bruit pour créer
le rapport récapitulatif final.

Le service d'agrégation reçoit des rapports agrégables chiffrés de la part du collecteur et génère des résumés rapports.

Pour déchiffrer la charge utile du rapport, le service d'agrégation récupère une clé de déchiffrement du coordinateur. Le service s'exécute dans un environnement d'exécution sécurisé (TEE), qui fournit un niveau d'assurance de l'intégrité et de la confidentialité des données, et l'intégrité du code. Bien que vous soyez propriétaire et gestionnaire du service, une visibilité sur les données en cours de traitement dans le TEE.

Rapports de synthèse

Rapports récapitulatifs vous permettent de voir les données que vous avez collectées en ajoutant du bruit. Vous pouvez demander des rapports de synthèse pour un ensemble de clés donné.

Un rapport récapitulatif contient un ensemble de paires clé-valeur de type dictionnaire JSON. Chaque contient:

bucket: clé d'agrégation sous forme de chaîne numérique binaire. Si le la clé d'agrégation utilisée est "123" et le bucket est "1111011".
value: valeur récapitulative pour un objectif de mesure donné, additionnée des tous les rapports agrégables disponibles en ajoutant du bruit.

Exemple :

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

Bruit et mise à l'échelle

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 du bruit sont sélectionnée de manière aléatoire à partir d'une probabilité de Laplace distribution. Pendant que vous pas un contrôle direct sur la façon dont le bruit est ajouté, vous pouvez influencer l'impact de bruit sur ses données de mesure.

La répartition du bruit est la même, quelle que soit la somme de tous les éléments agrégables valeurs. Par conséquent, plus les valeurs agrégables sont élevées, moins le bruit est affecté est susceptible d’avoir.

Par exemple, supposons que la distribution du bruit a un écart type de 100 et est centrée à zéro. Si la valeur du rapport agrégable collecté "valeur agrégable") n'est que 200, l'écart type du bruit est alors de 50% de la valeur agrégée. En revanche, si la valeur agrégable est de 20 000, l'écart type du bruit ne serait que 0,5% de la valeur agrégée. Ainsi, une valeur agrégable de 20 000 aurait un rapport signal/bruit beaucoup plus élevé.

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

Le bruit est constant, quelle que soit la valeur agrégée.

L'augmentation des valeurs en choisissant un facteur de scaling plus élevé réduit le trafic relatif bruit. Toutefois, cela entraîne également la somme de toutes les contributions de tous les buckets. pour atteindre plus rapidement la limite du budget de contribution. Réduire les valeurs de choisir une constante de facteur de mise à l'échelle plus faible augmente le bruit relatif, mais réduit le risque d'atteindre la limite du budget.

Adaptez la valeur agrégable au budget de contribution.

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.

Consultez le budget de contribution documentation pour en savoir plus.

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: consultez les l'explication, de poser des questions et de participer discussion. * Assistance aux développeurs: posez des questions et participez à des discussions sur le Assistance pour les développeurs de la Privacy Sandbox . * Rejoindre l'API Shared Storage groupe et l'API Protected Audience groupe pour connaître les dernières annonces concernant Private Aggregation.