Quando le ad tech attivano le API di misurazione (API Attribution Reporting o API Private Aggregation), i report criptati vengono inviati dal lato client/browser di Chrome all'endpoint di reporting dell'ad tech, che è un URL .well-known con l'origine dei report dell'ad tech. L'endpoint di generazione di report è ospitato dalla tecnologia pubblicitaria per raccogliere i report criptati.
Di seguito sono riportati gli endpoint per ogni API:
Private Aggregation
- Debug
[reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage - In diretta
[reporting-origin]/.well-known/private-aggregation/report-shared-storageo/.well-known/private-aggregation/report-protected-audience
- Debug
Report sull'attribuzione
- Debug
[reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution - In diretta
[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution
- Debug
I tecnici pubblicitari riceveranno i report in formato JSON tramite una chiamata POST. I tecnici pubblicitari raccoglieranno questi report JSON e li convertiranno in un secondo momento nel formato AVRO utilizzato nel servizio di aggregazione. Una volta convertiti, i report AVRO vengono archiviati nello spazio di archiviazione sul cloud della tecnologia pubblicitaria per essere raggruppati in un secondo momento.
Una volta che la tecnologia pubblicitaria è pronta per l'aggregazione, attiverà una richiesta di job di aggregazione tramite il servizio di aggregazione in cui i report vengono recuperati dallo spazio di archiviazione sul cloud della tecnologia pubblicitaria. Il servizio di aggregazione è ospitato nello spazio di archiviazione sul cloud della tecnologia pubblicitaria e deve avere un'immagine inserita nella lista consentita.
Le segnalazioni ricevute hanno il seguente aspetto:
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\"}"
}
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 report AVRO
Quando utilizzi il batching, i report aggregabili devono essere in formato AVRO. Per creare un report AVRO, devi disporre dello schema AVRO (AVSC) del report.
Un codice JavaScript di esempio è disponibile nel repository GitHub di Aggregation Service.
Puoi avere un file AVRO per tutti i report o suddividere i report in più file AVRO. Non è previsto alcun limite per le dimensioni dei file AVRO. Per motivi di prestazioni, è consigliabile mantenere il numero di file AVRO compreso tra il numero di CPU disponibili per l'istanza Cloud e 1000.
Di seguito è riportato lo schema AVRO per i report aggregabili. I diversi campi per i report sono 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 |
Il payload dovrà essere decodificato in base64 e convertito in un array di byte
da payload per i report dal vivo/di produzione.
|
debug_cleartext_payload |
Byte |
Il payload dovrà essere decodificato in base64 e convertito in un array di byte
da debug_cleartext_payload per i report di debug.
|
key_id |
Stringa | Si tratta della stringa key_id trovata nel report. Il valore key_id sarà un identificatore univoco universale a 128 bit simile. |
shared_info |
Stringa | Si tratta della stringa non alterata trovata nel campo shared_info del report. |
Ecco 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\"}"
}
AVRO dominio di output
Per generare report di riepilogo usando il servizio di aggregazione, la tecnologia pubblicitaria richiede report aggregabili e il file del dominio. I report aggregabili saranno i report JSON ricevuti nell'origine report e convertiti in formato AVRO. I domini di output conterranno le chiavi predichiarate che verranno raccolte dai report aggregabili e verranno scritte nei report di riepilogo. Scopri di più su queste chiavi in Attribution Reporting e sulle chiavi nell'aggregazione privata. Il dominio di output conterrà il bucket di campo e il valore del bucket sarà la chiave del bucket.
Il file del dominio dovrà inoltre essere in formato AVRO utilizzando il seguente schema:
{
"type": "record",
"name": "AggregationBucket",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "A single bucket that appears in the aggregation service output. 128-bit integer encoded as a 16-byte big-endian bytestring."
}
]
}
Chiave bucket
La chiave del bucket deve essere una stringa di byte esadecimale della chiave del bucket. Un esempio potrebbe essere avere una chiave di 1369 in decimale. Se convertito in esadecimale, il valore sarà 559. Quindi sarà necessario convertire 559 in una bytestring da aggiungere al dominio di output AVRO
Report batch
Per saperne di più sui budget per la privacy e sul raggruppamento in batch, consulta il documento sulle strategie di raggruppamento. Inoltre, tieni presente che un report aggregabile può essere raggruppato solo in un determinato periodo di tempo. Un report non deve superare il valore MAX_REPORT_AGE tra il giorno scheduled_report_time e la data di esecuzione del batch (attualmente 90 giorni).
Report di riepilogo
Dopo il raggruppamento in batch, il servizio di aggregazione crea il report di riepilogo in formato AVRO. Il report di riepilogo utilizza lo schema results.avsc.
Il report di riepilogo si trova in output_data_blob_prefix nel bucket output_data_bucket_name indicato nella richiesta createJob.
Per i batch del servizio di aggregazione in cui è attivata la funzionalità 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 debug generato utilizza lo schema debug_results.avsc.
Sia il report di riepilogo che quello di debug verranno denominati [output_data_blob_prefix]-1-of-1.avro. Se il valore di output_data_blob_prefix è summary/summary.avro, il report si troverà nella cartella di riepilogo con il nome summary-1-of-1.avro.
results.avsc
{
"type": "record",
"name": "AggregatedFact",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "Histogram bucket used in aggregation. 128-bit integer encoded as a 16-byte big-endian bytestring. Leading 0-bits will be left out."
},
{
"name": "metric",
"type": "long",
"doc": "Metric associated with the bucket"
}
]
}
debug_results.avsc
{
"type": "record",
"name": "DebugAggregatedFact",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "Histogram bucket used in aggregation. 128-bit integer encoded as a 16-byte big-endian bytestring. Leading 0-bits will be left out."
},
{
"name": "unnoised_metric",
"type": "long",
"doc": "Unnoised metric associated with 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 avrà il seguente aspetto results.json. Quando debug_run è abilitato, il report di riepilogo del debug restituisce un risultato simile all'esempio debug_results.json.
results.json (esempio)
I report AVRO provenienti dal servizio di aggregazione possono avere un aspetto simile se hai la chiave del bucket e il valore di riepilogo/aggregato con il rumore aggiunto dei valori del bucket.
{
"bucket": "\u0005Y",
"metric": 26308
}
debug_results.json (esempio)
I report AVRO di debug provenienti dal servizio di aggregazione dovrebbero avere un aspetto simile al seguente, in cui ricevi le chiavi dei bucket, unnoised_metric (riepilogo delle chiavi dei bucket senza rumore) e il rumore aggiunto al unnoised_metric.
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
Le annotazioni conterranno anche in_reports e/o in_domain, che significano:
in_reports: la chiave del bucket è disponibile all'interno dei report aggregabiliin_domain: la chiave del bucket è disponibile all'interno del file AVRO dioutput_domain