Ejecuta una subasta basada en el navegador con un solo vendedor

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

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 involucra a varios vendedores. En este caso, la subasta de un solo vendedor se conoce como "subasta de componentes", que puede proporcionar anuncios candidatos a 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 una explicación detallada de cómo los vendedores ejecutan subastas integradas 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(). Esto especifica qué espacio publicitario está a la venta y quién puede ofertar. Los vendedores también deben incluir una secuencia de comandos que califique cada oferta, scoreAd().
3. Se ejecuta el código del comprador invitado para generar una oferta, una URL para una creatividad de anuncio relevante 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 par clave-valor del comprador.
4. El código del vendedor califica cada oferta y selecciona una ganadora. Esta lógica usa el valor de la oferta y otros datos que muestran la deseabilidad 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 obtener datos en tiempo real.
5. El anuncio ganador se muestra 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 al vendedor y a los compradores ganadores.

Una subasta puede ocurrir cuando un usuario navega a una página que muestra un anuncio. Las subastas se pueden ejecutar con anticipación para que la creatividad del anuncio esté lista cuando aparezca el espacio de anuncios.

Los vendedores inician la subasta de anuncios, califican los anuncios candidatos con una 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 del publicador y filtrar la calidad de los anuncios con su función scoreAd().

Un vendedor puede hacer referencia a lo siguiente:

• Publicadores de contenido que actúan por su cuenta para alojar contenido de anuncios en su sitio web
• Plataformas de proveedores (SSP), que trabajan con el publicador de anuncios y proporcionan otros servicios
• Secuencias de comandos de terceros que actúan en nombre de un publicador para habilitar 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 asigna una puntuación a un anuncio candidato
• reportResult(), que se encarga de informar el resultado de la subasta al vendedor

Estas secuencias de comandos deben publicarse desde un solo extremo que pertenezca al vendedor.

scoreAd()

Un vendedor debe definir una función scoreAd() que se publique desde un extremo que sea 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 JSON que los vendedores y compradores deberán definir y acordar la 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 par clave-valor del vendedor. La plataforma usará el renderUrl del anuncio candidato como la clave para esta búsqueda.
• browserSignals, que es un objeto que construye el navegador, incluida la información que el navegador conoce y que la secuencia de comandos de subasta del vendedor podría querer verificar.
• directFromSellerSignals es un objeto que puede contener los siguientes campos: ** sellerSignals: Al igual que auctionConfig.sellerSignals, pero se pasa con el mecanismo directFromSellerSignals. ** auctionSignals: Es similar a auctionConfig.auctionSignals, pero se pasa con el mecanismo directFromSellerSignals.

El siguiente es 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()

Un 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 que construye el navegador, incluida la información que el navegador conoce y que la secuencia de comandos de subasta del vendedor podría querer verificar. Este es el mismo objeto que se pasa a la función scoreAds().

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

Ejecuta una subasta de la API de Protected Audience

Existen cuatro pasos principales que un vendedor debe seguir para ejecutar una subasta. Ten en cuenta que, en estos pasos, se da por sentado que el vendedor tiene configurado un extremo para mostrar 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 al vendedor especificar 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. Para ejecutar la subasta, llama a navigator.runAdAuction() y pasa la configuración que creaste en el paso anterior. Esto inicia la cadena de compradores que generan ofertas y, luego, la puntuación. El resultado final de este paso es un anuncio candidato que se puede renderizar para mostrar un anuncio.
3. Renderiza el anuncio ganador en un marco o un iframe cercados.
4. Informa el resultado de la subasta. Hay una función, navigator.sendReportTo(), que iniciará los informes. El vendedor siempre recibirá un informe de los resultados de la subasta. Solo el comprador que ganó la subasta recibirá un informe. Para ello, se usa el reportResult() del vendedor que se describió antes en esta guía para informar a su servidor.