Informes de subastas de la API de Protected Audience

Mide los datos de subasta y los resultados de la API de Protected Audience

En este artículo, encontrarás una descripción general de los diversos mecanismos disponibles para informar 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 las soluciones alternativas estén listas.

Para generar informes sobre 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
• La API de Ads Reporting para iframes y marcos vallados, 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 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 subasta.
• Almacenamiento compartido, que te permite escribir indicadores de subasta en un almacenamiento de origen cruzado y, luego, informar esos datos más tarde con la agregación privada.

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

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

Durante la subasta, puedes generar informes de los datos de la subasta con los worklets de informes. Durante el tiempo de renderización, puedes generar informes sobre los datos de participación desde un iframe o un marco vallado. Durante el período de conversión, puedes informar los datos de atribución desde la página de destino mediante la API de Attribution Reporting.

Ubicaciones de los informes

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

Durante cada uno de los períodos enumerados, los compradores y vendedores tendrán acceso a varias APIs de informes disponibles para registrar datos, como indicadores de subastas, 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 informarse 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 disponibles para los compradores y vendedores dentro de un worklet con el objetivo de generar una oferta, calificar un anuncio y registrar los resultados de una subasta.

El objeto auction config es la fuente principal de los datos suministrados para que estén disponibles como indicadores en worklets. El publicador y el vendedor pueden proporcionar datos contextuales y datos de origen en la configuración de la subasta, y estos indicadores pueden enriquecerse con los datos del grupo de interés 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 en informes de compradores y vendedores, facturación, presupuestos, entrenamiento de modelos de AA y mucho más.

Otros datos disponibles

• Datos de los resultados que se relacionan con los datos de subastas ganadas o perdidas, 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 se 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 hay datos disponibles para informarse.

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

Durante el período de conversión, cuando un usuario realiza alguna acción en la página de clics 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 victoria en una subasta, una impresión de anuncios o una conversión. Hasta, al menos, 2026, seguirán vigentes los informes de subastas ganadas a nivel del evento, no se requerirán los marcos vallados para renderizar un anuncio de Protected Audience, y se puede 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 iframes y marcos vallados para que asocies los datos de subastas y de 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 sencilla, ya que puedes seguir usando tu infraestructura de informes existente hasta al menos 2026 mientras migras tu sistema a Protected Audience.

Informes de subastas ganadas 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 una subasta ganada. La función está disponible en los worklets de informes del comprador y el vendedor, y el navegador realiza una solicitud GET a la cadena de URL proporcionada cuando comienza la renderización de anuncios. 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 el 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, al menos, hasta 2026.

Informe de participación

Un informe de participación contiene datos a nivel del evento de una creatividad de anuncio, como los 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 concluye la subasta, los indicadores de subasta no están disponibles dentro del fotograma que renderiza el anuncio. Para asociar estos datos con diferentes períodos, te brindamos dos mecanismos de transición para generar informes de participación.

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

API de Ads Reporting para iframes y marcos vallados

La API de Ads Reporting para iframes y marcos vallados proporciona un mecanismo para asociar 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 pixel 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 los informes. Luego, más adelante, cuando el anuncio se renderice en un marco vallado, puedes activar el evento personalizado llamando a la función window.fence.reportEvent(). Los datos disponibles dentro de la trama vallada se pueden agregar como carga útil.

La función registerAdBeacon() solo está disponible en las funciones de informes, 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 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 2026, como mínimo, por los mismos motivos que los informes de anuncios ganadores.

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

Acceso a la red sin restricciones

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

El acceso a la red se verá limitado en el futuro.

Informe de atribución

Un informe de atribución te permite asociar una conversión de un sitio web con un anuncio que se eligió de una subasta de la API de Protected Audience. Por ejemplo, un usuario puede hacer clic en un anuncio de producto que usted publica, redireccionar al sitio del anunciante, realizar una compra allí y que usted desee 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 conversiones del sitio del anunciante.

Si bien diseñamos una solución más permanente, puedes usar la API de Ads Reporting para los marcos vallados como un mecanismo de transición para generar un informe agregable a nivel del evento con Attribution Reporting. Ten en cuenta que estos informes se utilizan para medir las conversiones y son independientes de los informes de participación a nivel del evento y de participación agregable generados a partir de la subasta y el marco del anuncio. Cuando esté todo listo, publicaremos una explicación para una solución más permanente.

Mecanismo de transición

Al registrar un píxel contador de anuncios, puede utilizar 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 a la baliza que registró, puede llamar a setReportEventDataForAutomaticBeacons() desde el marco vallado 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 marco vallado o iframe 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 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 auctionConfig y estará disponible en los worklets del comprador.
2. Durante el momento de 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 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 búsqueda de la URL del píxel contador.
   2. Para asociar indicadores de subasta para un evento de conversión, establece el auctionId en la URL del píxel contador.
3. Durante el tiempo de renderización de anuncios, los píxeles contadores que registró durante la subasta pueden activarse o mejorarse con datos a nivel del evento.
   1. Activa el evento de marco con reportEvent() y pasa los datos a nivel del evento.
   2. Agregue una carga útil a nivel del evento al píxel contador 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 período 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 juntos en una clave única que se puede usar para asociarse 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 datos de Protected Audience para generar un informe de resumen, que es un informe agregado y ruidoso de los datos recopilados en buckets. Un bucket se representa con una clave de agregación y parte de la información se puede codificar en la clave.

Por ejemplo, un evento de impresión de anuncios se puede registrar en diferentes intervalos, y cada intervalo 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 si 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 agregó ruido para proteger la privacidad del usuario.

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

Agrega indicadores de subasta

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

En este ejemplo, la oferta ganadora se agrega al intervalo de propietarios 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 utilizar 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 generar informes de los indicadores de subasta, consulta la explicación.

Agrega 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 global cuántos clics recibió un anuncio de una campaña. Para ello, crea 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 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 del anuncio para activar el envío del informe.

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 intervalo como la combinación del ID de la campaña y el evento de clic y, luego, aumentar el valor de ese intervalo 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 llamar a reportEvent(eventType) para activar el envío de la denuncia:

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

Cómo informar los resultados y el rendimiento de la subasta

También puedes agregar los resultados de la subasta cuando se activan por un evento de victoria o derrota de una subasta con contributeToHistogramOnEvent(eventType, contribution) si 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 desde la que 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 se calificó como el segundo más alto 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 agregar o restar a ese valor y, luego, informar el valor final. Por ejemplo, si se proporciona la oferta ganadora de USD 5 como valor base, puede restar su oferta de USD 2 para calcular el valor real de USD 3 de cuánto perdió su subasta.

Informes de resultados de la subasta

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

Para saber cuánto perdió 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, cambiado 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 recuperar los indicadores de confianza. Con su permiso, los vendedores pueden recopilar el tiempo de generación de ofertas y el tiempo del indicador de ofertas de confianza de cada comprador.

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

Almacena indicadores de subasta en el almacenamiento compartido

El almacenamiento compartido es un almacenamiento no particionado y de origen cruzado en el que puedes escribir con libertad, pero está protegido por puertas cuando se leen y procesan los valores almacenados. Una de las puertas disponibles para la API de Shared Storage es la de agregación privada. Solo puedes leer los valores en el almacenamiento compartido desde dentro de un worklet, y puedes informar esos valores con la agregación privada desde el worklet.

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

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 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.