Conceptos básicos de la API de Private Agregación

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 desde trabajos que tienen acceso a datos entre sitios. Los conceptos que se comparten aquí son importantes para los desarrolladores que crean funciones de informes dentro de la API de Shared Storage y Protected Audience.

• Si eres desarrollador y estás creando un sistema de informes para la medición entre sitios,
• Si eres especialista en marketing, científico de datos o algún otro usuario de informes de resumen, comprender estos mecanismos te ayudará a tomar decisiones de diseño para recuperar un informe de resumen optimizado.

Términos clave

Antes de leer este documento, será útil que te familiarices con los términos y conceptos clave. Cada uno de estos términos se describirá en detalle aquí.

• Una clave de agregación (también conocida como bucket) es una colección predeterminada de datos. Por ejemplo, es posible que desees recopilar un bucket de datos de ubicación en el que el navegador informe el nombre del país. 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 recopilado en una clave de agregación. Si deseas medir cuántos usuarios de Francia vieron tu contenido, France es una dimensión en la clave de agregación y viewCount de 1 es el valor agregable.
• Los informes agregables se generan y encriptan dentro de un navegador. Para la API de Private Aggregation, este 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 y contiene datos de usuario agregados ruidosos y datos de conversiones detallados.
• Un worklet es una parte de la infraestructura que te permite ejecutar funciones específicas de JavaScript y mostrar información 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 valor agregable, el navegador genera un informe agregable. Los informes se envían a tu servidor que agrupa los informes. El servicio de agregación procesa los informes por lotes y se genera un informe de resumen.

1. Cuando llamas a la API de Private Aggregation, el cliente (navegador) genera y envía el informe agregable a tu servidor para recopilarlo.
2. Tu servidor recopila los informes de los clientes y los agrupa en lotes para enviarlos al servicio de agregación.
3. Una vez que hayas recopilado suficientes informes, los enviarás por lotes al servicio de agregación, que se ejecutará en un entorno de ejecución confiable, para generar un informe de resumen.

Término clave: el entorno de ejecución confiable es una configuración especial de hardware y software informático que permite a terceros verificar las versiones exactas del software que se ejecuta en la computadora. Los TEE permiten que las partes externas verifiquen que el software hace exactamente lo que el fabricante afirma que hace, nada más o menos.

El flujo de trabajo que se describe en esta sección es similar al de la API de Attribution Reporting. Sin embargo, Attribution Reporting asocia los datos recopilados a partir de un evento de impresión y un evento de conversión, que ocurren en diferentes momentos. Private Aggregation mide un solo evento entre sitios.

Clave de agregación

Una clave de agregación (“clave” para abreviar) representa el bucket en el que se acumularán los valores agregables. Se pueden codificar una o más dimensiones en la clave. Una dimensión representa algún aspecto sobre el que deseas obtener más información, como la edad de los usuarios o el recuento de impresiones de una campaña publicitaria.

Por ejemplo, es posible que tengas un widget incorporado en varios sitios y quieras analizar el país de los usuarios que lo vieron. Debes responder preguntas como “¿Cuántos de los usuarios que vieron mi widget son del país X?”. Para generar informes sobre esta pregunta, puedes configurar una clave de agregación que codifique dos dimensiones: ID del widget y, también, 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 el ID del widget y el ID del país. Supongamos que el ID del widget puede tener hasta 4 dígitos, como 1234, y que cada país se asigna a un número en orden alfabético, por ejemplo, Afganistán es 1, Francia es 61 y Zimbabue es "195". Por lo tanto, la clave agregable tendría 7 dígitos, en la que los primeros 4 caracteres se reservan para WidgetID y los últimos 3 caracteres 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

Ejemplo: Si una dimensión tiene espacio de claves disponible para varios dígitos, pero el valor tiene menos, agrega ceros a la izquierda. Por ejemplo, si el ID de país permite 3 dígitos, el ID del país para Argelia es 003.

La clave de agregación también se puede generar con un mecanismo de hash, como SHA-256. Por ejemplo, a la string {"WidgetId":3276,"CountryID":67} se le puede generar un hash y, luego, convertirse en un valor BigInt de 42943797454801331377966796057547478208888578253058197330928948081739249096287n. Si el valor de hash tiene más de 128 bits, puedes truncarlo para asegurarte de que no excederá el valor máximo permitido de bucket de 2^128−1.

Dentro de un worklet de almacenamiento compartido, puedes acceder a los módulos crypto y TextEncoder que pueden ayudarte a generar un hash. Si quieres obtener más información para generar un hash, consulta SubtleCrypto.digest() en MDN.

En el siguiente ejemplo, se describe cómo generar una clave de bucket a partir de un valor de hash:

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

Nota: Si bien los conceptos son similares, la clave se construye de manera diferente para la API de Private Aggregation y para la API de Attribution Reporting. Para Private Aggregation, la clave completa se especifica una sola vez, en la llamada de JavaScript.

Valor agregable

Los valores agregables se suman por clave entre muchos usuarios para generar estadísticas agregadas en forma de valores de resumen en los informes de resumen.

Ahora, regresa a la pregunta de ejemplo anterior: “¿Cuántos de los usuarios que vieron mi widget son de Francia?”. La respuesta a esta pregunta será similar a: "Aproximadamente 4881 usuarios que vieron mi ID de widget 3276 son de Francia". El valor agregable es 1 para cada usuario, y "4,881 usuarios" es el valor agregado que es la suma de todos los valores agregables para esa 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 de a 1 para cada usuario que vea el widget. En la práctica, el valor agregable se puede escalar para mejorar la relación señal/ruido.

Presupuesto de contribución

Cada llamada a la API de Private Aggregation se denomina contribución. Para proteger la privacidad del usuario, la cantidad de contribuciones que se puede recopilar de una persona es limitada.

Cuando sumes todos los valores agregables de todas las claves de agregación, la suma debe ser menor que el presupuesto de contribución. El presupuesto se define por origen de worklet, por día y es independiente de los trabajos de la API de Protected Audience y del almacenamiento compartido. Para el día, se utiliza un período móvil de aproximadamente las últimas 24 horas. Si un informe agregable nuevo hace que se supere el presupuesto, no se crea el informe.

El presupuesto de contribución se representa con el parámetro L₁ y se establece en 2¹⁶ (65,536) cada diez minutos por día con un respaldo de 2²⁰.

(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 ajusta a él. Puedes usar este presupuesto para maximizar la relación señal/ruido en los valores de resumen (se explica con más detalle en la sección Ruido y escalamiento).

Para obtener más información sobre los presupuestos de contribución, consulta la explicación. Además, consulta Presupuesto de contribución para obtener más información.

Informes agregables

Una vez que el usuario invoca la API de Private Aggregation, el navegador genera informes agregables que el servicio de agregación debe procesar más adelante para generar informes de resumen. Un informe agregable tiene formato JSON y contiene una lista encriptada de contribuciones, cada una de las cuales es un par {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 se pueden leer fuera del Servicio de agregación. El servicio de agregación desencripta los informes y genera un informe de resumen. El coordinador emite la clave de encriptación para el navegador y la clave de desencriptación para el servicio de agregación, que actúa como el servicio de administración de claves. El coordinador mantiene una lista de hashes binarios de la imagen de servicio para verificar que el emisor tenga permiso para recibir la clave de desencriptación.

Ejemplo de un informe agregable con el modo de depuración 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 la página chrome://private-aggregation-internals:

Para realizar pruebas, el botón “Send Selected Reports” se puede usar para enviar el informe al servidor de inmediato.

Recopila y agrega informes por lotes

El navegador envía los informes agregables al origen del worklet que contiene la llamada a la API de Private Aggregation, mediante la ruta conocida que aparece en la lista:

• Para el almacenamiento compartido: /.well-known/private-aggregation/report-shared-storage
• En el caso de Protected Audience: /.well-known/private-aggregation/report-protected-audience

En estos extremos, deberás operar un servidor, que actúe como recopilador, que reciba los informes agregables que envían los clientes.

Luego, el servidor debe enviar informes por lotes y enviarlos al servicio de agregación. Crea lotes según la información disponible en la carga útil no encriptada del informe agregable, como el campo shared_info. Lo ideal sería que los lotes contengan 100 o más informes por lote.

Puedes decidir agrupar con una frecuencia diaria o semanal. Esta estrategia es flexible, y puedes cambiar tu estrategia de lotes para eventos específicos en los que esperas un mayor 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 los informes y hora de programación del informe.

Servicio de agregación

El servicio de agregación recibe informes agregables encriptados del recopilador y genera informes de resumen.

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), que proporciona un nivel de garantía de la integridad de los datos, la confidencialidad de los datos y la integridad del código. Si bien eres el propietario y el administrador del servicio, no tendrás visibilidad de los datos que se procesan dentro del TEE.

Resumen de informes

Los informes de resumen te permiten ver los datos que recopilaste con ruido agregado. Puedes solicitar informes de resumen para un conjunto determinado de claves.

Un informe de resumen contiene un conjunto de pares clave-valor con estilo de diccionario JSON. Cada par contiene lo siguiente:

• bucket: Es la clave de agregación como una cadena de número binario. Si la clave de agregación que se usa es “123”, el bucket es “1111011”.
• value: Es el valor de resumen de un objetivo de medición determinado, sumado de 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 valor de resumen cada vez que se solicita un informe de resumen. Los valores de ruido se extraen de forma aleatoria a partir de una distribución de probabilidad de Laplace. Si bien no tienes el control directo de las formas en las que se agrega el ruido, puedes influir en el impacto del ruido en sus datos de medición.

La distribución de ruido es la misma sin importar la suma de todos los valores agregables. Por lo tanto, cuanto más altos sean los valores agregables, menor será el impacto que pueda tener el ruido.

Por ejemplo, supongamos que la distribución de ruido tiene una desviación estándar de 100 y está centrada en cero. Si el valor del informe agregable recopilado (o "valor agregable") es solo 200, la desviación estándar del ruido sería el 50% del valor agregado. Sin embargo, si el valor agregable es 20,000, la desviación estándar del ruido solo sería el 0.5% del valor agregado. Por lo tanto, el valor agregable de 20,000 tendría una relación señal-ruido mucho más alta.

Por lo tanto, multiplica el valor agregable por un factor de escala para reducir el ruido. El factor de escalamiento representa cuánto deseas escalar un valor agregable determinado.

Aumentar la escala de los valores mediante la elección de un factor de escala más grande reduce el ruido relativo. Sin embargo, esto también hace que la suma de todas las contribuciones de todos los buckets alcance más rápido el límite del presupuesto de contribuciones. Reducir los valores mediante la elección de 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.

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 la documentación sobre el presupuesto de contribución para obtener más información.

Interactúa y comparte comentarios

La API de Private Aggregation se está debatiendo y está sujeta a cambios en el futuro. Si pruebas esta API y tienes comentarios, nos encantaría recibirlos.

• GitHub: Lee la explicación, presenta preguntas y participa en el debate. * Asistencia para desarrolladores: Haz preguntas y únete a debates en el repositorio de asistencia para desarrolladores de Privacy Sandbox. * Únete al grupo de la API de Shared Storage y al grupo de la API de Protected Audience para ver los anuncios más recientes relacionados con la agregación privada.