Aprende a configurar una subasta de la API de Protected Audience.
Subastas en el dispositivo que ejecutan los vendedores
En un sitio que vende espacios publicitarios, se ejecuta una subasta de Protected Audience integrada en el dispositivo, y nos referimos a la parte que ejecuta la subasta como el vendedor. Muchas partes pueden actuar como vendedores: un sitio puede ejecutar su propia subasta de anuncios, incluir una secuencia de comandos de terceros para que ejecute la subasta por él o usar una SSP que combine la ejecución de una subasta en el dispositivo con otras actividades de subasta de anuncios del servidor. Los vendedores tienen tres tareas básicas en la subasta de anuncios en el dispositivo:
- Los vendedores deciden (a) qué compradores pueden participar y (b) cuáles de las ofertas de los grupos de intereses de esos compradores son aptas para ingresar a la subasta. Esto permite que el vendedor aplique las reglas del sitio sobre qué anuncios pueden aparecer en la página.
- Los vendedores son responsables de la lógica empresarial de la subasta: código JavaScript que considera el precio y los metadatos de cada oferta, y calcula una puntuación de "deseabilidad". La oferta con la puntuación de conveniencia más alta gana la subasta.
- Los vendedores generan informes sobre el resultado de la subasta, incluida información sobre el precio de cierre y otros pagos. Los compradores que ganan y pierden también pueden generar sus propios informes.
En este documento, se explica cómo configurar e iniciar una subasta en el dispositivo.
Configura una subasta de anuncios de la API de Protected Audience
Para ejecutar una subasta de anuncios de la API de Protected Audience, el primer paso es configurar la subasta. Para ello, se crea un objeto auctionConfig.
A continuación, se muestra un ejemplo de una configuración de este tipo:
const auctionConfig = {
seller: 'https://seller.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://buyer-1.example': {...},
'https://buyer-2.example': {...},
...
},
perBuyerTimeouts: {
'https://buyer-1.example': 50,
'https://buyer-2.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://component-seller.example',
'decisionLogicUrl': ...,
...
},
...
],
resolveToConfig: [true|false],
};
AuctionConfig propiedades
Propiedades obligatorias
Las únicas propiedades obligatorias para auctionConfigs son seller, decisionLogicUrl y interestGroupBuyers.
| Propiedad | Ejemplo | Rol |
|---|---|---|
| vendedor | https://seller.example | Es el origen del vendedor. |
| decisionLogicUrl | https://seller.example/decision-logic.js | Es la URL del worklet de lógica de decisión de JavaScript de la subasta. Este campo debe tener el mismo origen que el campo del vendedor. |
| interestGroupBuyers | [https://buyer-1.example, https://buyer-2.example, ...] |
Orígenes de todos los propietarios de grupos de interés a los que se les solicitó que ofertaran en la subasta |
Propiedades opcionales
Las propiedades restantes de auctionConfigs son opcionales.
| Propiedad | Ejemplo | Rol |
|---|---|---|
| trustedScoringSignalsUrl | https://seller.example/scoring-signals | Es la URL del servidor de clave/valor del vendedor. Se consultará durante el proceso de calificación del anuncio con la URL de renderización de la creatividad como clave. Este campo debe tener el mismo origen que el campo del vendedor. |
| auctionSignals | {"category":"news"} | Es un objeto serializable en JSON que representa los indicadores disponibles para todos los compradores y vendedores que participan en la subasta. |
| sellerSignals | {…} | Objeto serializable en JSON que representa los indicadores disponibles solo para los vendedores. |
| perBuyerSignals | {https://dsp.example: {...}, https://another-buyer.example: {...}, ... } |
Son los indicadores disponibles para un comprador específico. Los indicadores pueden provenir de los vendedores y de los compradores. |
| perBuyerTimeouts | {https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...}, |
Es el tiempo de ejecución máximo en milisegundos de la secuencia de comandos generateBid() de un comprador en particular. Se aplicará un símbolo comodín a cada comprador que no tenga definido un tiempo de espera específico. |
| sellerTimeout | 100 | Es el tiempo de ejecución máximo en milisegundos de una secuencia de comandos scoreAd() del vendedor. |
| componentAuctions | [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] | Son parámetros de configuración adicionales para las subastas de componentes. |
| resolveToConfig | true|false | Es un valor booleano que indica si la promesa que devuelve runAdAuction() se resolverá en un FencedFrameConfig si es verdadero (para usar en un <fencedframe>) o en una URL opaca urn:uuid si es falso (para usar en un <iframe>). El valor predeterminado es falso. |
Proporciona indicadores de forma asíncrona
Los valores de algunos indicadores (los que se configuran con los campos auctionSignals, sellerSignals, perBuyerSignals y perBuyerTimeouts) se pueden proporcionar de forma opcional no como valores concretos, sino como promesas. Esto permite que algunas partes de la subasta, como la carga de secuencias de comandos y de indicadores de confianza, y el lanzamiento de procesos de worklet aislados, se superpongan con el cálculo (o la recuperación de red) de esos valores. Las secuencias de comandos de worklet solo verán los valores resueltos. Si se rechaza alguna de esas promesas, se anulará la subasta, a menos que ya haya fallado o se haya anulado de otras maneras.
Configura una subasta con varios vendedores
En algunos casos, es posible que varios vendedores deseen participar en una subasta, y los ganadores de subastas independientes se pasen a otra subasta, que ejecuta otro vendedor. Estas subastas separadas que se pasan se denominan subastas de componentes.
Para facilitar estas subastas de componentes, el objeto componentAuctions puede contener configuraciones de subastas adicionales para cada subasta de componentes del vendedor. La oferta ganadora de cada una de estas subastas de componentes se pasará a la subasta de "nivel superior", que es la que toma la determinación final de la subasta. Es posible que los auctionConfig de las subastas de componentes no tengan su propio componentAuctions. Cuando componentAuctions no está vacío, interestGroupBuyers debe estar vacío. Es decir, para cualquier subasta de Protected Audience en particular, o bien hay un solo vendedor y no hay subastas de componentes, o bien todas las ofertas provienen de subastas de componentes y la subasta de nivel superior solo puede elegir entre los ganadores de las subastas de componentes.
Ejecuta la subasta
El vendedor realiza una solicitud al navegador del usuario para iniciar una subasta de anuncios llamando a navigator.runAdAuction().
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
La llamada a runAdAuction() devuelve una promesa que se resuelve en el anuncio. Ningún código de la página del publicador puede inspeccionar el anuncio ganador ni obtener información sobre su contenido a partir del resultado de runAdAuction(). Si la marca resolveToConfig se estableció como verdadera en AuctionConfig, se devuelve un objeto FencedFrameConfig que solo se puede renderizar en un iframe delimitado. Si la marca se estableció como falsa, se devolverá un URN opaco que se puede renderizar en un iframe. Es posible que runAdAuction devuelva un valor nulo, lo que indica que no se seleccionó ningún anuncio. En este caso, el vendedor podría optar por renderizar un anuncio segmentado de forma contextual.