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 ofrecer las funciones esenciales de las que depende la Web, la Private Aggregation La API se creó para agregar datos entre sitios y generar informes sobre ellos en un que preservan 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 entre los usuarios de cada bucket (lo que en la API se conoce como una clave de agregación) que definas. Tu llamada al histograma acumula valores y muestra un resultado agregado con ruido en como un informe resumido. Por ejemplo, el informe podría mostrar la cantidad de sitios en los que los usuarios vieron tu contenido o se encontraron con un error en la 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 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 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.

Cómo 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 no existe la marca, se llama a Private Aggregation 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. Si deseas 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.

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+

Te recomendamos que midas 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 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.

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 la 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 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 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 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 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 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.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 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 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 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 subasta ganadora 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 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 con permiso de acceso cookies de terceros. Si el emisor no tiene acceso a cookies de terceros enableDebugMode() fallará de manera silenciosa. Esto significa que, cuando un tercero las cookies dejaron de estar disponibles; 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

En el caso del almacenamiento compartido, puedes verificar que los informes agregables que recibiste sean legítimos agregando un ID de contexto a la llamada de operación de almacenamiento compartido. 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.

Para obtener más información, consulta la explicación de 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.

• GitHub: Lee la explicación, plantea preguntas y participa en los debates.
• Asistencia para desarrolladores: Haga preguntas y participe en 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.