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 leviewCount
de1
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.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/data-flows-the-client-t-ebd6f5c55d92f.png?authuser=0000&hl=fr)
- 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 |
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 L1. définie sur 216 (65 536) toutes les 10 minutes par jour avec un arrêt arrière de 220
(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](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/screenshot-the-private-a-132a69aaab759.png?authuser=0000&hl=fr)
À 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.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/the-service-runs-a-tee-746adddcc2c6.png?authuser=0000&hl=fr)
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.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/noise-is-constant-regardl-6c311a31c1292.png?authuser=0000&hl=fr)
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.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/scale-aggregatable-value-b7347ae673f12.png?authuser=0000&hl=fr)
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.