Ejecuta una subasta basada en el navegador con un solo vendedor

En este documento, encontrarás una descripción general de alto nivel para ejecutar una subasta con datos de Protected Audience para un solo vendedor, como se usa en la iteración actual de la API de Protected Audience. Una subasta con un solo vendedor se puede ejecutar como parte de una subasta más compleja que involucre a varios vendedores. En este caso, la subasta de un solo vendedor se denomina "subasta de componente", que puede proporcionar candidatos a anuncios para la "subasta de nivel superior" en la que participan varios vendedores.

Lee la guía para desarrolladores para conocer el ciclo de vida completo de la API de Protected Audience y consulta la explicación de la API de Protected Audience para obtener un análisis detallado sobre cómo los vendedores ejecutan subastas en el dispositivo.

Seis etapas de una subasta de anuncios de la API de Protected Audience

1. Un usuario visita un sitio que muestra anuncios.
2. El código del vendedor ejecuta navigator.runAdAuction(). Especifica qué espacio publicitario está a la venta y quién puede ofertar. Los vendedores también deben incluir un script que califique cada oferta, scoreAd().
3. El código del comprador invitado se ejecuta para generar una oferta, una URL para una creatividad del anuncio pertinente y otros datos. La secuencia de comandos de ofertas puede consultar datos en tiempo real, como el presupuesto restante de la campaña publicitaria, desde el servicio de clave/valor del comprador.
4. El código del vendedor califica cada oferta y selecciona un ganador. Esta lógica utiliza el valor de la oferta y otros datos para devolver la conveniencia de una oferta. Se rechazan los anuncios que no pueden superar al ganador contextual. El vendedor puede usar su propio servicio de par clave-valor para los datos en tiempo real.
5. El anuncio ganador se devuelve como un valor opaco, que se muestra en un marco delimitado. Ni el vendedor ni el publicador podrán ver este valor.
6. La subasta se informa a los vendedores y a los compradores ganadores.

Se puede realizar una subasta cuando un usuario navega a una página que muestra un anuncio. Las subastas se pueden realizar con anticipación para que la creatividad del anuncio esté lista cuando se muestre el espacio publicitario.

Los vendedores inician la subasta de anuncios, califican los anuncios candidatos con la lógica personalizada proporcionada como una función scoreAd() y son responsables de informar los resultados de la subasta a sí mismos y al comprador ganador. Los vendedores también pueden aplicar las reglas de los publicadores y filtrar la calidad de los anuncios con su función scoreAd().

Un vendedor puede referirse a lo siguiente:

• Publicadores de contenido que actúan por sí mismos para alojar contenido publicitario en su sitio web
• Plataformas de proveedores (SSP), que trabajan con el publicador de anuncios y brindan otros servicios
• Son secuencias de comandos de terceros que actúan en nombre de los publicadores para permitir la participación en subastas de anuncios.

Requisitos previos para ejecutar una subasta

Un vendedor necesita dos funciones de JavaScript definidas para ejecutar una subasta:

• scoreAd(), que califica a un candidato a anuncio
• reportResult(), que se encarga de informar el resultado de la subasta al vendedor

Estas secuencias de comandos deben publicarse desde un solo extremo que sea propiedad del vendedor.

scoreAd()

El vendedor debe definir una función scoreAd() que se publique desde un extremo de su propiedad. El extremo se especifica en la configuración de la subasta como decisionLogicUrl. La función scoreAd() tiene la siguiente firma:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

Los parámetros de scoreAd() son los siguientes:

• adMetaData, que son metadatos arbitrarios sobre la creatividad del anuncio que proporciona el comprador. Este es un objeto serializable en JSON que los vendedores y compradores deberán definir y acordar su estructura.
• bid, que es un valor numérico que representa la oferta.
• auctionConfig, que es la configuración de la subasta que se usa para ejecutarla.
• trustedScoringSignals, que son indicadores que se leen en el momento de la subasta desde el servidor de clave/valor del vendedor. La plataforma usará el renderUrl del anuncio candidato como clave para esta búsqueda.
• browserSignals, que es un objeto construido por el navegador, incluida la información que conoce el navegador y que el script de la subasta del vendedor podría querer verificar.
• directFromSellerSignals es un objeto que puede contener los siguientes campos: ** sellerSignals: Similar a auctionConfig.sellerSignals, pero se pasa con el mecanismo directFromSellerSignals. ** auctionSignals: Es similar a auctionConfig.auctionSignals, pero se pasa con el mecanismo directFromSellerSignals.

A continuación, se muestra un ejemplo de browserSignals. Ten en cuenta que el renderUrl del anuncio candidato está disponible a través de estos indicadores:

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

El vendedor debe definir una función reportResult() que se publique desde un extremo que le pertenezca. El extremo se especifica en la configuración de la subasta como decisionLogicUrl. La función reportResult() tiene la siguiente firma:

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Los parámetros de reportResult() son los siguientes:

• auctionConfig, que es la configuración de la subasta que se usa para ejecutarla.
• browserSignals, que es un objeto construido por el navegador, incluida la información que conoce el navegador y que el script de la subasta del vendedor podría querer verificar. Este es el mismo objeto que se pasó a la función scoreAds().

reportResult() devuelve signalsForWinner, que es un objeto JSON arbitrario que se pasa a la función de informes del comprador ganador. Esto debe incluir toda la información pertinente que el vendedor pueda proporcionar sobre la subasta y que el comprador necesite para sus informes.

Cómo ejecutar una subasta de la API de Protected Audience

Existen cuatro pasos principales que debe seguir un vendedor para ejecutar una subasta. Ten en cuenta que estos pasos suponen que el vendedor tiene un extremo configurado para devolver el código JavaScript requerido que se mencionó anteriormente en esta guía.

1. Configura la subasta. Este paso incluye la creación de un objeto auctionConfig. Esto permite que el vendedor especifique qué compradores deben participar en la subasta, así como proporcionar cualquier indicador que pueda ser relevante durante la generación de ofertas o la puntuación de anuncios.
2. Ejecuta la subasta llamando a navigator.runAdAuction() y pasando la configuración creada en el paso anterior. Esto inicia la cadena de compradores que generan ofertas y, luego, las califican. El resultado final de este paso es un candidato a anuncio que se puede renderizar para mostrar un anuncio.
3. Renderiza el anuncio ganador en un iframe o un fotograma cercado.
4. Informa el resultado de la subasta. Hay una función, navigator.sendReportTo(), que iniciará la generación de informes. El vendedor siempre recibirá un informe de los resultados de la subasta. Solo el comprador que ganó la subasta recibirá un informe. Esto usa el reportResult() del vendedor que se describió anteriormente en esta guía para informar a su servidor.