Informes de subastas de la API de Protected Audience

bookmark_border Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Mide los datos y los resultados de las subastas de la API de Protected Audience

En este artículo, encontrarás una descripción general de alto nivel de los diversos mecanismos disponibles para informar los datos de subasta de la API de Protected Audience a tu servidor, junto con los mecanismos de transición disponibles en este momento para que los uses durante la migración hasta que estén listas las soluciones alternativas.

Para generar informes sobre las métricas importantes que recopilas de una subasta de anuncios, la API de Protected Audience funciona con lo siguiente:

• Agregación privada, que recopila indicadores y resultados de subastas para generar informes de resumen.
• API de Ads Reporting para marcos delimitados y marcos de iframe, que es un canal dentro de los marcos para comunicarse con las worklets de la API de Protected Audience. La API permite asociar datos a nivel del evento con indicadores de subasta. Los informes a nivel del evento de la API de Google Ads Reporting son un mecanismo de transición hasta que se diseñe un mecanismo de informes más privado.
• Informes de atribución, que te permiten asociar los datos de conversiones con los indicadores de subasta
• Almacenamiento compartido, que te permite escribir indicadores de subasta en un almacenamiento de varios orígenes y, luego, informar esos datos más adelante con la agregación privada.

Descripción general de los informes de la API de Protected Audience

Existen tres períodos principales en los que los datos del flujo de subasta de la API de Protected Audience se pueden informar a tu servidor: el tiempo de subasta, cuando la subasta se ejecuta desde el sitio del publicador, el tiempo de renderización, cuando el anuncio se renderiza en un marco protegido o un iframe en el sitio del publicador, y el tiempo de conversión, cuando el usuario realiza alguna acción en otro sitio que se puede atribuir a la subasta.

Durante la subasta, puedes informar los datos de la subasta con las tareas de informes. Durante el tiempo de renderización, puedes informar datos de participación desde un iframe o un marco protegido. Durante el tiempo de conversión, puedes informar datos de atribución desde la página de destino con la API de Attribution Reporting.

Cómo denunciar ubicaciones

Dentro de una subasta, los compradores pueden informar los indicadores disponibles en los worklets generateBid() y reportWin(), y los vendedores pueden informar los indicadores disponibles en scoreAd() y reportResult(). Fuera de una subasta, los compradores y vendedores pueden informar datos de un marco que renderizó el anuncio y del sitio desde el que se realizó la conversión.

Durante cada uno de los períodos indicados, los compradores y vendedores tendrán acceso a varias APIs de informes disponibles para generar informes de datos, como indicadores de subasta, datos a nivel del evento y datos de conversiones.

Datos disponibles en una subasta de la API de Protected Audience

Los siguientes datos están disponibles para generar informes desde una tarea de la API de Protected Audience durante la subasta.

Indicadores

Los indicadores son los datos contextuales de la subasta, los datos del usuario, los datos en tiempo real y los datos del navegador disponibles para los compradores y vendedores dentro de una tarea para generar una oferta, calificar un anuncio y generar informes sobre los resultados de una subasta.

El objeto auction config es la fuente principal de datos que se proporcionan para que estén disponibles como indicadores en los worklets. El publicador y el vendedor pueden proporcionar datos contextuales y datos de origen en la configuración de la subasta, y estos indicadores se pueden enriquecer con los datos del grupo de intereses del comprador, los datos a nivel del evento del marco de renderización de anuncios y los datos de atribución de la página de clics. Los datos informados se pueden usar para informes de compradores o vendedores, facturación, elaboración de presupuestos, entrenamiento de modelos de AA y mucho más.

Otros datos disponibles

• Datos de resultados relacionados con los datos de adjudicación y pérdida de subastas, como el precio de la oferta ganadora y el motivo del rechazo de la oferta.
• Datos de rendimiento que contienen información de latencia, como el tiempo que tardó en recuperar y ejecutar la worklet de ofertas.

Datos disponibles fuera de una subasta de la API de Protected Audience

Fuera de una subasta de la API de Protected Audience, hay dos períodos en los que los datos están disponibles para generar informes.

Durante el tiempo de renderización, cuando el anuncio se renderiza en el sitio del publicador, los datos a nivel del evento dentro del iframe o el marco protegido se pueden asociar con los datos de subasta de la API de Protected Audience y se pueden informar a tu servidor. Algunos ejemplos de datos a nivel del evento incluyen la impresión de anuncios, los clics, el desplazamiento del cursor y cualquier otro evento que ocurra dentro del marco.

Durante el tiempo de conversión, cuando un usuario realiza alguna acción en la página de clic que se atribuye a la subasta, los datos a nivel del evento de la página de conversión se pueden asociar con los datos de subasta de la API de Protected Audience y se pueden informar a tu servidor.

Informes a nivel del evento

Los informes a nivel del evento detallan la información de uno o más eventos. Un evento puede ser una ganancia de subasta, una impresión de anuncio o una conversión. Hasta, al menos, 2026, los informes de anuncios ganadores de subastas a nivel del evento permanecerán vigentes, no se requerirán marcos delimitados para renderizar un anuncio de Protected Audience y se podrá usar un iframe con acceso a la red sin restricciones para los informes a nivel del evento. Además, la API de Google Ads Reporting está disponible en marcos delimitados y en iframes para que asocies los datos de subastas y conversiones con los datos a nivel del evento del marco. Esto está diseñado para permitir que el ecosistema tenga una ruta de migración más fácil, ya que puedes seguir usando tu infraestructura de informes existente hasta, al menos, 2026 mientras migras tu sistema a Protected Audience.

Informes de éxito en subastas a nivel del evento con sendReportTo()

Un mecanismo disponible para generar informes de datos a nivel del evento dentro de una subasta de Protected Audience es el sendReportTo() function en una subasta ganadora. La función está disponible en los worklets de informes del comprador y del vendedor, y el navegador realiza una solicitud GET a la cadena de URL proporcionada cuando comienza la renderización del anuncio. Puedes codificar cualquier indicador disponible en tus worklets como parámetros de consulta de la URL.

Por ejemplo, un comprador puede informar el importe de la oferta ganadora desde la worklet reportWin() para fines de facturación:

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

La función sendReportTo() se puede usar para generar un informe de ganancias para el vendedor cuando se llama desde reportResult() y un informe de ganancias para el comprador cuando se llama desde reportWin(). La función sendReportTo() estará disponible hasta, al menos, 2026.

Informe de participación

Un informe de participación contiene datos a nivel del evento de una creatividad del anuncio, como datos de impresiones o clics, que están asociados con los indicadores de la subasta de la API de Protected Audience que renderizó el anuncio. Dado que el anuncio se renderiza después de que finaliza la subasta, los indicadores de subasta no están disponibles dentro del marco que renderiza el anuncio. Para asociar estos datos de diferentes períodos, te proporcionamos dos mecanismos de transición para generar informes de participación.

La función sendReportTo() descrita anteriormente se puede usar para asociar datos de subasta con datos a nivel del evento desde un iframe, pero no funciona para un marco protegido, ya que no se puede pasar un ID único desde el incorporador porque la comunicación entre el incorporador y el marco protegido es limitada. Para asociar datos de subasta con datos a nivel del evento de un anuncio de marco protegido, se puede usar la API de Google Ads Reporting.

API de Reporting de Google Ads para marcos delimitados y marcos de iframe

La API de Attribution Reporting para marcos de contenido protegido y marcos de iframes proporciona un mecanismo para que asocies los datos a nivel del evento del usuario de un marco de anuncio con indicadores dentro de una subasta de Protected Audience.

En una tarea de informes de la API de Protected Audience, puedes registrar un píxel contador de anuncios con la función registerAdBeacon() y pasar tu URL de informes con los indicadores agregados como parámetros de consulta. También debes especificar el evento personalizado que deseas asociar con la URL de informes. Luego, más adelante, cuando el anuncio se renderice en un marco cercado, puedes activar el evento personalizado llamando a la función window.fence.reportEvent(). Los datos disponibles dentro del marco delimitado se pueden agregar como carga útil.

La función registerAdBeacon() solo está disponible en las funciones de informes y no en la lógica de ofertas del comprador ni en la lógica de puntuación del vendedor.

En el siguiente ejemplo, un ID de campaña está asociado con una carga útil a nivel del evento con las coordenadas de clic:

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

La API de Fenced Frames Ads Reporting también estará disponible hasta, al menos, 2026 por los mismos motivos que los informes de ganancias.

Para obtener más información, consulta la explicación.

Acceso a la red sin restricciones

Los marcos delimitados permitirán cargar recursos de red de la misma manera que lo haría un iframe, y puedes enviar datos a nivel del evento dentro de marcos delimitados a tu servidor. Más adelante, puedes generar informes a nivel del evento en el servidor asociando los datos a nivel del evento de un marco delimitado con los datos de subasta que se enviaron con sendReportTo(), que se analizaron en la sección anterior Mecanismo de informes a nivel del evento de subasta.

En el futuro, se restringirá el acceso a la red.

Informe de atribución

Un informe de atribución te permite asociar una conversión en un sitio web con un anuncio que se eligió en una subasta de la API de Protected Audience. Por ejemplo, un usuario puede hacer clic en un anuncio de producto que publicas, redireccionarse al sitio del anunciante, realizar una compra allí y te interesa atribuir la compra al anuncio que se mostró. La API de Attribution Reporting se integrará con la API de Protected Audience para combinar los datos de subasta del sitio del publicador y los datos de conversión del sitio del anunciante.

Mientras diseñamos una solución más permanente, puedes usar la API de Google Ads Reporting para marcos delimitados como mecanismo de transición para generar un informe a nivel del evento y agregable con Attribution Reporting. Ten en cuenta que estos informes son para medir la conversión y son independientes de los informes de participación agregables y a nivel del evento que se generan a partir de la subasta y el marco de anuncios. Publicaremos una explicación de una solución más permanente cuando esté lista.

Mecanismo de transición

Cuando registres un píxel contador de anuncios, puedes usar la palabra clave reserved.top_navigation, que agregará automáticamente el encabezado Attribution-Reporting-Eligible para que el píxel contador sea apto para registrarse como fuente de atribución.

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

Para adjuntar datos a nivel del evento al píxel contador que registraste, puedes llamar a setReportEventDataForAutomaticBeacons() desde el marco cercado con la carga útil del evento.

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

Consulta la sección Attribution Reporting de la explicación de la API de Ads Reporting para obtener más información.

Ejemplo de informes de participación y conversiones

En este ejemplo, los analizaremos desde la perspectiva del comprador a quien le interesa asociar los datos de la subasta, el marco de anuncio y el sitio de conversión.

En este flujo de trabajo, el comprador coordina con el vendedor para enviar un ID único a la subasta. Durante la subasta, el comprador envía este ID único con los datos de la subasta. Durante el período de renderización y de conversión, los datos del marco o iframe cercado también se envían con el mismo ID único. Más adelante, se puede usar el ID único para asociar estos informes.

Flujo de trabajo:

1. Antes de que comience la subasta, el comprador envía un ID único al vendedor como parte de su respuesta de oferta programática de la licitación en tiempo real ("RTB"). El ID se puede establecer como una variable, por ejemplo, auctionId. El ID se pasa como perBuyerSignals en el objeto auctionConfig y estará disponible en las worklets del comprador.
2. Durante la subasta, el comprador puede registrar un píxel contador de anuncios para que se active durante el tiempo de renderización de anuncios y el tiempo de conversión (registerAdBeacon()).
   1. Si deseas asociar indicadores de subasta para un evento de marco de anuncio, establece auctionId como un parámetro de consulta de la URL del píxel contador.
   2. Para asociar indicadores de subasta para un evento de conversión, establece auctionId en la URL del píxel contador.
3. Durante el tiempo de renderización de anuncios, los píxeles contadores que registraste durante la subasta se pueden activar o mejorar con datos a nivel del evento.
   1. Activa el evento de fotogramas con reportEvent() y pasa los datos a nivel del evento.
   2. Agrega una carga útil a nivel del evento al píxel contador de atribución con setReportEventDataForAutomaticBeacons()
   3. Para registrar el anuncio con la API de Attribution Reporting, responde las solicitudes del píxel contador de anuncios con el encabezado Attribution-Reporting-Register-Source.
4. Durante el tiempo de conversión, puedes activar la fuente que registraste durante la subasta.

Después del proceso anterior, el comprador tendrá un informe de subasta, un informe de participación y un informe de conversiones, todos vinculados por una sola clave única que se puede usar para que se asocien entre sí.

Un flujo de trabajo similar se aplica a un vendedor si necesita acceder a los datos de atribución, y el vendedor también puede usar un ID único para enviar con registerAdBeacon(). Desde el marco, la llamada a reportEvent() contiene una propiedad de destino que se puede usar para enviar el informe al comprador y al vendedor. Ten en cuenta que la SSP también debe estar presente en la página de destino para que el activador se atribuya a la fuente.

Agrega datos de Protected Audience

La API de Private Aggregation es el mecanismo que se usa para informar los datos de Protected Audience y generar un informe de resumen, que es un informe agregado y con ruido de los datos recopilados en buckets. Un bucket se representa con una clave de agregación, y se puede codificar cierta información en la clave.

Por ejemplo, un evento de impresión de anuncios se puede registrar en diferentes buckets, en los que cada bucket representa una campaña publicitaria diferente. Un informe de resumen difiere de un informe a nivel del evento en que no revela información sobre cada evento individual. Con un informe a nivel del evento, puedes determinar que los usuarios A, B y C vieron la campaña 123. Con los informes de resumen, puedes medir la cantidad de usuarios que vieron la campaña 123 y se agrega ruido para proteger la privacidad del usuario.

Consulta el artículo Agregación privada para obtener más información sobre la API.

Cómo agregar indicadores de subasta

Puedes agregar los indicadores disponibles en los worklets a tu servidor con la agregación privada. Para la agregación de indicadores, puedes usar el método privateAggregation.contributeToHistogram() disponible en la tarea de trabajo de ofertas del comprador, la tarea de trabajo de puntuación del vendedor y las tareas de trabajo de informes del comprador o del vendedor.

En este ejemplo, la oferta ganadora se agrega al bucket del propietario del grupo de intereses:

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
} 

Este es el mecanismo general que se debe usar cuando los indicadores que deseas agregar no están asociados con datos a nivel del evento y no se activan por un evento fuera de la subasta. Para obtener más información sobre cómo informar los indicadores de subasta, consulta la explicación.

Cómo agregar indicadores de subasta con datos de eventos

Puedes agregar indicadores de subasta con información limitada sobre un evento que ocurre en un marco de anuncio. Por ejemplo, puedes medir de forma agregada cuántos clics recibió un anuncio de una campaña si creas un bucket que represente esa campaña y el evento de clic. Ten en cuenta que, desde el marco de anuncio, puedes especificar qué evento ocurrió, pero no puedes adjuntar una carga útil a nivel del evento.

Para agregar indicadores de subasta por eventos, puedes usar privateAggregation.contributeToHistogramOnEvent(eventType, contribution), que toma una cadena que especifica el tipo de evento y la contribución que se informará cuando se active ese evento. Puedes llamar al método con un tipo de evento personalizado y, luego, llamar a window.fence.reportEvent(eventType) desde el marco de anuncio para activar el informe que se enviará.

Supongamos que deseas medir cuántos clics recibió un anuncio de una campaña.

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

En la función de generación de ofertas, puedes definir un bucket como la combinación del ID de la campaña y el evento de clic y, luego, aumentar el valor de ese bucket en 1 cada vez que se activa el evento.

// Ad frame
window.fence.reportEvent('click');

Luego, más adelante, desde el marco de anuncios, puedes llamar a reportEvent(eventType) para activar el envío del informe:

Obtén más información sobre cómo activar las contribuciones de agregación privada desde un marco en la explicación.

Informes de resultados y rendimiento de la subasta

También puedes agregar los resultados de la subasta cuando se activan con un evento de ganancia o pérdida de la subasta con contributeToHistogramOnEvent(eventType, contribution) cuando pasas palabras clave de tipo de evento reservadas (reserved.win, reserved.loss y reserved.always).

La agregación privada proporciona una lista de valores base a partir de los cuales puedes calcular el bucket y el valor de tu contribución. Los valores base disponibles para los resultados de la subasta son el valor de la oferta del anuncio ganador, el valor de la oferta que obtuvo la segunda puntuación más alta y el motivo por el que se rechazó una oferta de la subasta.

Cuando se proporciona un valor base, como el importe de la oferta ganadora, puedes establecer cuánto agregar o restar a ese valor y, luego, informar el valor final. Por ejemplo, si la oferta ganadora de USD 5 se proporciona como el valor base, puedes restar tu oferta de USD 2 para calcular el valor real de USD 3 por el que perdiste la subasta.

Informes de resultados de subastas

Veamos un ejemplo en el que perdiste una subasta y quieres saber qué tan lejos estaba tu oferta del precio de liquidación de la subasta.

Para saber cuánto perdiste la subasta, puedes restar el precio de tu oferta del precio de la oferta ganadora:

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

Cuando se envíe el informe, el valor real informado será el baseValue ajustado que se desplaza por el valor de offset. Para obtener más información, consulta la explicación.

Informes de rendimiento

Los compradores y vendedores pueden informar cuánto tiempo tardó en ejecutarse una secuencia de comandos y cuánto tiempo tardó en recuperar los indicadores de confianza. Los vendedores pueden recopilar el tiempo de generación de ofertas y el tiempo de indicadores de ofertas de confianza de cada comprador con su permiso.

Consulta la explicación para obtener más información.

Almacenamiento de indicadores de subasta en el almacenamiento compartido

El almacenamiento compartido es un almacenamiento sin particiones y de origen cruzado en el que puedes escribir libremente, pero que está protegido con puertas de enlace cuando se leen y procesan los valores almacenados. Una de las puertas de enlace disponibles para la API de Shared Storage es Private Aggregation. Solo puedes leer los valores del almacenamiento compartido desde una worklet y generar informes sobre ellos con la agregación privada desde la worklet.

También puedes escribir en el almacenamiento compartido desde las worklets de informes, puntuación y ofertas de la API de Protected Audience. Más adelante, puedes informar esos valores en el almacenamiento compartido a tu servidor con la agregación privada . También puedes usar los valores almacenados para la operación de selección de URL.

Desde una tarea de la API de Protected Audience, puedes escribir cualquier clave y valor en el almacenamiento compartido:

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

Más adelante, puedes cargar una worklet de almacenamiento compartido para leer y enviar ese valor con la agregación privada:

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

Para obtener más información sobre el almacenamiento compartido, consulta la sección de almacenamiento compartido de la guía para desarrolladores de informes de la API de Protected Audience, la explicación, la demostración en vivo y el código de demostración en GitHub.

¿Qué sigue?

Queremos conversar contigo a fin de asegurarnos de compilar una API que funcione para todos.

Debate sobre la API

Al igual que otras APIs de Privacy Sandbox, esta API se documenta y se analiza públicamente.

Experimenta con la API

Puedes experimentar y participar en las conversaciones sobre la API de Protected Audience.