Informes de subastas de la API de Protected Audience

Cómo medir 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 los diversos mecanismos disponibles para que informes los datos de la 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:

• Private Aggregation, que recopila indicadores y resultados de la subasta para generar informes de resumen
• API de Ads Reporting para Fenced Frames y elementos iframe, que es un canal dentro de los marcos para comunicarse con los worklets de la API de Protected Audience La API permite asociar datos a nivel del evento con indicadores de la subasta. Los informes a nivel del evento de la API de Ads Reporting son un mecanismo de transición hasta que se diseñe un mecanismo de informes más privado.
• Attribution Reporting, que te permite asociar los datos de conversiones con los indicadores de la subasta
• Shared Storage, que te permite escribir indicadores de la subasta en un almacenamiento de varios orígenes y, luego, te permite informar esos datos con Private Aggregation.

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

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

Durante el tiempo de la subasta, puedes informar los datos de la subasta con worklets de informes. Durante el tiempo de renderización, puedes informar datos de participación desde un iframe o un fenced frame. Durante el tiempo de conversión, puedes registrar los datos de atribución de la página de destino con la API de Attribution Reporting.

Ubicaciones de informes

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

Durante cada uno de los períodos que se indican, los compradores y vendedores tendrán acceso a varias APIs de informes disponibles para informar datos como los indicadores de subasta, los datos a nivel del evento y los datos de conversión.

Datos disponibles en una subasta de la API de Protected Audience

Los siguientes datos están disponibles para generarse informes desde un worklet 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 que están disponibles para los compradores y vendedores dentro de un worklet para generar una oferta, calificar un anuncio y registrar los resultados de una subasta.

El objeto de configuración de la subasta es la principal fuente de datos que se proporciona 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 interés del comprador, los datos a nivel del evento del marco de renderización del anuncio y los datos de atribución de la página de destino. Los datos que se registran se pueden usar para generar informes de compradores y vendedores, facturación, 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 el 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 del iframe o del iframe delimitado se pueden asociar con los datos de la subasta de la API de Protected Audience y se pueden informar a tu servidor. Entre los datos a nivel del evento, se incluyen la impresión del anuncio, el clic, 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 destino 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 la 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 del anuncio o una conversión. Al menos hasta el 2026, se mantendrán los informes de victorias de subastas a nivel del evento, no se requerirán marcos cercados 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 Ads Reporting está disponible en los elementos iframe y los marcos delimitados para que asocies los datos de conversiones y de la subasta con los datos a nivel del evento del marco. Esto está diseñado para que el ecosistema tenga una ruta de migración más sencilla, ya que puedes seguir usando tu infraestructura de informes existente hasta, al menos, el 2026 mientras migras tu sistema a Protected Audience.

Informes de éxito de la subasta a nivel del evento con sendReportTo()

Un mecanismo disponible para informar datos a nivel del evento dentro de una subasta de Protected Audience es el sendReportTo() function en un éxito de subasta. La función está disponible en los worklets de informes del comprador y del vendedor, y el navegador realiza una solicitud de 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 del 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 victorias para el vendedor cuando se llama desde reportResult() y un informe de victorias para el comprador cuando se llama desde reportWin(). La función sendReportTo() estará disponible al menos hasta el 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 se asocian 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 la 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 la subasta con datos a nivel del evento de un iframe, pero no funciona para un fenced frame, ya que no se puede pasar un ID único desde el incorporador porque la comunicación entre el incorporador y el fenced frame es limitada. Para asociar los datos de la subasta con los datos a nivel del evento de un anuncio de iframe delimitado, se puede usar la API de Ads Reporting.

API de Ads Reporting para fenced frames y elementos iframe

La API de Ads Reporting para los iframe y los iframe delimitados 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 un worklet 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 del informe. Luego, en un momento posterior, cuando el anuncio se renderice en un iframe delimitado, puedes activar el evento personalizado llamando a la función window.fence.reportEvent(). Los datos disponibles dentro del iframe 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, se asocia un ID de campaña a una carga útil a nivel del evento con las coordenadas del 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 al menos hasta 2026 por los mismos motivos que los informes de victorias.

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 podrás enviar datos a nivel del evento dentro de los 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 iframe delimitado con los datos de la subasta que se enviaron con sendReportTo(), como se explicó en la sección anterior sobre el mecanismo de informes a nivel del evento de la subasta.

El acceso a la red se restringirá en el futuro.

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, ser redireccionado al sitio del anunciante, realizar una compra allí y tú quieres 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 la 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 Ads Reporting para los marcos delimitados como mecanismo de transición para generar un informe agregable y a nivel del evento con Attribution Reporting. Ten en cuenta que estos informes sirven para medir las conversiones 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 del anuncio. Cuando esté lista, publicaremos una explicación sobre una solución más permanente.

Mecanismo de transición

Cuando registres un baliza de anuncio, puedes usar la palabra clave reserved.top_navigation, que agregará automáticamente el encabezado Attribution-Reporting-Eligible para que la baliza sea apta 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 iframe delimitado 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 del 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 iframe o del iframe delimitado 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 los worklets del comprador.
2. Durante el tiempo de 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. Si deseas asociar indicadores de subasta para un evento de conversión, establece auctionId en la URL del baliza.
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 fotograma con reportEvent() y pasa los datos a nivel del evento.
   2. Agrega una carga útil a nivel del evento al beacon de atribución con setReportEventDataForAutomaticBeacons()
   3. Registra el anuncio con la API de Attribution Reporting respondiendo 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 el tiempo de 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 asociarlos 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 iframe, 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.

Cómo agregar 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 ruidoso y agregado 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 anuncio se puede incluir en diferentes buckets, en los que cada uno representa una campaña publicitaria diferente. Un informe de resumen se diferencia 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 sobre la 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 el worklet de ofertas del comprador, el worklet de puntuación del vendedor y los worklets de informes del comprador y el vendedor.

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

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 ni 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 la 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 creando un bucket que represente esa campaña y el evento de clic. Ten en cuenta que, desde el marco del anuncio, puedes especificar qué evento ocurrió, pero no puedes adjuntar una carga útil a nivel del evento.

Para agregar los indicadores de la 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 del anuncio para activar el envío del informe.

Supongamos que deseas medir la cantidad de clics que 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 active el evento.

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

Luego, más adelante, desde el marco del anuncio, puedes activar el envío del informe llamando a reportEvent(eventType):

Obtén más información para activar contribuciones de Private Aggregation desde un fotograma en el explicador.

Informes sobre los resultados y el rendimiento de la subasta

También puedes agregar los resultados de la subasta cuando se activa un evento de victoria o derrota en la subasta con contributeToHistogramOnEvent(eventType, contribution) cuando pasas palabras clave de tipo de evento reservado (reserved.win, reserved.loss y reserved.always).

La Agregación privada proporciona una lista de valores base a partir de la cual 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 algún valor base, como el importe de la oferta ganadora, puedes establecer cuánto sumar o restar de 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 la subasta

Veamos un ejemplo en el que perdiste una subasta y quieres saber qué tan lejos estuvo tu oferta del precio de cierre de la subasta.

Para saber por cuánto perdiste la subasta, puedes restar el precio de tu oferta al 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 valor de baseValue ajustado, desplazado 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 la oferta y el tiempo del indicador de ofertas de confianza de cada comprador con su permiso.

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

Almacena indicadores de subasta en Shared Storage

El almacenamiento compartido es un almacenamiento sin particiones y de origen cruzado en el que puedes escribir libremente, pero que está protegido con puertas cuando lees y procesas los valores almacenados. Una de las puertas disponibles para la API de Shared Storage es Private Aggregation. Solo puedes leer los valores del almacenamiento compartido desde un worklet, y puedes informar esos valores con la Agregación privada desde el worklet.

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

Desde un worklet 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 un worklet de Shared Storage 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 Shared Storage, consulta la sección de Shared Storage de la guía para desarrolladores de informes de la API de Protected Audience, el explicador, 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.