Cuando las tecnologías publicitarias activan las APIs de medición (API de Attribution Reporting o API de Private Aggregation), los informes encriptados se envían desde el navegador Chrome o el cliente al extremo de informes de la tecnología publicitaria, que es una URL .well-known con el origen de informes de la tecnología publicitaria. La tecnología publicitaria aloja el extremo de informes para recopilar los informes encriptados.
Los siguientes son los extremos por API:
Private Aggregation
- Depuración
[reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage [reporting-origin]/.well-known/private-aggregation/report-shared-storageo/.well-known/private-aggregation/report-protected-audienceen vivo
- Depuración
Informes de atribución
- Depuración
[reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution - En vivo
[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution
- Depuración
Las tecnologías publicitarias recibirán los informes en formato JSON a través de una llamada POST. Las tecnologías publicitarias recopilarán estos informes JSON y, luego, los convertirán al formato AVRO que se usa en el servicio de agregación. Una vez convertidos, los informes AVRO se almacenan en el almacenamiento en la nube de la tecnología publicitaria para realizar el procesamiento por lotes más adelante.
Una vez que la tecnología publicitaria esté lista para el procesamiento por lotes, esta activará una solicitud de trabajo de agregación a través del servicio de agregación, en el que se recuperan los informes del almacenamiento en la nube de la tecnología publicitaria. El servicio de agregación se aloja en el almacenamiento en la nube de la tecnología publicitaria y debe tener una imagen incluida en la lista de entidades permitidas.
Los informes recibidos son similares a los siguientes:
API de 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 de 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"
}
Convierte informes de JSON a AVRO
Cuando se agrupan, los informes agregables deben estar en formato AVRO. Para crear un informe AVRO, necesitarás el esquema AVRO del informe (AVSC).
Hay un código de JavaScript de muestra disponible en el repositorio de GitHub del servicio de agregación.
El siguiente es el esquema AVRO para los informes agregables. Los diferentes campos de los informes son payload, key_id y shared_info.
{
"type": "record",
"name": "AggregatableReport",
"fields": [
{
"name": "payload",
"type": "bytes"
},
{
"name": "key_id",
"type": "string"
},
{
"name": "shared_info",
"type": "string"
}
]
}
| Parámetro | Tipo | Descripción |
|---|---|---|
payload |
Bytes |
La carga útil deberá decodificarse en base64 y convertirse en un array de bytes de payload para los informes en vivo o de producción.
|
debug_cleartext_payload |
Bytes |
La carga útil deberá decodificarse en base64 y convertirse en un array de bytes de debug_cleartext_payload para los informes de depuración.
|
key_id |
String | Esta será la cadena key_id que se encuentra en el informe. key_id será un identificador único universal de 128 bits similar. |
shared_info |
String | Esta será la cadena sin alteraciones que se encuentra en el campo shared_info del informe. |
Este es un ejemplo de informe 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 de dominio de salida
Para generar informes de resumen con el servicio de agregación, la tecnología publicitaria requiere los informes agregables y el archivo de dominio. Los informes agregables serán los informes JSON recibidos en el origen de informes y convertidos al formato AVRO. Los dominios de salida contendrán las claves declaradas previamente que se recopilarán de tus informes agregables y se escribirán en los informes de resumen. Obtén más información sobre estas claves en los informes de atribución y las claves en la agregación privada. El dominio de salida contendrá el bucket de campo y el valor del bucket será tu clave de bucket.
El archivo de dominio también deberá estar en formato AVRO con el siguiente esquema:
{
"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."
}
]
}
Clave de bucket
La clave del bucket debe ser una cadena de bytes hexadecimal de la clave del bucket. Un ejemplo de esto sería tener una clave de 1369 en decimal. Cuando se convierta a hexadecimal, será 559. Luego, deberás convertir 559 en una cadena de bytes para agregarla al dominio de salida AVRO.
Informes por lotes
Para obtener más información sobre los presupuestos de privacidad y el procesamiento por lotes, consulta el documento sobre estrategias de procesamiento por lotes. Además, ten en cuenta que un informe agregable solo se puede procesar por lotes dentro de un período determinado. Un informe no debe superar el valor de MAX_REPORT_AGE entre scheduled_report_time y la fecha de ejecución por lotes (actualmente, 90 días).
Informes de resumen
Después de la agrupación por lotes, el servicio de agregación crea el informe de resumen en formato AVRO. El informe de resumen usa el esquema results.avsc.
El informe de resumen se ubicará en output_data_blob_prefix en el bucket output_data_bucket_name que se indica en la solicitud createJob.
En el caso de los lotes del servicio de agregación en los que debug_run está habilitado, se crean dos informes. El informe de resumen y el informe de resumen de depuración. El informe de resumen de depuración se ubicará en la carpeta output_data_blob_prefix/debug.
El informe de depuración generado usa el esquema debug_results.avsc.
Tanto el informe de resumen como el de depuración se nombrarán como [output_data_blob_prefix]-1-of-1.avro. Si tu output_data_blob_prefix es summary/summary.avro, el informe estará en la carpeta de resumen con el nombre 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 vez que se convierta, tu informe de resumen se verá como el ejemplo results.json. Cuando debug_run está habilitado, el informe de resumen de depuración muestra algo similar al ejemplo debug_results.json.
results.json (ejemplo)
Los informes AVRO que provienen del servicio de agregación pueden verse similares cuando tienes la clave de bucket y el valor de resumen o agregado con el ruido agregado de los valores del bucket.
{
"bucket": "\u0005Y",
"metric": 26308
}
debug_results.json (ejemplo)
Los informes de depuración de AVRO que provienen del servicio de agregación deberían verse de manera similar a la siguiente, en la que recibes las claves de bucket, unnoised_metric (resumen de las claves de bucket sin ruido) y el ruido que se agrega a unnoised_metric.
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
Las anotaciones también contendrán in_reports o in_domain, lo que significa lo siguiente:
in_reports: La clave del bucket está disponible en los informes agregables.in_domain: La clave del bucket está disponible dentro del archivo AVROoutput_domain.