Se usó la API de Cloud Translation para traducir esta página.

Informes de subastas de la API de Protected Audience

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 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 que puedes usar durante la migración hasta que estén listas soluciones alternativas.

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 la subasta para generar informes de resumen.
API de Ads Reporting para iframes y marcos protegidos, que es un canal dentro de los fotogramas 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 transitorio hasta que se diseña un mecanismo de generación de informes más privado.
Los informes de atribución, que te permiten asociar los datos de conversiones con los indicadores de subastas
Almacenamiento compartido, que le permite escribir indicadores de subasta en un almacenamiento de origen cruzado y, luego, informar sobre esos datos mediante la agregación privada.

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

Flujo de trabajo general de Protected Audience

Existen 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 momento 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 momento de conversión cuando el usuario realiza alguna acción en el otro sitio que se puede atribuir a la subasta.

Durante el momento de la subasta, puedes crear informes sobre los datos de la subasta mediante trabajos de informes. Durante el tiempo de renderización, puedes informar los datos de participación desde un iframe o un marco vallado. Durante el horario de conversión, puedes informar los datos de atribución desde la página de destino mediante la API de Attribution Reporting.

Ubicaciones de informes

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

Período	Destino	Location	Los datos están disponibles	APIs de informes disponibles
Subasta	Comprador	`generateBid()`	Indicadores, resultados y rendimiento de la subasta	API de Private Aggregation
	Comprador	`reportWin()`		API de Private Aggregation API de Ads Reporting
	Vendedor	`scoreAd()`		API de Private Aggregation
	Vendedor	`reportResult()`		API de Private Aggregation API de Ads Reporting
Renderizar	Comprador / Vendedor	Marco en el sitio del publicador	Datos a nivel del evento dentro del marco del anuncio	API de Private Aggregation API de Ads Reporting
Conversión	Comprador / Vendedor	Sitio de conversiones	Datos a nivel del evento y de las conversiones del sitio de conversión	API de Attribution Reporting API de Private Aggregation API de Ads Reporting

Durante cada uno de los períodos indicados, los compradores y vendedores tendrán acceso a varias APIs de informes disponibles para registrar datos como los 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 informarlos 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 para generar una oferta, calificar un anuncio y, también, informar los resultados de una subasta.

Señal	Descripción	Establecer ubicación	Usuarios	Disponibilidad
auctionSignals	Datos disponibles en el contexto del lugar donde se realiza la subasta. Estos datos pueden incluir información sobre el contenido de la página, datos de origen del usuario y mucho más.	Es lo que establece el vendedor desde el sitio del publicador en la configuración de la subasta.	Comprador Vendedor	generateBid scoreAd reportWin reportResult
directFromSellerSignals	Se utilizan los mismos datos para `auctionSignals`, `perBuyerSignals` y `sellerSignals`, pero se garantiza que los indicadores provienen del vendedor especificado.	Establecido a través de encabezados de respuesta HTTP del vendedor	Comprador Vendedor	generateBid scoreAd reportWin reportResult
browserSignals	Varios datos proporcionados por el navegador (`topWindowHostname`, `interestGroupOwner`, `renderUrl`, `adComponents`, `biddingDurationMsec`, `IGJoinCount`, `IGRecency`, `modelingSignals`)	Establecido por el navegador.	Comprador Vendedor	generateBid scoreAd reportWin reportResult
sellerSignals	Son los indicadores que se proporcionan al vendedor para la puntuación de anuncios.	Es lo que establece el vendedor desde el sitio del publicador en la configuración de la subasta.	Vendedor	puntuaciónAd reportWin reportResult
trustedScoringSignals	Son indicadores en tiempo real que se proporcionan al vendedor para la puntuación de anuncios.	El vendedor establece la URL en el sitio del publicador en la configuración de la subasta.	Vendedor	ScoreAd reportResult
perBuyerSignals	Son datos contextuales de la subasta proporcionados a compradores específicos. El vendedor puede recuperar los valores de los compradores antes de que comience la subasta. Es el conocimiento del comprador sobre la oportunidad del anuncio.	Es lo que establece el vendedor desde el sitio del publicador en la configuración de la subasta.	Comprador	generateBid scoreAd reportWin reportResult
trustedBiddingSignals	Son indicadores en tiempo real que se proporcionan a los compradores para las ofertas de anuncios.	El comprador establece la URL desde el sitio del anunciante cuando se establece el grupo de interés.	Comprador	generateBid
userBiddingSignals	Datos del usuario proporcionados por el comprador.	Establecido por el comprador desde el sitio del anunciante cuando se establece el grupo de interés .	Comprador	generateBid

El objeto de configuración de subasta es la fuente principal de datos suministrados para estar disponibles como indicadores en los worklets. El publicador y el vendedor pueden proporcionar datos contextuales y 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 de anuncios y los datos de atribución de la página de clics. Los datos informados se pueden usar para la generación de informes de compradores y vendedores, la facturación, la creación de presupuestos, el entrenamiento de modelos de AA y mucho más.

Otros datos disponibles

Son datos de los resultados relacionados con las pérdidas o ganancias de una subasta, como el precio de la oferta ganadora y el motivo del rechazo.
Datos de rendimiento que contengan 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 los datos están disponibles para informarse.

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 vallado se pueden asociar con los datos de subasta de la API de Protected Audience y, luego, informarse a tu servidor. Los ejemplos de datos a nivel del evento incluyen impresiones de anuncios, clics, 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 proporcionan información detallada de uno o más eventos. Un evento puede ser el resultado de una subasta, una impresión de anuncios o una conversión. Hasta al menos 2026, se mantendrán los informes de victorias de subasta a nivel del evento, no se requerirán los marcos vallados para renderizar un anuncio de Protected Audience, y se podrá usar un iframe con acceso a la red ilimitado 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 conversiones con los datos a nivel del evento del marco. Esto se diseñó para permitir que el ecosistema tenga una ruta de migración más sencilla, ya que podrás seguir usando tu infraestructura de informes existente hasta al menos 2026 mientras migras tu sistema a Protected Audience.

Informes de ventas de subastas 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 de una subasta ganada. La función está disponible en los trabajos de informes de compradores y vendedores, y el navegador envía 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 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 éxito para el vendedor cuando se llama desde reportResult() y un informe de éxito para el comprador cuando se llama desde reportWin(). La función sendReportTo() estará disponible hasta 2026 como mínimo.

Informe de participación

Un informe de participación contiene datos a nivel del evento de una creatividad del 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 una vez concluida la subasta, los indicadores de la subasta no están disponibles dentro del fotograma 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 de un iframe, pero no funciona para un marco vallado, ya que no se puede pasar un ID único desde el incorporado porque la comunicación entre este y el marco vallado es limitada. Para asociar datos de subastas 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 que te permite asociar 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 de informes. Más adelante, cuando el anuncio se renderice en un marco vallado, podrás activar el evento personalizado llamando a la función window.fence.reportEvent(). Los datos disponibles dentro del marco vallado se pueden agregar como carga útil.

La función registerAdBeacon() solo está disponible en las funciones de informes y no lo está 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 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 hasta, al menos, 2026 por los mismos motivos que para los informes de ganancias.

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

Acceso a la red sin restricciones

Los marcos vallados 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 marcos vallados a tu servidor. Más adelante, puedes generar informes a nivel del evento del servidor si asocias los datos a nivel del evento de un marco vallado con los datos de la subasta que se enviaron con sendReportTo(), los cuales se analizaron en la sección anterior mecanismo de informes a nivel del evento de la subasta.

El acceso a la red se verá limitado en algún momento después de que las cookies de terceros dejen de estar disponibles.

Los mecanismos de informes a nivel del evento que existen actualmente en la API de Protected Audience son mecanismos de transición, y se diseñará una solución alternativa para respaldar mejor los casos de uso existentes.

Informe de atribución

Un informe de atribución te permite asociar una conversión en un sitio web con un anuncio seleccionado de una subasta de la API de Protected Audience. Por ejemplo, un usuario puede hacer clic en un anuncio de producto que usted publica, que se lo redirecciona al sitio del anunciante, realiza una compra allí y le 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 subastas 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 fotogramas vallados como mecanismo de transición para generar un informe agregable y 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 agregables y a nivel del evento que se generan a partir de la subasta y el marco del anuncio. Publicaremos una explicación de una solución más permanente cuando esté todo listo.

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 registraste, puedes 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 de 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 entre sí.

Flujo de trabajo:

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 auctionConfig y estará disponible en los trabajos del comprador.
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 del anuncio, establece auctionId como un parámetro de búsqueda de la URL del píxel contador.
2. Si deseas asociar indicadores de subasta para un evento de conversión, establece el auctionId en la URL del píxel contador.
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 marco 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. 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.
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 vinculados por 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 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 contar en diferentes intervalos, y cada intervalo 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 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 su privacidad.

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

Agrega indicadores de subasta

Puedes agregar los indicadores disponibles dentro de los worklets a tu servidor mediante 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, en el worklet de puntuación del vendedor y en los trabajos de informes del comprador y 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)
  });
}

Se trata del 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 mediante 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 del anuncio. Por ejemplo, puedes medir de forma agregada la cantidad de clics que recibió un anuncio para 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 la cantidad de clics que recibió un anuncio para 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 en 1 el valor de ese bucket 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 del informe:

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

Informes del rendimiento y los resultados de la subasta

También puedes agregar los resultados de la subasta cuando se activa por un evento de victoria o pérdida de la subasta con contributeToHistogramOnEvent(eventType, contribution) si pasas una palabra clave de tipo de evento reservado (reserved.win, reserved.loss y reserved.always).

Private Aggregation 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 algún valor base, como el importe de la oferta ganadora, puedes establecer cuánto quieres sumar o restar de ese valor y, luego, informar el valor final. Por ejemplo, si se proporciona la oferta ganadora de USD 5 como valor base, puedes restar tu oferta de USD 2 para calcular el valor real de USD 3 de cuánto perdiste tu subasta.

Informes de resultados de subastas

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

Para obtener información sobre cuánto perdió 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 registrado será el valor de baseValue ajustado y 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 cuánto tardó en recuperar los indicadores de confianza. Los vendedores pueden recopilar la hora de generación de ofertas y la hora del indicador de ofertas confiable de cada comprador con su permiso.

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

Almacena indicadores de subastas en el almacenamiento compartido

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

También puedes escribir en el almacenamiento compartido desde trabajos de generación 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 usando 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 Private Aggregation:

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