Descripción general de la API de Private Aggregation

Genera informes de datos agregados con datos de Protected Audience y datos entre sitios del almacenamiento compartido.

Para proporcionar funciones esenciales en las que se basa la Web, se creó la API de agregación privada para agregar y generar informes sobre datos de varios sitios de una manera que preserva la privacidad.

Estado de implementación

¿Qué es la API de Private Aggregation?

La API de Private Aggregation permite a los desarrolladores generar informes de datos agregados con datos de la API de Protected Audience y datos entre sitios de Shared Storage.

La función principal de esta API se conoce como contributeToHistogram(). La operación de histograma te permite agregar datos de todos los usuarios en cada bucket (conocido en la API como una clave de agregación) que definas. Tu llamada al histograma acumula valores y muestra un resultado agregado con ruido en forma de informe de resumen. Por ejemplo, el informe podría mostrar la cantidad de sitios en los que cada usuario vio tu contenido o encontrar un error en tu secuencia de comandos de terceros. Esta operación se realiza dentro de la worklet de otra API.

Por ejemplo, si anteriormente registraste datos demográficos y geográficos en el almacenamiento compartido, puedes usar la API de Private Aggregation para crear un histograma que te indique aproximadamente cuántos usuarios de la ciudad de Nueva York vieron tu contenido en varios sitios. Para realizar la agregación para esta medición, puedes codificar la dimensión geográfica en la clave de agregación y contar los usuarios en el valor agregable.

Conceptos clave

Cuando llamas a la API de agregación privada con una clave de agregación y un valor agregable, el navegador genera un informe agregable.

Los informes agregables se envían a tu servidor para su recopilación y procesamiento por lotes. El servicio de agregación procesará los informes por lotes más adelante y se generará un informe de resumen.

Consulta el documento Conceptos básicos de la API de Private Aggregation para obtener más información sobre los conceptos clave relacionados con la API de Private Aggregation.

Diferencias con los informes de atribución

La API de Private Aggregation comparte muchas similitudes con la API de Attribution Reporting. Attribution Reporting es una API independiente diseñada para medir las conversiones, mientras que Private Aggregation se creó para realizar mediciones entre sitios en conjunto con APIs como la API de Protected Audience y Shared Storage. Ambas APIs producen informes agregables que consume el backend del servicio de agregación para generar informes de resumen.

Los Informes de atribución asocian los datos recopilados de un evento de impresión y un evento de conversión, que ocurren en diferentes momentos. La agregación privada mide un solo evento entre sitios.

Prueba esta API

Para probar la API de Private Aggregation de forma local, habilita todas las APIs de privacidad en los anuncios en chrome://settings/adPrivacy.

Obtén más información sobre las pruebas en Cómo participar en el experimento.

Cómo usar la demostración

Puedes acceder a la demostración de la API de Private Aggregation para Shared Storage en goo.gle/shared-storage-demo, y el código está disponible en GitHub. La demostración implementa las operaciones del cliente y produce un informe agregable que se envía a tu servidor.

En el futuro, se publicará una demostración de la API de Private Aggregation para la API de Protected Audience.

Casos de uso

Private Aggregation es una API de uso general para la medición entre sitios y está disponible para usarse en los worklets de Shared Storage y la API de Protected Audience. El primer paso es decidir específicamente qué información quieres recopilar. Esos datos son la base de tus claves de agregación.

Con almacenamiento compartido

Shared Storage te permite leer y escribir datos entre sitios en un entorno seguro para evitar filtraciones, y la API de Private Aggregation te permite medir los datos entre sitios almacenados en Shared Storage.

Medición de alcance único

Te recomendamos que midas cuántos usuarios únicos vieron su contenido. La API de Private Aggregation puede proporcionar una respuesta como "Aproximadamente 317 usuarios únicos vieron el Content ID 861".

Puedes establecer una marca en el almacenamiento compartido para indicar si el usuario ya vio el contenido o no. En la primera visita en la que no existe la marca, se realiza una llamada a la agregación privada y, luego, se establece la marca. En las visitas posteriores del usuario, incluidas las visitas entre sitios, puedes verificar el almacenamiento compartido y omitir el envío de un informe a la agregación privada si se configuró la marca. Para obtener más información sobre los métodos para implementar estas mediciones, consulta nuestro informe sobre el alcance.

Medición de datos demográficos

Te recomendamos que midas los datos demográficos de los usuarios que vieron tu contenido en diferentes sitios.

La agregación privada puede proporcionar una respuesta, como "Aproximadamente 317 usuarios únicos tienen entre 18 y 45 años y son de Alemania". Usa el almacenamiento compartido para acceder a los datos demográficos desde un contexto de terceros. Más adelante, puedes generar un informe con la agregación privada si codificas las dimensiones de grupo etario y país en la clave de agregación.

Medición de frecuencia de K+

Es posible que desees medir la cantidad de usuarios que vieron un contenido o un anuncio al menos K veces en un navegador determinado, para un valor de K elegido de antemano.

La agregación privada puede proporcionar una respuesta como "Aproximadamente 89 usuarios vieron el ID de contenido 581 al menos 3 veces". Un contador se puede incrementar en el almacenamiento compartido desde diferentes sitios y se puede leer dentro de una worklet. Cuando el recuento alcance K, se podrá enviar un informe con la agregación privada.

Atribución de múltiples puntos de contacto

Esta guía se publicará en el sitio para desarrolladores para que las tecnologías publicitarias puedan comprender cómo implementar MTA en el almacenamiento compartido y la agregación privada.

Con la API de Protected Audience

La API de Protected Audience habilita casos de uso de resegmentación y públicos personalizados, y Private Aggregation te permite informar eventos de las worklets del comprador y del vendedor. La API se puede usar para tareas como medir la distribución de las ofertas de subasta.

Desde una tarea de la API de Protected Audience, puedes agregar tus datos directamente con contributeToHistogram() y generar informes sobre ellos en función de un activador con contributeToHistogramOnEvent(), que es una extensión especial para la API de Protected Audience.

Funciones disponibles

Las siguientes funciones están disponibles en el objeto privateAggregation disponible en los worklets de las APIs de Shared Storage y Protected Audience.

contributeToHistogram()

Puedes llamar a privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }), donde la clave de agregación es bucket y el valor agregable es value. Para el parámetro bucket, se requiere un BigInt. Para el parámetro value, se requiere un número entero.

Este es un ejemplo de cómo se puede llamar en el almacenamiento compartido para la medición del alcance:

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', {
  data: { contentId: '1234' }
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await sharedStorage.get(key) === 'true';

    // Don't send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId),
      value: 1 * SCALE_FACTOR
    });

    // Set the flag in Shared Storage
    await sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

El ejemplo de código anterior llamará a la agregación privada cada vez que se cargue el contenido del iframe entre sitios. El código de iframe carga la worklet, que llama a la API de Private Aggregation con el ID de contenido convertido en una clave de agregación (bucket).

contributeToHistogramOnEvent()

Solo en los worklets de la API de Protected Audience, proporcionamos un mecanismo basado en activadores para enviar un informe solo si ocurre un evento determinado. Esta función también permite que el bucket y el valor dependan de indicadores que aún no están disponibles en ese momento de la subasta.

El método privateAggregation.contributeToHistogramOnEvent(eventType, contribution) toma un eventType que especifica el evento de activación y el contribution que se enviará cuando se active el evento. El evento activador puede provenir de la subasta después de que esta finaliza, como un evento de ganancia o pérdida de la subasta, o puede provenir de un marco cercado que renderizó el anuncio.

Para enviar un informe de los eventos de subasta, puedes usar dos palabras clave reservadas: reserved.win, reserved.loss y reserved.always. Para enviar un informe activado por un evento de un marco delimitado, define un tipo de evento personalizado. Para activar el evento desde un marco de zona restringida, usa el método fence.reportEvent() disponible en la API de informes de anuncios de marcos de zona restringida.

En el siguiente ejemplo, se envía un informe de impresiones cuando se activa el evento de ganar la subasta y un informe de clics si se activa un evento click desde el marco cercado que renderizó el anuncio. Estos dos valores se pueden usar para calcular el porcentaje de clics.

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

Consulta la explicación de los informes de agregación privada extendida para obtener más información.

enableDebugMode()

Mientras las cookies de terceros sigan disponibles, proporcionaremos un mecanismo temporal que permita facilitar la depuración y las pruebas habilitando el modo de depuración. Un informe de depuración es útil para comparar tus mediciones basadas en cookies con tus mediciones de agregación privada y también te permite validar rápidamente tu integración de API.

Llamar a privateAggregation.enableDebugMode() en la worklet habilita el modo de depuración, lo que hace que los informes agregables incluyan la carga útil sin encriptar (texto simple). Luego, puedes procesar estas cargas útiles con la herramienta de prueba local del servicio de agregación.

El modo de depuración solo está disponible para los llamadores que tienen permiso para acceder a las cookies de terceros. Si el llamador no tiene acceso a las cookies de terceros, enableDebugMode() fallará de forma silenciosa.

También puedes establecer la clave de depuración llamando a privateAggregation.enableDebugMode({ <debugKey: debugKey> }), donde se puede usar un BigInt como clave de depuración. La clave de depuración se puede usar para asociar datos de una medición basada en cookies y datos de una medición de agregación privada.

Se puede llamar a estos solo una vez por contexto. Todas las llamadas posteriores arrojarán una excepción.

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

Verificación de informes

La API de Private Aggregation habilita la medición entre sitios y, al mismo tiempo, protege la privacidad del usuario. Sin embargo, las personas que actúan de mala fe pueden intentar manipular la exactitud de estas mediciones. Para evitar esto, puedes usar un ID de contexto para verificar la autenticidad de los informes.

Establecer un ID de contexto ayuda a garantizar que los datos sean precisos cuando contribuyen a los resultados agregados finales. Para ello, sigue estos pasos:

• Prevenir informes ilegítimos o no auténticos: Asegúrate de que los informes se generen a través de llamadas a la API legítimas y auténticas, lo que dificulta la fabricación de informes por parte de personas o entidades que actúan de mala fe.
• Prevenir la repetición de informes: Detecta y rechaza cualquier intento de reutilizar informes antiguos, lo que garantiza que cada informe se agregue solo una vez a los resultados agregados.

Almacenamiento compartido

Cuando usas el almacenamiento compartido para ejecutar una operación que puede enviar un informe agregable, puedes establecer un ID impredecible fuera de la worklet.

Este ID se incorpora en el informe creado a partir de la worklet. Puedes especificarlo cuando llames a los métodos de almacenamiento compartido run() o selectURL(), dentro del objeto de opciones, en la clave privateAggregationConfig.

Por ejemplo:

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

Una vez que se configure este ID, podrás usarlo para verificar que el informe se haya enviado desde tu operación de almacenamiento compartido. Para evitar la filtración de información, se envía exactamente un informe por operación de almacenamiento compartido (incluso si no se realizan contribuciones), independientemente de la cantidad de llamadas a contributeToHistogram().

La API de Private Aggregation envía informes agregables con una demora aleatoria de hasta una hora. Sin embargo, configurar un ID de contexto para verificar un informe reduce esta demora. En este caso, hay una demora fija y más pequeña de 5 segundos desde que comienza la operación de almacenamiento compartido.

Un flujo de trabajo de ejemplo (como se muestra en el diagrama anterior):

1. La operación de almacenamiento compartido se ejecuta con una configuración de agregación privada que especifica un ID de contexto y se genera un informe agregable.
2. El ID de contexto se incorpora en el informe agregable generado que se envía a tu servidor.
3. Tu servidor recopila los informes agregables generados.
4. Los procesos de tu servidor verifican el ID de contexto en cada informe que se puede agrupar con tus IDs de contexto almacenados para garantizar su validez antes de agrupar los informes y enviarlos a tu servicio de agregación.

Verificación del ID de contexto

Los informes entrantes a tu servidor de recopilación se pueden verificar de diferentes maneras antes de enviarlos al servicio de agregación. Los informes con IDs de contexto no válidos se pueden rechazar en los siguientes casos:

• Desconocido: Si llega un informe con un ID de contexto que no creó tu sistema, puedes descartarlo. Esto evita que actores desconocidos o maliciosos inserten datos en tu canalización de agregación.
• Un duplicado: Si recibes dos (o más) informes con el mismo ID de contexto, significa que debes elegir cuál de ellos descartar.
• Marcado en la detección de spam:
  • Si detectas actividad sospechosa de un usuario, por ejemplo, un cambio repentino en su actividad, mientras se procesa su informe, puedes descartarlo.
  • Puedes almacenar informes junto con sus IDs de contexto y cualquier indicador relevante (por ejemplo, el usuario-agente, la fuente de referencia, etcétera). Más adelante, a medida que analices el comportamiento de los usuarios y identifiques nuevos indicadores de spam, podrás volver a evaluar los informes almacenados en función de sus IDs de contexto y sus indicadores asociados. Esto te permite descartar los informes de los usuarios que muestran actividad sospechosa, incluso si no se marcaron inicialmente.

Interactúa y comparte comentarios

La API de Private Aggregation está en discusión activa y está sujeta a cambios en el futuro. Si pruebas esta API y tienes comentarios, nos encantaría conocerlos.

• GitHub: Lee la explicación, haz preguntas y participa en el debate.
• Asistencia para desarrolladores: Haz preguntas y únete al debate del 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 conocer los anuncios más recientes relacionados con Private Aggregation.