Ce guide explique comment les rapports de mesure chiffrés sont envoyés aux fournisseurs de technologies publicitaires. Les navigateurs et clients Chrome envoient ces rapports à des points de terminaison de reporting désignés, où la plate-forme de technologie publicitaire reçoit et stocke les rapports agrégables. Ces points de terminaison, situés sur les URL .well-known dans l'origine des rapports du fournisseur, sont hébergés par la plate-forme. Ils permettent aux fournisseurs de technologie publicitaire qui utilisent l'API Attribution Reporting ou l'API Private Aggregation d'y accéder.
Les étapes suivantes décrivent le processus de réception et de stockage des rapports agrégables par le service d'agrégation:
- Lorsqu'il est déclenché, le navigateur envoie des rapports agrégables contenant des informations sur les données intersites et les données de conversion.
- Le navigateur envoie les rapports chiffrés à une URL
.well-knowndans le domaine de création de rapports de la technologie publicitaire. - Le système transfère les lots de rapports au service d'agrégation pour traitement.
- Le service d'agrégation résume les rapports de manière statistique.
- Le service d'agrégation ajoute du bruit aux données résumées pour renforcer la confidentialité des utilisateurs.
- Le système met les rapports à la disposition de l'entreprise de technologie publicitaire à des fins d'analyse et de mesure.
Le tableau suivant décrit les points de terminaison de débogage et en direct pour l'API Private Aggregation et l'API Attribution Reporting:
| API | Point de terminaison | Description |
|---|---|---|
| API Private Aggregation |
|
|
| API Attribution Reporting |
|
|
Les origines de création de rapports reçoivent des rapports JSON via des appels POST. Le système transforme ensuite ces rapports au format Avro et les stocke dans Cloud Storage. Après le traitement par lot, le système envoie les rapports Avro au service d'agrégation pour les résumer.
Les plates-formes de technologie publicitaire déclenchent une requête de tâche d'agrégation auprès du service d'agrégation lorsqu'un lot de rapports Avro est considéré comme prêt à être traité. Ce service, hébergé dans l'environnement cloud de la plate-forme de technologie publicitaire, récupère les rapports Avro requis à partir du même emplacement de stockage. Pour des raisons de sécurité, le service d'agrégation doit être configuré pour utiliser une image de conteneur approuvée. Pour connaître les images de conteneur disponibles, consultez le dépôt GitHub de la privacy sandbox/aggregation-service.
Vous trouverez ci-dessous des exemples représentatifs des rapports renvoyés par chaque API:
- Exemple de rapport de l'API Private Aggregation:
{
"aggregation_coordinator_origin": "https://publickeyservice.msmt.aws.privacysandboxservices.com",
"aggregation_service_payloads": [ {
"key_id": "1a2baa3f-5d48-46cf-91f0-772633c12640",
"payload": "8Cjr1s3FVkCYkjzBvyzJn14yardVjd5N4vLCA69LQAPbIkJ0B58hAqUGBCNXpvTjW9ZpIoZbCSiUOsUDuoA/S+tqVolLMkame6sWC07cfUmZcVsbU+La3pzTMtCgdtNc8MIWgD3C63CMw7rWroRlechewVUajvAYVK/0HJq0YyGrTiFZZm36zi0jjyHLAXKV8p1Lvy1d0o/wnBxC5oVo5BV6LPkxqQEcoYS2GyixUuht6wD0RzuH+BxxuH6vY/ynp2xDrnwftjvqwDUAxUWLFTunthM6BXZVxlrvOBim1h2dvPqWSyKZ5gafo+MgW9EM4SraavNM3XzZSCjdtAfSMJMrynSu2j0opyAq+9e1jq1xeYN00yZrJ0Y/GTI45IGjgCnVmvmuoI9ucW2SnXP31CQBwHqk4gtUgMsYGFSUYfhtnAQ/8TSbaXyS2LX+cQW87LqkvIraWw6o37O24VFBreFoFFXpu3IUeCZfji+Sr4/ykfZuHeMzQbBavyNnHKzPZlbLSXMiucx4/vWzYyOzHeIlbtupXVvbi40V2PieDShaSbjI266kGgFkeCk6z51AaAGebDPtRT1lhBpcoQ6JdF0Yp5VWSnyFARKFtCZ1aEBrlUlrEHLUQY/pFtmDxJQiicRz1YPjR8jRr3C7hlRhWwov0dMocqnMz5209hHGVZWSsaGc9kWjtxREW2ULXfoIwOGbX+WZsyFW2RhXksQPJ5fhyNc4ROkAzUthLb68gC5e0yZHvmLIAU4hcWe0UanJv+jRljn8PAPaJHKFUxQNJyBA7mTbn5mkpycxGrX6T3ZYdPHqvckqt9llJZWjr8NneizzZFRuJk423BDs38fXkvcTAsAckd2Zu0u2KC45WR93sN2/CWrqB7/QU9BsgNdonl/ehAWhU1LbcRRvBTcR9+0wL7vRL7cv5LG3+gRYRKsWI6U2nDSWp0cNpo9+HU0JNiifa5X0cguihqU2bSk6ABozgRtCZ7m+7eqWXMLSzBdmc1CPUoQppo6Wmf6ujdNqI6v2S6pDH781lph8Z2v7ZpxGdhVVPEL51cVn"
} ],
"debug_key": "1234",
"shared_info": "{\"api\":\"shared-storage\",\"report_id\":\"05e3b948-cb8d-4404-be29-bfeac7ad9710\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1707784729\",\"version\":\"0.1\"}"
}
- Exemple de rapport de l'API Attribution Reporting
{
"aggregation_coordinator_origin": "https://publickeyservice.msmt.aws.privacysandboxservices.com",
"aggregation_service_payloads": [ {
"key_id": "2dee0f3f-2aee-4a4a-8238-9154ed3d6f72",
"payload": "pHvTHhcxvNKaCmnLpvYQsXlJpiNRuFO5Zj1QqUlqgWPOfuoHLfiXiFjmpvY8a53/OYnS4bKwHwJReFcofldsu8E9BzTTJ3CEk+B7vbEjnDPaljhpIBMTuQXy3QHGK4slWR/yNZVm2uXRWR/DVVzXziBoTDjN7qaPstRoLKUUMdfY2u8oq4tnLY00Y+NDZttZ4wJvC7hPmvY3lqHjdl14JPD2ytZZ4NViYzno3WKdH/oZc0jhGK4zI38lAM0qpahF/B9yb4zOu7IRIjQpNx73P8naDyddxLldoVlW/qHpO04FguWymscvI/8i6NwUR6Kj8seRlWS0iIUhETt/ai3lilKUHUb+uz0YG2kxjoXq7Ldk+MP56nNl67ZRNi2YZ7bOGI/okYWoT/wt2uWPe/5xAEMmadxl0hQQrG7YXHRSD8rDnaVPXo+AKIxdg727yJeB1ZENZvovl/kIevdRAmdBe2h1U3J6Uz6psly/46fvjgkj5QD+kO2uaYirzvmwS19luJsN/Qvh/R3ZO4qlJIQI0nDJPWwUJ4ODpyVmj4a0xQp3t2ESEnf4EmY7+khn3xpF5+MwEWKES2ZeDf7SHalR99pvZA8G3Fr8M0PWFmT00cmKCBwpQgZyd3Eay70UlqdkbFEedxiCVWKNNOUz41m5KG/7K3aR+dYx57l57Wct4gOFQg3jiUEBJWrFIVCXf12BT5iz5rBQh1N1CUt2oCOhYL/sPuBl6OV5GWHSIj8FUdpoDolqKXWINXfE88MUijE2ghNRpJN25BXIErUQtO9wFQv7zotC6d2BIaF0x8AkKg/7yzBQRySX/FZP3H3lMkpOz9rQMV8DjZ2lz7nV4k6CFo8qhT6cpYJD7GpYl81xJbglNqcJt5Pe5YUHrdBMyAFsTh3yoJvYnhQib/0xVN/a93lbYccxsd0yi375n4Xz0i1HUoe2ps+WlU8XysAUA1agG936eshaY1anTtbJbrcoaH+BNSacKiq4saprgUGl4eDjaR/uBhvUnO52WkmAGon8De3EFMZ/kwpPBNSXi7/MIAMjotsSKBc19bfg"
} ],
"shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://privacy-sandbox-demos-shop.dev\",\"report_id\":\"5b052748-f5fb-4f14-b291-de03484ed59e\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1707786751\",\"source_registration_time\":\"0\",\"version\":\"0.1\"}",
"source_debug_key": "123456789",
"trigger_debug_key": "123456789"
}
Convertir des rapports JSON en Avro
Les rapports agrégables doivent être au format de sérialisation de données Apache Avro à des fins de traitement par lot. Pour créer un rapport Avro, vous devez utiliser un schéma AVSC. Le fichier de schéma AVSC définit la structure et le type de données des enregistrements Avro. Pour obtenir un exemple de schéma AVSC, consultez le fichier example.avsc dans ce dépôt GitHub avrodoc/schemata.
Vous trouverez un exemple de code JavaScript dans la section Collecter, transformer et regrouper des rapports de la page Collecter et regrouper des rapports agrégables, disponible dans le dépôt GitHub privacysandbox/aggregation-service.
Vous pouvez stocker tous les rapports dans un seul fichier AVRO ou les répartir sur plusieurs fichiers. Bien que les fichiers AVRO n'aient pas de limite de taille, des performances optimales sont généralement obtenues lorsque le nombre de fichiers varie entre le nombre de processeurs de votre instance cloud et 1 000.
L'exemple de code suivant présente un schéma Avro pour les rapports agrégables. Les champs de rapport incluent payload, key_id et shared_info.
{
"type": "record",
"name": "AggregatableReport",
"fields": [
{
"name": "payload",
"type": "bytes"
},
{
"name": "key_id",
"type": "string"
},
{
"name": "shared_info",
"type": "string"
}
]
}
| Paramètre | Type | Description |
|---|---|---|
payload |
Octets |
Le payload doit être décodé en base64 et converti en tableau d'octets pour les rapports en direct ou de production.
|
debug_cleartext_payload |
Octets |
La charge utile doit être décodée en base64 et convertie en tableau d'octets à partir de debug_cleartext_payload pour les rapports de débogage.
|
key_id |
Chaîne | Il s'agit de la chaîne key_id trouvée dans le rapport. key_id est un identifiant universel unique de 128 bits. |
shared_info |
Chaîne | Il s'agit de la chaîne non modifiée et non falsifiée trouvée dans le champ shared_info du rapport. |
Voici un exemple de rapport JSON:
{
"aggregation_coordinator_identifier": "aws-cloud",
"aggregation_service_payloads": [{
"debug_cleartext_payload": "omRkYXhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAFWW1vcGVyYX",
"key_id": "3c6e2850-edf6-4886-eb70-eb3f2a7a7596",
"payload": "oapYz92Mb1yam9YQ2AnK8dduTt2RwFUSApGcKqXnG1q+aGXfJ5DGpSxMj0NxdZgp7Cq"
}],
"debug_key": "1234",
"shared_info":
"{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"b029b922-93e9-4d66-a8c6-8cdeec762aed\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1719251997\",\"version\":\"0.1\"}"
}
Spécifications du fichier de domaine
Pour générer des rapports récapitulatifs avec le service d'agrégation, vous devez disposer de vos rapports agrégables (rapports JSON convertis en Avro) et du fichier de domaine associé. Le système extrait les clés prédéclarées de vos rapports agrégables et les inclut dans les rapports récapitulatifs des domaines de sortie. Pour en savoir plus sur ces clés d'agrégation essentielles, consultez Comprendre les clés d'agrégation pour les rapports sur l'attribution et la section Clé d'agrégation de Principes de base de l'API Private Aggregation. Le domaine de sortie inclut également le champ bucket, qui représente la valeur de votre clé de bucket.
Le fichier de domaine doit être au format Avro et utiliser le schéma suivant:
{
"type": "record",
"name": "AggregationBucket",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "A single bucket that appears in the aggregation service output. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring."
}
]
}
Clé de bucket
La clé de bucket dans le domaine de sortie doit être représentée sous forme de chaîne d'octets hexadécimaux.
Exemple :
Si la clé de bucket est la valeur décimale 1369:
Convertir 1 369 en son équivalent hexadécimal: 559
Convertissez la chaîne hexadécimale "559" en une chaîne d'octets.
Cette représentation de chaîne d'octets de la clé de bucket doit ensuite être incluse dans le schéma Avro du domaine de sortie.
Remarques importantes :
Type de données: la clé de bucket dans le schéma Avro doit être définie comme un type d'octet pour prendre en charge la représentation de la chaîne d'octets hexadécimaux.
Conversion: la conversion du format décimal au format hexadécimal, puis en chaîne d'octets, peut être implémentée à l'aide de Python ou de Java.
Cette approche garantit que la clé de bucket est correctement formatée et compatible avec le type de données attendu dans le schéma Avro pour le domaine de sortie.
Rapports par lot
Pour en savoir plus sur les budgets de confidentialité et les stratégies de traitement par lot, consultez la documentation sur les stratégies de traitement par lot. Notez que les rapports agrégables sont soumis à une limite MAX_REPORT_AGE (actuellement 90 jours) entre leur scheduled_report_time et la date d'exécution du lot.
Rapports récapitulatifs
Après le traitement par lot, le service d'agrégation crée le rapport récapitulatif au format Avro à l'aide du schéma results.avsc.
Une fois la tâche terminée, le rapport récapitulatif est stocké dans le output_data_blob_prefix du bucket output_data_bucket_name, comme indiqué dans la requête createJob.
Pour les lots du service d'agrégation où debug_run est activé, il crée deux rapports : le rapport récapitulatif et le rapport récapitulatif de débogage. Le rapport récapitulatif de débogage se trouve dans le dossier output_data_blob_prefix/debug. Le rapport récapitulatif de débogage utilise le schéma debug_results.avsc.
Le rapport de synthèse et le rapport de débogage sont nommés [output_data_blob_prefix]-1-of-1.avro. Si votre output_data_blob_prefix est summary/summary.avro, le rapport se trouve dans le dossier de résumé nommé summary-1-of-1.avro.
Exemple results.avsc
Voici un exemple de schéma Avro pour results.avsc:
{
"type": "record",
"name": "AggregatedFact",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "Histogram bucket used in aggregation. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring. Leading 0-bits are left out."
},
{
"name": "metric",
"type": "long",
"doc": "The metric associated with the bucket"
}
]
}
L'exemple de schéma Avro définit un enregistrement nommé AggregatedFact.
Exemple debug_results.avsc
Voici un exemple de schéma Avro pour debug_results.avsc:
{
"type": "record",
"name": "DebugAggregatedFact", Output domains include summary reports that contain pre-declared keys extracted from your aggregatable reports.
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "This represents the histogram bucket used in aggregation. It's a 128-bit integer, encoded as a 16-byte big-endian bytestring, with leading zero bytes omitted.."
},
{
"name": "unnoised_metric",
"type": "long",
"doc": "The raw metric for the bucket."
},
{
"name": "noise",
"type": "long",
"doc": "The noise applied to the metric in the regular result."
}
{
"name":"annotations",
"type": {
"type": "array",
"items": {
"type":"enum",
"name":"bucket_tags",
"symbols":["in_domain","in_reports"]
}
}
]
}
Une fois converti, votre rapport récapitulatif ressemble à l'exemple results.json. Lorsque debug_run est activé, le rapport récapitulatif de débogage renvoyé est semblable à l'exemple debug_results.json.
Format des rapports Avro
Les rapports Avro reçus du service d'agrégation respectent généralement un format cohérent. Le format de rapport Avro inclut les champs suivants:
bucket: identifiant unique de l'agrégation des données (par exemple, "\u0005Y").
métrique: valeur cumulée pour le bucket correspondant. Cette valeur inclut souvent du bruit ajouté pour préserver la confidentialité.
Exemple :
{
"bucket": "\u0005Y",
"metric": 26308
}
Exemple debug_results.json
Les rapports Avro de débogage du service d'agrégation ressemblent à l'exemple debug_results.json suivant. Ces rapports incluent les clés de bucket, le unnoised_metric (résumé des clés de bucket avant l'application du bruit) et le bruit ajouté à cette métrique.
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
Les annotations contiennent également les valeurs suivantes:
in_reports: clé de bucket disponible dans les rapports agrégablesin_domain: clé de bucket disponible dans le fichier Avrooutput_domain