En este documento, encontrarás una descripción general de alto nivel para ejecutar una subasta con datos de Protected Audience de 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 candidatos de anuncios 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 un análisis detallado de cómo los vendedores ejecutan subastas integradas en el dispositivo.
Seis etapas de una subasta de anuncios de la API de Protected Audience
- Un usuario visita un sitio que muestra anuncios.
- El código del vendedor ejecuta
navigator.runAdAuction(). Esto especifica qué espacio publicitario está en venta y quiénes pueden ofertar. Los vendedores también deben incluir una secuencia de comandos con una puntuación de cada oferta,scoreAd(). - El código del comprador invitado se ejecuta 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.
- El código del vendedor califica cada oferta y selecciona un ganador. Esta lógica utiliza el valor de la oferta y otros datos que muestran 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.
- El anuncio ganador se muestra como un valor opaco, que se muestra en un marco vallado. Ni el vendedor ni el publicador podrán ver este valor.
- Se informa al vendedor y a los compradores ganadores.
Una subasta puede producirse 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 publicitario.
Los vendedores inician la subasta de anuncios, califican los anuncios candidatos con una lógica personalizada que se proporciona como una función scoreAd() y son responsables de informar los resultados de la subasta a ellos y al comprador ganador. Los vendedores también pueden aplicar de manera forzosa las reglas del publicador y filtrar la calidad del anuncio con su función scoreAd().
Un vendedor puede hacer referencia a lo siguiente:
- Publicadores de contenido que actúan por sí mismos para alojar el contenido del anuncio en su sitio web
- Plataformas de proveedores (SSP), que trabajan con el publicador de anuncios y proporcionan otros servicios
- Guiones de terceros, que actúan para que los publicadores habiliten 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 candidato de anuncioreportResult(), que informa el resultado de la subasta al vendedor
Estas secuencias de comandos deben entregarse desde un único extremo que posee el vendedor.
scoreAd()
Un vendedor debe definir una función scoreAd() que se entrega desde un extremo que le pertenece. 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 de JSON que los vendedores y los compradores deberán definir y acordar la estructura.bid, que es un valor numérico que representa la ofertaauctionConfig, que es la configuración de la subasta que se utiliza para ejecutarlatrustedScoringSignals, que son indicadores leídos en el momento de la subasta desde el servidor de par clave-valor del vendedor. La plataforma usará elrenderUrldel anuncio candidato como clave para esta búsqueda.browserSignals, que es un objeto que crea el navegador, incluida la información que el navegador conoce y que la secuencia de comandos de subasta del vendedor podría querer verificar.directFromSellerSignalses un objeto que puede contener los siguientes campos: **sellerSignals: Es similar aauctionConfig.sellerSignals, pero se pasó con el mecanismodirectFromSellerSignals. **auctionSignals: Es similar aauctionConfig.auctionSignals, pero se pasó con el mecanismodirectFromSellerSignals.
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()
Un vendedor debe definir una función reportResult() que se entrega desde un extremo que le pertenece. 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 utiliza para ejecutarlabrowserSignals, que es un objeto que crea 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ónscoreAds().
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 requiere para sus informes.
Ejecuta una subasta de la API de Protected Audience
Un vendedor debe seguir cuatro pasos principales para ejecutar una subasta. Ten en cuenta que, en estos pasos, se supone que el vendedor tiene un extremo configurado para mostrar el JavaScript obligatorio que se mencionó anteriormente en esta guía.
- Configura la subasta. En este paso, se incluye la creación de un objeto
auctionConfig. Esto permite al vendedor especificar qué compradores deben participar en la subasta y proporcionar cualquier indicador que pueda ser relevante durante la generación de ofertas o la puntuación del anuncio. - Para ejecutar la subasta, llama a
navigator.runAdAuction()y pasa la configuración creada en el paso anterior. Esto inicia la cadena de compradores que genera ofertas y, luego, califica. El resultado final de este paso es un candidato de anuncio que se puede renderizar para mostrar un anuncio. - Renderiza el anuncio ganador en un marco cercado o iframe.
- 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. Esto usa elreportResult()del vendedor que se describió anteriormente en esta guía para informar a su servidor.