Descripción general de la API de Private Aggregation

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

Para proporcionar funciones esenciales en las que se basa la Web, la API de Private Aggregation se diseñó para agregar datos entre sitios y generar informes sobre ellos de una manera que preserva la privacidad.

Estado de implementación

Proposal Status
Prevent invalid Private Aggregation API reports with report verification for Shared Storage
Explainer		 Available in Chrome
Private Aggregation debug mode availability dependent on 3PC eligibility
GitHub issue		 Available in Chrome M119
Reducing report delay
Explainer		 Available in Chrome M119
Support for Private Aggregation API and Aggregation Service for Google Cloud
Explainer		 Available in Chrome M121
Padding for aggregatable report payloads
Explainer		 Available in Chrome M119
Private Aggregation debug mode available for auctionReportBuyers reporting
Explainer		 Expected in Chrome M123
Filtering ID support
Explainer		 Initial launch expected in Chrome in Q2 2024.

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 del almacenamiento compartido.

Por el momento, esta API proporciona una operación, sendHistogramReport(), pero es posible que se admitan más en el futuro. La operación de histograma te permite agregar datos de los usuarios en cada bucket (lo que en la API se conoce como una clave de agregación) que definas. Tu llamada de histograma acumula valores y muestra un resultado agregado con ruido en forma de informe de resumen. Por ejemplo, el informe puede 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 un worklet de otra API.

Por ejemplo, si previamente registraste datos demográficos y geográficos en el almacenamiento compartido, puedes usar la API de Private Aggregation para construir un histograma que te indique aproximadamente cuántos usuarios en la ciudad de Nueva York vieron tu contenido entre sitios. Para agregar en 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 Private Aggregation con una clave 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 en lotes 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 conversiones, mientras que Private Aggregation se diseñó para realizar mediciones entre sitios junto con APIs como la API de Protected Audience y el almacenamiento compartido. Ambas APIs producen informes agregables que consume el backend del servicio de agregación para generar informes de resumen.

Attribution Reporting 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 entre sitios.

Probar 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 de experimento y participación.

Usar la demostración

Puedes acceder a la demostración de la API de Private Aggregation para almacenamiento compartido 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 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 Almacenamiento compartido y 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 almacenamiento compartido

El almacenamiento compartido 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 almacenamiento compartido.

Medición de alcance único

Es posible que desees medir 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”.

En el almacenamiento compartido, puedes configurar una marca para indicar si el usuario ya vio el contenido o no. En la primera visita en la que la marca no existe, se llama a la agregación privada y, luego, se configura 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 la marca está configurada.

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.

Private Aggregation puede proporcionar una respuesta como “Aproximadamente 317 usuarios únicos de entre 18 y 45 años son de Alemania”. Use el almacenamiento compartido para acceder a los datos demográficos desde un contexto de terceros. Más adelante, podrás generar un informe con agregación privada codificando las dimensiones de edad y país en la clave de agregación.

Medición de frecuencia K+

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

La agregación privada puede proporcionar una respuesta como “Aproximadamente 89 usuarios vieron el Content ID 581 al menos 3 veces”. Un contador puede aumentarse en el almacenamiento compartido desde diferentes sitios y se puede leer dentro de un worklet. Cuando el recuento llega a K, se puede enviar un informe a través de la agregación privada.

Con la API de Protected Audience

La API de Protected Audience habilita casos de uso de la resegmentación y el público personalizado, y la agregación privada te permite informar eventos de los worklets de compradores y vendedores. La API se puede usar para tareas como medir la distribución de ofertas de subasta.

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

Funciones disponibles

Las siguientes funciones están disponibles en el objeto privateAggregation, disponible en los worklets de almacenamiento compartido y de la API de Protected Audience.

contributeToHistogram()

Puedes llamar a privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }), en el que la clave de agregación es bucket y el valor agregable como 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 la podría llamar en el almacenamiento compartido para la medición de 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 this.sharedStorage.get(key) === 'true';

    // Do not 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 this.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 iframe entre sitios. El código 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 (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.reportContributionForEvent(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 una vez que esta finaliza, como un evento de ganancia o pérdida de una subasta, o puede provenir de un fotograma vallado que renderizó el anuncio. Para enviar un informe de eventos de subasta, puede utilizar dos palabras clave reservadas: reserved.win, reserved.loss y reserved.always. Para enviar un informe activado por un evento desde un marco vallado, define un tipo de evento personalizado. Para activar el evento desde un marco vallado, usa el método fence.reportEvent() disponible en la API de informes de anuncios de marcos vallados.

En el siguiente ejemplo, se envía un informe de impresiones cuando se activa el evento de ganancia de la subasta y un informe de clics si se activa un evento click desde el marco vallado que renderizó el anuncio. Estos dos valores se pueden usar para calcular la tasa 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 el informe de agregación privada extendida para obtener más información.

enableDebugMode()

Si bien las cookies de terceros siguen disponibles, proporcionaremos un mecanismo temporal que facilita 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 Private Aggregation y también te permite validar rápidamente tu integración de API.

Llamar a privateAggregation.enableDebugMode() en el worklet habilita el modo de depuración, que hace que los informes agregables incluyan la carga útil no encriptada (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 emisores que tienen permitido acceder a cookies de terceros. Si el llamador no tiene acceso a las cookies de terceros, enableDebugMode() fallará silenciosamente. Esto significa que, cuando las cookies de terceros se den de baja, el modo de depuración ya no estará disponible.

También puedes configurar la clave de depuración llamando a privateAggregation.enableDebugMode({ <debugKey: debugKey> }), donde se puede usar 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 la medición de agregación privada.

Se pueden llamar solo una vez por contexto. Las llamadas posteriores mostrarán una excepción.

// Enables debug mode
privateAggregation.enableDebugMode();

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

Denunciar verificación

Para el almacenamiento compartido, puedes agregar un ID de contexto a la llamada de operación de almacenamiento compartido para verificar que los informes agregables que recibiste son legítimos. El ID se adjuntará al informe enviado y, más adelante, podrás usarlo para verificar que el informe se haya enviado desde tu operación de almacenamiento compartido.

La función está disponible para probarla en Chrome M114 y versiones posteriores. La verificación de informes para la API de Protected Audience aún no está disponible para pruebas.

Para obtener más información, consulta la explicación sobre la verificación de informes.

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.