Descripción general de la API de Private Aggregation

Generar informes de datos agregados con datos de Protected Audience y datos de varios sitios de Shared Storage

Para proporcionar funciones críticas en las que se basa la Web, se creó la API de Private Aggregation, que permite agregar datos de varios sitios y generar informes sobre ellos de una manera que preserva la privacidad.

Estado de implementación

¿Qué es la API de Private Aggregation?

La API de Private Aggregation permite que los desarrolladores generen informes de datos agregados con datos de la API de Protected Audience y datos de varios 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 discretización (conocida en la API como clave de agregación) que definas. Tu llamada al histograma acumula valores y devuelve un resultado agregado con ruido en forma de un informe de resumen. Por ejemplo, el informe puede mostrar la cantidad de sitios en los que cada usuario vio tu contenido o si se produjo un error en tu secuencia de comandos de terceros. Esta operación se realiza dentro del worklet de otra API.

Por ejemplo, si antes registraste datos demográficos y geográficos en Shared Storage, 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 agregar datos para esta medición, puedes codificar la dimensión de geografía en la clave de agregación y contar los usuarios en el valor agregable.

Conceptos clave

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 agregables se envían a tu servidor para su recopilación y procesamiento por lotes. El Servicio de agregación procesa los informes por lotes más adelante y se genera 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 Attribution Reporting

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 en varios sitios junto con APIs como la API de Protected Audience y Shared Storage. Ambas APIs producen informes agregables que el backend del Servicio de agregación consume para generar informes de resumen.

El Informe de atribución asocia 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 en varios sitios.

Probar esta API

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

Obtén más información sobre las pruebas en experiment and participate.

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 genera un informe que se puede agregar y 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 en varios sitios, y está disponible para usarse en worklets de Shared Storage y la API de Protected Audience. El primer paso es decidir específicamente qué información deseas recopilar. Esos datos son la base de tus claves de agregación.

Con Shared Storage

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

Medición del alcance único

Es posible que desees medir cuántos usuarios únicos vieron tu 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 Shared Storage 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 Private Aggregation y, luego, se establece la marca. En las visitas posteriores del usuario, incluidas las visitas en varios sitios, puedes verificar Shared Storage y omitir el envío de un informe a Private Aggregation si se establece la marca. Para obtener más información sobre los métodos para implementar estas mediciones, consulta nuestro informe de alcance.

Medición de datos demográficos

Es posible que desees medir 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 Shared Storage para acceder a los datos demográficos desde un contexto de terceros. Más adelante, puedes generar un informe con Private Aggregation codificando las dimensiones de grupo etario y país en la clave de agregación.

Medición de la frecuencia superior a 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 preseleccionado de K.

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

Atribución de múltiples puntos de contacto

La atribución de marketing es un método que utilizan los anunciantes para determinar la contribución de las tácticas de marketing y las interacciones posteriores con los anuncios a las ventas o las conversiones.

Con la API de Protected Audience

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

Desde un worklet de la API de Protected Audience, puedes agregar tus datos directamente con contributeToHistogram() y generar informes sobre tus datos 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 la API de Protected Audience y Shared Storage.

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);

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

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 la discretización y el valor dependan de indicadores que aún no están disponibles en ese punto 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 en sí después de que finaliza, como un evento de ganancia o pérdida de la subasta, o puede provenir de un iframe delimitado que renderizó el anuncio.

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

En el siguiente ejemplo, se envía un informe de impresión cuando se activa el evento de victoria de la subasta y se envía un informe de clics si se activa un evento click desde el iframe delimitado 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 sobre los informes de Agregación privada extendida para obtener más información.

enableDebugMode()

Si bien las cookies de terceros seguirán disponibles, proporcionaremos un mecanismo temporal que permitirá depurar y probar con mayor facilidad habilitando el modo de depuración. Un informe de depuración es útil para comparar tus mediciones basadas en cookies con tus mediciones de Private Aggregation y también te permite validar rápidamente la integración de tu API.

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

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

También puedes configurar 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 Private Aggregation.

Solo se pueden llamar una vez por contexto. Las llamadas posteriores generará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 permite la medición en varios sitios y, al mismo tiempo, protege la privacidad del usuario. Sin embargo, los agentes maliciosos pueden intentar manipular la precisión 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 se contribuye a los resultados agregados finales. Esto se logra de la siguiente manera:

• Evita los informes ilegítimos o no auténticos: Verifica 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 para los actores maliciosos.
• Evitar la reproducción de informes: Detecta y rechaza cualquier intento de reutilizar informes antiguos, lo que garantiza que cada informe se incluya solo una vez en los resultados agregados.

Shared Storage

Cuando usas Shared Storage para ejecutar una operación que puede enviar un informe agregable, puedes establecer un ID impredecible fuera del worklet.

Este ID está incorporado en el informe creado a partir del 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'
  }
});

Después de configurar este ID, puedes usarlo para verificar que el informe se envió desde tu operación de Shared Storage. Para evitar la filtración de información, se envía exactamente un informe por operación de Shared Storage (incluso si no se realizan contribuciones), independientemente de la cantidad de llamadas a contributeToHistogram().

La API de Private Aggregation envía informes que se pueden agregar con un retraso aleatorio de hasta una hora. Sin embargo, establecer un ID de contexto para verificar un informe reduce esta demora. En este caso, hay una demora fija y más corta de 5 segundos desde que se inicia la operación de Shared Storage.

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

1. La operación de Shared Storage se ejecuta con una configuración de Private Aggregation que especifica un ID de contexto y se genera un informe agregable.
2. El ID de contexto está incorporado 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 de cada informe agregable comparándolo con los IDs de contexto almacenados para verificar 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 varias maneras antes de enviarse al Servicio de agregación. Se pueden rechazar los informes con IDs de contexto no válidos en los siguientes casos:

• Desconocido: Si llega un informe con un ID de contexto que tu sistema no creó, puedes descartarlo. Esto evita que agentes 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 los informes descartar.
• Se marcó en la detección de spam:
  • Si detectas actividad sospechosa de un usuario, por ejemplo, un cambio repentino en su actividad, mientras procesas su denuncia, puedes descartarla.
  • Puedes almacenar informes junto con sus IDs de contexto y cualquier indicador pertinente (por ejemplo, el agente de usuario, la fuente de referencia, etcétera). Más adelante, a medida que analices el comportamiento de los usuarios y detectes nuevos indicadores de spam, podrás volver a evaluar los informes almacenados según sus IDs y sus indicadores de contexto 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 se encuentra en debate activo 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 a los 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 conocer los anuncios más recientes relacionados con Private Aggregation.