Questa guida descrive come i report di misurazione criptati vengono inviati ai fornitori di tecnologia pubblicitaria. I browser e i client Chrome inviano questi report a endpoint di reporting designati, dove la piattaforma di tecnologia pubblicitaria riceve e archivia i report aggregabili. Questi endpoint, che si trovano agli URL .well-known all'interno dell'origine report del fornitore, sono ospitati dalla piattaforma e consentono ai fornitori di tecnologia pubblicitaria che utilizzano l'API Attribution Reporting o l'API Private Aggregation di accedervi.
I passaggi riportati di seguito descrivono in dettaglio la procedura del servizio di aggregazione per la ricezione e l'archiviazione dei report aggregabili:
- Quando viene attivato, il browser invia report aggregabili contenenti dettagli sia sui dati cross-site sia sulle conversioni.
- Il browser invia i report criptati a un URL
.well-knownall'interno del dominio dei report di tecnologia pubblicitaria. - Il sistema inoltra i batch di report al servizio di aggregazione per l'elaborazione.
- Il servizio di aggregazione riassume statisticamente i report.
- Il servizio di aggregazione aggiunge rumore ai dati riepilogati per migliorare la privacy degli utenti.
- Il sistema rende disponibili i report per la società di ad tech a fini di analisi e misurazione.
La tabella seguente descrive gli endpoint di debug e in produzione per l'API Private Aggregation e l'API Attribution Reporting:
| API | Endpoint | Descrizione |
|---|---|---|
| API Private Aggregation |
|
|
| API Attribution Reporting |
|
|
Le origini report ricevono i report JSON tramite chiamate POST. Il sistema trasforma quindi questi report in formato Avro e li inserisce nello spazio di archiviazione sul cloud. Dopo l'elaborazione batch, il sistema invia i report Avro al servizio di aggregazione per il riepilogo.
Le piattaforme di tecnologia pubblicitaria attivano una richiesta di job di aggregazione al servizio di aggregazione quando un batch di report Avro è considerato pronto per l'elaborazione. Questo servizio, ospitato nell'ambiente cloud della piattaforma di ad tech, recupera i report Avro richiesti dalla stessa posizione di archiviazione. Per motivi di sicurezza, il servizio di aggregazione deve essere configurato per utilizzare un'immagine container approvata. Per le immagini container disponibili, consulta il repository GitHub di Privacy Sandbox/Aggregation Service.
Di seguito sono riportati esempi rappresentativi dei report restituiti da ogni API:
- Esempio di report dell'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\"}"
}
- Esempio di report dell'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"
}
Convertire i report JSON in Avro
I report aggregabili devono essere nel formato di serializzazione dei dati Apache Avro per i batch. Per creare un report Avro, devi utilizzare uno schema AVSC. Il file dello schema AVSC definisce la struttura del record Avro e il tipo di dati. Per un esempio di schema AVSC, consulta il file example.avsc in questo repository GitHub avrodoc/schemata.
Puoi trovare un codice JavaScript di esempio nella sezione Raccogliere, trasformare e raggruppare i report della pagina Raccogliere e raggruppare i report aggregabili nel repository GitHub privacysandbox/aggregation-service.
Hai la possibilità di archiviare tutti i report in un unico file AVRO o di distribuirli in più file. Sebbene i file AVRO non abbiano limiti di dimensioni, in genere le prestazioni ottimali vengono raggiunte quando il numero di file varia dal numero di CPU nell'istanza cloud fino a 1000.
Il seguente esempio di codice mostra uno schema Avro per i report aggregabili. I campi del report includono payload, key_id e shared_info.
{
"type": "record",
"name": "AggregatableReport",
"fields": [
{
"name": "payload",
"type": "bytes"
},
{
"name": "key_id",
"type": "string"
},
{
"name": "shared_info",
"type": "string"
}
]
}
| Parametro | Tipo | Descrizione |
|---|---|---|
payload |
Byte |
payload deve essere decodificato in base64 e convertito in un array di byte per i report dal vivo o di produzione.
|
debug_cleartext_payload |
Byte |
Il payload deve essere decodificato in base64 e convertito in un array di byte
dal debug_cleartext_payload per i report di debug.
|
key_id |
Stringa | Questa è la stringa key_id trovata nel report. key_id è un identificatore univoco universale di 128 bit. |
shared_info |
Stringa | Si tratta della stringa non alterata e non manomessa trovata nel campo shared_info del report. |
Di seguito è riportato un esempio di report 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\"}"
}
Specifiche del file del dominio
La generazione di report di riepilogo con il servizio di aggregazione richiede i report aggregabili (report JSON convertiti in Avro) e il file del dominio associato. Il sistema estrae le chiavi predefinite dai report aggregabili e le include nei report di riepilogo all'interno dei domini di output. Puoi trovare i dettagli su queste chiavi di aggregazione fondamentali nella sezione Informazioni sulle chiavi di aggregazione per i report sull'attribuzione e nella sezione Chiave di aggregazione di Concetti fondamentali dell'API Private Aggregation. Il dominio di output include anche il campo bucket che rappresenta il valore della chiave del bucket.
Il file del dominio deve essere in formato Avro e utilizzare lo schema seguente:
{
"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."
}
]
}
Chiave del bucket
La chiave del bucket all'interno del dominio di output deve essere rappresentata come una stringa di byte esadecimale.
Ad esempio:
Se la chiave del bucket è il valore decimale 1369:
Converti 1369 nel suo equivalente esadecimale: 559
Converti la stringa esadecimale "559" in una stringa di byte.
Questa rappresentazione di stringa di byte della chiave del bucket deve essere inclusa nello schema Avro del dominio di output.
Considerazioni importanti:
Tipo di dati: la chiave del bucket all'interno dello schema Avro deve essere definita come tipo di byte per supportare la rappresentazione della stringa di byte esadecimale.
Conversione: la conversione da decimale a esadecimale e poi a una stringa di byte può essere implementata utilizzando Python o Java.
Questo approccio garantisce che la chiave del bucket sia formattata correttamente e compatibile con il tipo di dati previsto nello schema Avro per il dominio di output.
Report batch
Per informazioni dettagliate sui budget di privacy e sulle strategie di raggruppamento, consulta la documentazione relativa alle strategie di raggruppamento. Tieni presente che i report aggregabili hanno un limite MAX_REPORT_AGE (attualmente 90 giorni) tra la data scheduled_report_time e la data di esecuzione del batch.
Report di riepilogo
Dopo l'aggregazione, il servizio di aggregazione crea il report di riepilogo in formato Avro utilizzando lo schema results.avsc.
Al termine del job, il report di riepilogo viene archiviato in output_data_blob_prefix all'interno del bucket output_data_bucket_name come indicato nella richiesta createJob.
Per i batch del servizio di aggregazione in cui è attivato debug_run, vengono creati due report: il report di riepilogo e il report di riepilogo del debug. Il report di riepilogo del debug si trova nella cartella output_data_blob_prefix/debug. Il report di riepilogo del debug utilizza lo schema debug_results.avsc.
Sia il report di riepilogo sia il report di debug sono denominati [output_data_blob_prefix]-1-of-1.avro. Se output_data_blob_prefix è summary/summary.avro, il report si trova nella cartella di riepilogo con il nome summary-1-of-1.avro.
Esempio di results.avsc
Di seguito è riportato uno schema Avro di esempio per 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"
}
]
}
Lo schema Avro di esempio definisce un record denominato AggregatedFact.
Esempio di debug_results.avsc
Di seguito è riportato un esempio di schema Avro per 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"]
}
}
]
}
Una volta convertito, il report di riepilogo sarà simile all'esempio results.json. Quando debug_run è attivato, il report di riepilogo del debug restituito è simile all'esempio debug_results.json.
Formato dei report Avro
I report Avro ricevuti dal servizio di aggregazione in genere rispettano un formato coerente. Il formato del report Avro include i seguenti campi:
bucket: un identificatore univoco per l'aggregazione dei dati (ad es. "\u0005Y").
metric: il valore aggregato per il bucket corrispondente. Spesso questo valore include rumore aggiunto per migliorare la privacy.
Ad esempio:
{
"bucket": "\u0005Y",
"metric": 26308
}
Esempio di debug_results.json
I report di debug Avro del servizio di aggregazione saranno simili al seguente esempio debug_results.json. Questi report includono le chiavi dei bucket, il valore unnoised_metric (il riepilogo delle chiavi dei bucket prima dell'applicazione del rumore) e il rumore aggiunto a questa metrica.
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
Le annotazioni contengono anche i seguenti valori:
in_reports: la chiave del bucket disponibile all'interno dei report aggregabiliin_domain: la chiave del bucket disponibile all'interno del file Avrooutput_domain