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 agrégées à partir de worklets ayant accès aux données intersites. Les concepts présentés ici sont importants pour les développeurs qui créent des fonctions de création de rapports dans l'API Shared Storage et 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 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 un une collecte prédéterminée de points de données. Par exemple, vous pouvez collecter un bucket de données de localisation dans lequel 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é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
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 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 groupés sont ensuite traités par le service d'agrégation, et un rapport récapitulatif est généré.

Les données passent du client au collecteur, puis au service d'agrégation pour 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 des clients et les regroupe pour les envoyer 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 workflow décrit dans cette section est semblable à celui de l'API Attribution Reporting. 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é" pour faire court) représente le bucket dans lequel les valeurs agrégables seront accumulé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 créer un rapport 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. 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 comporte 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 de France (ID de 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'ID de pays accepte trois chiffres, celui de 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 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() activé 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 des insights sous la forme de valeurs récapitulatives dans les rapports de synthèse.

Revenez maintenant à l'exemple de question posée précédemment : "Combien d'utilisateurs qui ont vu mon widget sont français ?". La réponse à cette question se présente comme suit : "Environ 4 881 utilisateurs qui ont vu mon widget ID 3276 sont situés en France." La valeur agrégable est de 1 pour chaque utilisateur, et "4 881 utilisateurs" est la valeur agrégée, qui correspond à 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, le nombre de contributions pouvant être collectées auprès d'un individu 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 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, il 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 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 sur les budgets de contribution, consultez la présentation. Consultez également Contributions Budget pour en savoir plus.

Limite de contribution par rapport

La limite de contribution peut varier selon l'appelant. 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 peut être intégré à la taille de la charge utile.

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

Contributions avec marge intérieure

Les contributions sont également modifiées avec une fonctionnalité de marge intérieure. Le fait de remplir la charge utile protège les informations relatives au nombre réel de contributions le rapport agrégable. Le remplissage augmente la charge utile avec des contributions null. (c'est-à-dire avec la valeur 0) pour obtenir une longueur fixe.

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 avec un délai aléatoire pouvant aller jusqu'à une heure.

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 clé de chiffrement du navigateur et la clé de déchiffrement du service d'agrégation sont émises par le coordinateur, qui sert de 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 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 inspecter les rapports agrégables depuis la page chrome://private-aggregation-internals :

Capture d'écran de la page des composants internes de l'API Private Aggregation

À des fins de test, vous pouvez utiliser le bouton "Envoyer les rapports sélectionnés" pour envoyer immédiatement le rapport au serveur.

Collecter et traiter par lot des rapports agrégables

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 Shared Storage : /.well-known/private-aggregation/report-shared-storage
Pour Protected Audience: /.well-known/private-aggregation/report-protected-audience

Sur ces points de terminaison, vous devrez exploiter un serveur (qui joue le rôle de collecteur) qui reçoit les rapports cumulables envoyés par les clients.

Le serveur doit ensuite regrouper les rapports et les envoyer 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 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 (jours de l'année où davantage d'impressions sont attendues, par exemple) 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 du collecteur et génère des rapports récapitulatifs.

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

Les rapports récapitulatifs vous permettent de consulter les données que vous avez collectées avec du bruit 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 numérique binaire. Si la clé d'agrégation utilisée est "123", le bucket est "1111011".
value : valeur récapitulative d'un objectif de mesure donné, résumée à partir de tous les rapports agrégables disponibles avec du bruit 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 extraites de manière aléatoire à partir d'une distribution de probabilité de Laplace. 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 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 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 de rapport agrégable collectée (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ésentera 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, multiplier votre valeur agrégable par un facteur de scaling peut contribuer à réduire le bruit. Le facteur de mise à l'échelle représente l'échelle que vous souhaitez appliquer à une valeur agrégable donnée.

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 bruit relatif. 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. Si vous diminuez les valeurs en choisissant une constante de facteur de scaling plus faible, le bruit relatif augmente, mais le risque d'atteindre la limite de budget est réduit.

Adaptez la valeur agrégable au budget de contribution.

Pour calculer un facteur de mise à l'échelle 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 à nous faire, nous serions ravis de les recevoir.

GitHub : lisez la présentation, posez des questions et participez aux discussions. * 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.