Conceptos clave de la API de Private Aggregation
¿A quién está dirigido este documento?
La API de Private Aggregation permite la recopilación de datos agregados de los worklets con acceso a datos de varios sitios. Los conceptos que se comparten aquí son importantes para los desarrolladores que crean informes funciones en el almacenamiento compartido y la API de Protected Audience.
- Si usted es desarrollador y está creando un sistema de informes para varios sitios de medición.
- Si eres especialista en marketing, científico de datos o cualquier otro informe de resumen consumidor, comprender estos mecanismos te ayudará a tomar decisiones de diseño decisiones para recuperar un informe de resumen optimizado.
Términos clave
Antes de leer este documento, te recomendamos que te familiarices con en términos y conceptos clave. Cada una de estas condiciones se describe en detalle aquí.
- Una clave de agregación (también conocida como bucket) es un conjunto predeterminado de datos. Por ejemplo, es posible que quieras recopilar un bucket de datos de ubicación en el que el navegador informa el país de la fuente de datos. Una clave de agregación puede contener más de una dimensión (por ejemplo, el país y el ID del widget de contenido).
- Un valor agregable es un dato individual.
recopilarse en una clave de agregación. Si quieres medir cuántos usuarios
de Francia vieron tu contenido, por lo tanto,
France
es una dimensión del clave de agregación y elviewCount
de1
es el valor agregable. - Los informes agregables se generan y encriptan en un navegador. Para el API de Private Aggregation, contiene datos sobre un solo evento.
- El servicio de agregación procesa datos de informes agregables para crear un informe de resumen.
- Un informe de resumen es el resultado final del servicio de agregación. contiene datos de usuarios agregados inconsistentes y datos de conversiones detallados.
- Un worklet es una pieza de infraestructura que te permite ejecutar funciones específicas de JavaScript y la información de vuelta al solicitante. Dentro de un worklet, puedes ejecutar JavaScript, pero no puedes interactuar ni comunicarte con la página externa.
Flujo de trabajo de agregación privada
Cuando llamas a la API de Private Aggregation con una clave de agregación y un con un valor agregable, el navegador genera un informe agregable. Los informes se envían a tu servidor que agrupa los informes en lotes. Los informes por lotes se que luego procesa el servicio de agregación y se genera un informe de resumen.
![Los datos fluyen del cliente al recopilador y, luego, a la Agregación.
Servicio para generar un informe de resumen.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/data-flows-the-client-t-ebd6f5c55d92f.png?authuser=19&hl=es)
- Cuando llamas a la API de Private Aggregation, el cliente (navegador) genera y lo envía a tu servidor para que se recopile.
- Tu servidor recopila los informes de los clientes y los agrupa en lotes para enviados al servicio de agregación.
- Una vez que hayas recopilado suficientes informes, los enviarás por lotes y los enviarás al de agregación, que se ejecuta en un entorno de ejecución confiable, para generar un informe de resumen.
El flujo de trabajo que se describe en esta sección es similar al de Attribution Reporting API Sin embargo, la atribución Los informes asocian los datos recopilados de un evento de impresión y una conversión. evento, que ocurren en diferentes momentos. La agregación privada mide un único entre sitios.
Clave de agregación
Una clave de agregación (“clave” para abreviar) representa el bucket al que los valores agregables se acumularán. Se pueden codificar una o más dimensiones en la clave. Una dimensión representa algún aspecto del que quieres obtener más estadísticas, como la edad de los usuarios o el recuento de impresiones de un anuncio campaña.
Por ejemplo, puedes tener un widget incorporado en varios sitios y quieres analizar el país de los usuarios que vieron tu widget. Estás mirando para responder preguntas como “¿Cuántos de los usuarios que vieron mi widget están del país X?". Para informar sobre esta pregunta, puedes configurar una clave de agregación que codifica dos dimensiones: el ID del widget y el ID del país.
La clave proporcionada a la API de Private Aggregation es una
BigInt
que consta de varias dimensiones. En este ejemplo, las dimensiones son las
el ID del widget y el ID del país. Supongamos que el ID del widget puede tener hasta 4 dígitos.
largo, como 1234
, y cada país se asigna a un número en orden alfabético
como Afganistán es 1
, Francia es 61
y Zimbabue es '195'.
Por lo tanto, la clave agregable tendría 7 dígitos, mientras que los primeros 4
caracteres están reservados para WidgetID
; los últimos 3 caracteres
reservado para CountryID
.
Supongamos que la clave representa el recuento de usuarios de Francia (ID de país 061
).
que vieron el ID del widget 3276
, la clave de agregación es 3276061
.
Clave de agregación | |
ID del widget | ID del país |
3276 | 061 |
La clave de agregación también se puede generar con un mecanismo de hash, como
SHA-256 Por ejemplo, la cadena
{"WidgetId":3276,"CountryID":67}
puede generar un hash y, luego, convertirse en
Valor BigInt
de
42943797454801331377966796057547478208888578253058197330928948081739249096287n
Si el valor de hash tiene más de 128 bits, puedes truncarlo para asegurarte de que no
supera el valor máximo permitido del bucket de 2^128−1
.
En un worklet del Almacenamiento compartido, puedes acceder al
crypto
y
Módulos TextEncoder
que pueden ayudarte a generar un hash. Para obtener más información sobre cómo generar un hash, consulta
SubtleCrypto.digest()
activado
MDN.
En el siguiente ejemplo, se describe cómo generar una clave de bucket a partir de un código valor:
async function convertToBucket(data) {
// Encode as UTF-8 Uint8Array
const encodedData = new TextEncoder().encode(data);
// Generate SHA-256 hash
const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);
// Truncate the hash
const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));
// Convert the byte sequence to a decimal
return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}
const data = {
WidgetId: 3276,
CountryID: 67
};
const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);
console.log(bucket); // 126200478277438733997751102134640640264n
Valor agregable
Los valores agregables se suman por clave entre muchos usuarios para generar estadísticas en forma de valores resumidos en informes resumidos.
Ahora, volvamos a la pregunta de ejemplo anterior: “¿Cuántos de los usuarios que vieron mi widget son de Francia?". La respuesta a esta pregunta se verá algo como "Aproximadamente 4881 usuarios que vieron mi ID de widget 3276 están de Francia". El valor agregable es 1 para cada usuario y "4881 usuarios" es El valor agregado, que es la suma de todos los valores agregables de ese clave de agregación.
Clave de agregación | Valor agregable | |
ID del widget | ID del país | Recuento de vistas |
3276 | 061 | 1 |
En este ejemplo, aumentamos el valor en 1 por cada usuario que vea el widget. En la práctica, el valor agregable se puede escalar para mejorar la señal a ruido relación de aspecto.
Presupuesto de contribución
Cada llamada a la API de Private Aggregation se denomina contribución. Para proteger privacidad del usuario, la cantidad de contribuciones que se pueden recopilar de un individuos son limitados.
Cuando sumas todos los valores agregables en todas las claves de agregación, la suma debe será inferior al presupuesto de contribución. El presupuesto se limita a cada trabajo. origin, por día, y es independientes para la API de Protected Audience y los worklets de almacenamiento compartido. Una línea de tiempo de las últimas 24 horas aproximadamente. Si un nuevo cliente o un informe agregable haría que se exceda el presupuesto, el informe no crear.
El presupuesto de contribución está representado por el parámetro L1 y es se establece en 216 (65,536) cada diez minutos al día, con un respaldo de 220
(1,048,576). Consulta la explicación para obtener más información sobre estos parámetros.
El valor del presupuesto de contribución es arbitrario, pero el ruido se escala a él. Puedes usar este presupuesto para maximizar la relación señal/ruido en los valores de resumen. (se analizan con más detalle en la sección Ruido y escalamiento).
Si deseas obtener más información sobre los presupuestos de contribución, consulta el explicación. Consulta la sección Contribución Presupuesto para obtener más orientación.
Informes agregables
Una vez que el usuario invoca la API de Private Aggregation, el navegador generará
informes agregables para que el servicio de agregación los procese en otro momento.
a tiempo para generar un resumen
informes. Los
informe agregable tiene formato JSON y contiene una lista encriptada de
contribuciones, cada una es un par de {aggregation key, aggregatable value}
.
Los informes agregables se envían con un retraso aleatorio de hasta una hora.
Las contribuciones están encriptadas y no son legibles fuera del servicio de agregación. El servicio de agregación desencripta los informes y genera un informe de resumen. El la clave de encriptación para el navegador y la clave de desencriptación para la agregación Los servicios son emitidos por el coordinador, que actúa como el servicio de administración de claves. El coordinador mantiene una lista de hashes binarios de la imagen del servicio para verificar. que el llamador pueda recibir la clave de desencriptación.
Un ejemplo de informe agregable con debug automático habilitado:
"aggregation_service_payloads": [
{
"debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
"key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
"payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
}
],
"debug_key": "777",
"shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"
Los informes agregables se pueden inspeccionar desde el
Página chrome://private-aggregation-internals
:
![captura de pantalla de la página de componentes internos de la API de Private Aggregation](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/screenshot-the-private-a-132a69aaab759.png?authuser=19&hl=es)
Para realizar pruebas, el sitio web "Enviar informes seleccionados" se puede usar para enviar el informar al servidor de inmediato.
Recopilar y agrupar en lotes informes
El navegador envía los informes agregables al origen del worklet que contiene la llamada a la API de Private Aggregation, mediante los atributos ruta:
- Para el almacenamiento compartido:
/.well-known/private-aggregation/report-shared-storage
- Para Protected Audience:
/.well-known/private-aggregation/report-protected-audience
En estos endpoints, deberá operar un servidor (que actúe como recopilador) que recibe los informes agregables enviados por los clientes.
Luego, el servidor debe agrupar los informes y enviarlo a la herramienta de
Servicio. Crear lotes según la información disponible en la carpeta sin encriptar
la carga útil del informe agregable, como el campo shared_info
. Idealmente,
Los lotes deben contener 100 informes o más por lote.
Puedes elegir agrupar los datos en lotes de forma diaria o semanal. Esta estrategia es flexible, y puedes cambiar tu estrategia de lotes para eventos específicos en los que esperas más volumen, por ejemplo, los días del año en los que se esperan más impresiones. Los lotes deben incluir informes de la misma versión de la API, origen de informes y programar la hora del informe.
Servicio de agregación
![El servicio se ejecuta en un TEE, desencripta los informes agregables y agrega
para crear el informe de resumen final.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/the-service-runs-a-tee-746adddcc2c6.png?authuser=19&hl=es)
El servicio de agregación recibe informes agregables encriptados del recopilador y genera resúmenes informes.
Para desencriptar la carga útil del informe, el servicio de agregación recupera una clave de desencriptación del coordinador. El servicio se ejecuta en un entorno de ejecución confiable (TEE) lo que brinda un nivel de garantía de la integridad y la confidencialidad de los datos, y la integridad del código. Aunque seas el propietario del servicio y lo administres, no tendrás visibilidad de los datos que se procesan dentro del TEE.
Resumen de informes
Informes de resumen le permiten ver los datos que ha recopilado con ruido agregado. Puedes solicitar informes de resumen para un conjunto de claves determinado.
Un informe de resumen contiene un conjunto de pares clave-valor con estilo de diccionario JSON. Cada el par contiene:
bucket
: Es la clave de agregación como una cadena de número binario. Si el botón clave de agregación utilizada es “123”, entonces el bucket es “1111011”.value
: El valor del resumen de un objetivo de medición determinado, resumido del todos los informes agregables disponibles con ruido agregado.
Por ejemplo:
[
{"bucket":` `"111001001",` `"value":` `"2558500"},
{"bucket":` `"111101001",` `"value":` `"3256211"},
{"bucket":` `"111101001",` `"value":` `"6536542"},
]
Ruido y escalamiento
Para preservar la privacidad del usuario, el servicio de agregación agrega ruido una vez a cada el valor de resumen cada vez que se solicita un informe de resumen. Los valores de ruido son extraídas de forma aleatoria de una probabilidad de Laplace distribución. Mientras estés no tienes control directo sobre las formas en que se agrega ruido, puedes influir en el impacto de ruido en sus datos de medición.
La distribución de ruido es la misma, independientemente de la suma de todas las tablas de salida. Por lo tanto, cuanto más altos sean los valores agregables, menor será el impacto del ruido un modelo de AA.
Por ejemplo, digamos que la distribución de ruido tiene una desviación estándar de 100 y está centrada en cero. Si el valor recopilado del informe agregable (o “valor agregable”) es solo 200, entonces la desviación estándar del ruido sería el 50% del valor agregado. Pero, si el valor agregable es 20,000, entonces la desviación estándar de ruido sería únicamente el 0.5% del valor agregado. Entonces, agregable de 20,000 tendría una proporción entre señal y ruido mucho más alta.
Por lo tanto, multiplicar tu valor agregable por un factor de escalamiento puede ayudarte reducir el ruido. El factor de escala representa cuánto deseas escalar en un determinado un valor agregable.
![El ruido es constante independientemente del valor agregado.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/noise-is-constant-regardl-6c311a31c1292.png?authuser=19&hl=es)
Aumentar los valores con un factor de escala mayor reduce la cantidad ruido de fondo. Sin embargo, esto también suma todas las contribuciones de todos los buckets para alcanzar el límite del presupuesto de contribución más rápido. Disminuir los valores en elegir una constante de factor de escala más pequeña aumenta el ruido relativo, pero reduce el riesgo de alcanzar el límite del presupuesto.
![Escalar el valor agregable al presupuesto de contribución](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/scale-aggregatable-value-b7347ae673f12.png?authuser=19&hl=es)
Para calcular un factor de escala adecuado, divide el presupuesto de contribución por la suma máxima de valores agregables en todas las claves.
Consulta el Presupuesto de contribución documentación para obtener más información.
Interactúa y comparte tus comentarios
La API de Private Aggregation se encuentra en discusión y sujeta a cambios en el futuro. Si pruebas esta API y tienes comentarios, nos encantaría recibirlos.
- GitHub: Consulta el explicación, plantear preguntas y participar debate. * Asistencia para desarrolladores: Haz preguntas y únete a debates en el Asistencia para desarrolladores de Privacy Sandbox repo. * Únete a la API de Shared Storage. grupo y la API de Protected Audience grupo para conocer los anuncios más recientes relacionados con la agregación privada.