Quando le tecnologie pubblicitarie attivano le API di misurazione (API Attribution Reporting o API Private Aggregation), i report criptati vengono inviati dal browser Chrome / lato client all'endpoint di reporting della tecnologia pubblicitaria, che è un URL .well-known con l'origine di reporting della tecnologia pubblicitaria. L'endpoint di reporting è ospitato dalla tecnologia pubblicitaria per raccogliere i report criptati.
Di seguito sono riportati gli endpoint per API:
Private Aggregation
- Debug
[reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage - Live
[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 tempo reale
[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution
- Debug
Le tecnologie pubblicitarie riceveranno i report in formato JSON tramite una chiamata POST. Le tecnologie pubblicitarie raccoglieranno questi report JSON e li convertiranno in formato AVRO, utilizzato nel servizio di aggregazione. Una volta convertiti, i report AVRO vengono archiviati nello spazio di archiviazione cloud della tecnologia pubblicitaria per il successivo raggruppamento.
Una volta che la tecnologia pubblicitaria è pronta per il batching, attiverà una richiesta di job di aggregazione tramite il servizio di aggregazione, in cui i report vengono recuperati dallo spazio di archiviazione cloud della tecnologia pubblicitaria. Aggregation Service è ospitato nello spazio di archiviazione cloud della tecnologia pubblicitaria e deve avere un'immagine inclusa nella lista consentita.
Le segnalazioni ricevute sono simili alla seguente:
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 AVRO
Quando vengono raggruppati, 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 del servizio di aggregazione.
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 live / 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 | Questa sarà la stringa key_id trovata nel report. L'ID chiave sarà un identificatore univoco universale a 128 bit simile. |
shared_info |
Stringa | Questa sarà la stringa non manomessa trovata nel campo shared_info del report. |
Ecco un esempio di file JSON del report:
{
"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 del dominio di output
Per generare report di riepilogo utilizzando il servizio di aggregazione, la tecnologia pubblicitaria richiede i report aggregabili e il file di dominio. I report aggregabili saranno i report JSON ricevuti nell'origine dei report e convertiti in formato AVRO. I domini di output conterranno le chiavi dichiarate in precedenza che verranno raccolte dai report aggregabili e scritte nei report di riepilogo. Scopri di più su queste chiavi in Attribution Reporting e sulle chiavi in Private Aggregation. Il dominio di output conterrà il bucket del campo e il valore del bucket sarà la chiave del bucket.
Anche il file di dominio dovrà 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 del bucket
La chiave del bucket deve essere una stringa di byte esadecimali della chiave del bucket. Un esempio è una chiave di 1369 in formato decimale. Se convertito in esadecimale, il valore sarà 559. A questo punto, devi convertire 559 in una stringa di byte da aggiungere all'AVRO del dominio di output
Report batch
Per saperne di più sui budget di privacy e sul batching, consulta il documento sulle strategie di batching. Tieni inoltre presente che un report aggregabile può essere raggruppato in batch solo entro un determinato periodo di tempo. Un report non deve superare il valore MAX_REPORT_AGE tra la data scheduled_report_time e la data di esecuzione del batch (attualmente 90 giorni).
Report di riepilogo
Dopo il 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 troverà in output_data_blob_prefix nel bucket output_data_bucket_name indicato nella richiesta createJob.
Per i batch del servizio di aggregazione in cui è abilitato debug_run, vengono creati due report. Il report di riepilogo e il report di riepilogo di debug. Il report di riepilogo del debug si troverà 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 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 riepilogativo sarà simile all'esempio 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 in cui sono presenti la chiave del bucket e il valore di riepilogo / aggregato con 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 essere simili al seguente, in cui ricevi le chiavi del bucket, unnoised_metric (riepilogo delle chiavi del bucket senza rumore) e il rumore aggiunto a unnoised_metric.
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
Le annotazioni conterranno anche in_reports e / o in_domain, il che significa:
in_reports: la chiave del bucket è disponibile all'interno dei report aggregabiliin_domain: la chiave del bucket è disponibile all'interno del file AVROoutput_domain