Cuando las plataformas de tecnología publicitaria 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 plataforma de 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:
Agregación privada
- Depurar
[reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage - En vivo el
[reporting-origin]/.well-known/private-aggregation/report-shared-storageo/.well-known/private-aggregation/report-protected-audience
- Depurar
Informes de atribución
- Depurar
[reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution - En vivo
[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution
- Depurar
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 su posterior agrupamiento.
Una vez que la tecnología publicitaria está lista para agruparse en lotes, activará una solicitud de trabajo de agregación a través de un servicio de agregación en el que los informes se recuperan 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 al siguiente:
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 en AVRO
Cuando se agrupan por lotes, 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.
Puedes tener 1 archivo AVRO para todos tus informes o dividir los informes en varios archivos AVRO. No hay límite de tamaño para AVRO. Por motivos de rendimiento, se recomienda mantener la cantidad de archivos AVRO entre la cantidad de CPUs disponibles para tu instancia de Cloud y 1,000.
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. El key_id será un identificador único universal de 128 bits similar. |
shared_info |
String | Esta será la cadena no manipulada que se encuentra en el campo shared_info del informe. |
Este es un ejemplo de JSON de informe:
{
"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 del informe y convertidos al formato AVRO. Los dominios de salida contendrán las claves declaradas previamente que se recopilarán de sus informes agregables y se escribirán en los informes de resumen. Obtén más información sobre estas claves en Attribution Reporting 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.
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 Hex, será 559. Luego, deberás convertir 559 en una cadena de bytes para agregarlo al dominio de salida AVRO.
Informes por lotes
Para obtener más información sobre los presupuestos de privacidad y la agrupación en lotes, consulta el documento sobre estrategias por lotes. Además, ten en cuenta que un informe agregable solo se puede agrupar en 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).
Resumen de informes
Después de realizar el procesamiento 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 encontrará en output_data_blob_prefix dentro del bucket output_data_bucket_name indicado en la solicitud createJob.
Para 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 del 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 dentro de los informes agregables.in_domain: La clave del bucket está disponible dentro del archivo AVROoutput_domain.