Generar informes de datos agregados con datos de Protected Audience y datos de varios sitios del almacenamiento compartido
Para proporcionar las funciones esenciales en las que se basa la Web, la API de Private Aggregation se creó para agregar datos entre sitios y generar informes sobre ellos de una manera que preserva la privacidad.
Estado de implementación
| Propuesta | Estado |
|---|---|
| Evitar los informes no válidos de la API de Private Aggregation con la verificación de informes para el almacenamiento compartido Explainer |
Disponible en Chrome |
| La disponibilidad del modo de depuración de agregación privada depende de la elegibilidad de 3PC Problema de GitHub |
Disponible en Chrome M119 |
| Reduce la demora en los informes Explicación |
Disponible en Chrome M119 |
| Compatibilidad con la API de Private Aggregation y el Servicio de agregación de Google Cloud Explainer |
Disponible en Chrome M121 |
| Relleno para cargas útiles de informes agregables Explicación |
Disponible en Chrome M119 |
| Modo de depuración de agregación privada disponible para los informes de AuctionReportBuyers Explicación |
Se espera en Chrome M123 |
| Filtrado de compatibilidad con IDs Explicación |
El lanzamiento inicial previsto en Chrome se realizará en el segundo trimestre de 2024. |
¿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 de varios sitios del Almacenamiento compartido.
Actualmente, 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 (conocido en la API como una clave de agregación) que definas.
Tu llamada de histograma acumula valores y muestra un resultado agregado con ruido en el formato de un 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 del worklet de otra API.
Por ejemplo, si ya has registrado 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 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 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 agrupación en lotes. El servicio de agregación procesa los informes por lotes y, luego, se genera un informe de resumen.
Consulta el documento Aspectos 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 creó para mediciones entre sitios junto con APIs como la API de Protected Audience y el almacenamiento compartido. Ambas APIs producen informes agregables que el backend del servicio de agregación consume para generar informes de resumen.
Los informes de atribución 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.
Probar esta API
La API de Private Aggregation se puede probar de forma local habilitando la marca de experimento de las APIs de anuncios de Privacy Sandbox en chrome://flags/#privacy-sandbox-ads-apis.
Obtén más información para realizar pruebas en experimentar y participar.
Usar la demostración
Se puede acceder a la demostración de la API de Private Aggregation para almacenamiento compartido en goo.gle/shared-storage-demo; 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.
Más adelante, 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 trabajos de almacenamiento compartido y de 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
El Almacenamiento compartido te permite leer y escribir datos entre sitios en un entorno seguro para evitar filtraciones. Además, la API de agregación privada te permite medir los datos entre sitios almacenados en el almacenamiento compartido.
Medición de alcance único
Te recomendamos medir cuántos usuarios únicos vieron su contenido. La API de Private Aggregation puede proporcionar una respuesta como "Aproximadamente 317 usuarios únicos vieron Content ID 861".
Puede configurar 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 Private Aggregation y, luego, se establece la marca. En visitas posteriores del usuario, incluidas las visitas a otros sitios, puedes consultar el almacenamiento compartido y omitir el envío de un informe a Private Aggregation si la marca está establecida.
Medición de datos demográficos
Te recomendamos que midas los datos demográficos de los usuarios que han visto tu contenido en diferentes sitios.
Private Aggregation puede proporcionar una respuesta, como "Aproximadamente 317 usuarios únicos son de Alemania entre 18 y 45 años". Use el almacenamiento compartido para acceder a datos demográficos desde un contexto de terceros. Más adelante, puedes generar un informe con la 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 contenido o un anuncio al menos K veces en un navegador determinado, para un valor preelegido de K.
Private Aggregation puede proporcionar una respuesta como "Aproximadamente 89 usuarios vieron Content ID 581 al menos 3 veces". En el almacenamiento compartido, se puede aumentar un contador 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 Private Aggregation.
Con la API de Protected Audience
La API de Protected Audience habilita los casos de uso de públicos personalizados y la resegmentación, y Private Aggregation te permite informar eventos de trabajos de compradores y vendedores. La API se puede usar para tareas como medir la distribución de las ofertas de subastas.
Desde un worklet de la API de Protected Audience, puedes agregar tus datos directamente con sendHistogramReport() y, luego, informar tus datos en función de un activador con reportContributionForEvent(), 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 la 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.
A continuación, se muestra un ejemplo de cómo se lo 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 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 Private Aggregation cada vez que se cargue el contenido de 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 dentro de los trabajos 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 misma después de que esta finaliza, como un evento de victoria o pérdida de la subasta, o puede provenir de un marco vallado que renderizó el anuncio.
Para enviar un informe de eventos de subasta, puedes usar 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 Fenced Frames Ads Reporting.
En el siguiente ejemplo, se envía un informe de impresiones cuando se activa el evento de victoria 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 sirven 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 del informe 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 para facilitar la depuración y las pruebas mediante la habilitación del modo de depuración. Un informe de depuración es útil para comparar sus mediciones basadas en cookies con sus mediciones de agregación privada; además, le permite validar rápidamente su integración de 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 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 emisores con permiso para acceder a cookies de terceros. Si el emisor no tiene acceso a cookies de terceros, enableDebugMode() fallará silenciosamente. Esto significa que, cuando las cookies de terceros dejen 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 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 la medición de agregación privada. Se los puede llamar solo una vez por contexto. Se ignorarán las llamadas posteriores.
// Enables debug mode
privateAggregation.enableDebugMode();
// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });
Verificación de informes
Para el almacenamiento compartido, puedes verificar que los informes agregables que recibiste sean legítimos agregando un ID de contexto a la llamada a la 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.
La función está disponible para pruebas 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 de la verificación de denuncias.
Interactúa y comparte comentarios
La API de Private Aggregation se está debatiendo en curso y está sujeta a cambios en el futuro. Si pruebas esta API y tienes comentarios, nos encantaría recibirlos.
- GitHub: Lee la explicación, haz preguntas y participa en debates.
- 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 Private Aggregation.