Obtén información para configurar una subasta de la API de Protected Audience.
Subastas integradas en el dispositivo que ejecutan los vendedores
Una subasta de Protected Audience integrada se ejecuta en un sitio que vende espacios publicitarios 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 ejecutar la subasta 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 trabajos básicos 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 participar en 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: el código JavaScript, que considera el precio y los metadatos de cada oferta y calcula una puntuación de "deseable". La oferta con la puntuación de deseabilidad más alta gana la subasta.
- Los vendedores informan sobre el resultado de la subasta, incluida la información sobre la liquidación del precio y cualquier otro pago. Los compradores ganadores y perdedores también pueden hacer sus propios informes.
En este documento, se explicará cómo configurar e iniciar una subasta integrada en el dispositivo.
Cómo configurar 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 configurarla. Para ello, se crea un objeto auctionConfig.
A continuación, se muestra un ejemplo de una de esas configuraciones:
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 | Origen del vendedor. |
| decisionLogicUrl | https://seller.example/decision-logic.js | URL del worklet de lógica de decisión de JavaScript de subasta. Este campo debe tener el mismo origen que el campo del vendedor. |
| interestGroupBuyers | [https://comprador-1.example, https://comprador-2.example, ...] |
Orígenes de todos los propietarios de grupos de interés a los que se les pidió ofertar en la subasta |
Propiedades opcionales
Las propiedades restantes de auctionConfigs son opcionales.
| Propiedad | Ejemplo | Rol |
|---|---|---|
| trustedScoringSignalsUrl | https://seller.example/scoring-signals | URL del servidor de par clave-valor del vendedor. Esta consulta se hará durante el proceso de puntuación de anuncios y se usará la URL de renderización de la creatividad como clave. Este campo debe tener el mismo origen que el campo del vendedor. |
| auctionSignals | {"category":"noticias"} | Es un objeto serializable en JSON que representa los indicadores disponibles para todos los compradores y vendedores que participan en la subasta. |
| sellerSignals | {...} | Es un objeto serializable en JSON que representa los indicadores disponibles solo para los vendedores. |
| perBuyerSignals | {https://dsp.example: {...}, https://otro-comprador.example: {...}, ... } |
Son indicadores disponibles para un comprador específico. Los indicadores pueden provenir de los vendedores y también de los compradores. |
| perBuyerTimeouts | {https://www.example-dsp.com: 50, https://www.otro-comprador.com: 200, *: 150, ...}, |
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 los compradores que no tengan un tiempo de espera específico definido. |
| sellerTimeout | 100 | Tiempo de ejecución máximo en milisegundos de la secuencia de comandos scoreAd() de un vendedor. |
| componentAuctions | [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] | Configuraciones adicionales para subastas de componentes. |
| resolveToConfig | verdadero|falso | Es un valor booleano que dirige la promesa que se muestra desde runAdSubasta() para resolver un elemento FencedFrameConfig si es verdadero (para usar en un <fencedframe>) o a una URL urn:uuid opaca si es falsa (para usar en un <iframe>). El valor predeterminado es falso. |
Proporciona indicadores de forma asíncrona
De manera opcional, los valores de algunos indicadores (los que configuran los campos auctionSignals, sellerSignals, perBuyerSignals y perBuyerTimeouts) no se pueden proporcionar como valores concretos, sino como promesas. Esto permite que algunas partes de la subasta, como la carga de secuencias de comandos, señales de confianza y el inicio de procesos de worklet aislados, se superpongan con el cálculo (o la recuperación de la red) de esos valores. Las secuencias de comandos del worklet solo verán los valores resueltos. Si se rechaza alguna de esas promesas, se anulará la subasta, a menos que ya falle o se anule de otras maneras.
Cómo configurar una subasta con varios vendedores
En algunos casos, es posible que varios vendedores quieran participar en una subasta, y los ganadores de subastas independientes pasan a otra subasta, administrada por otro vendedor. Estas subastas independientes que se rechazan se denominan subastas de componentes.
Para facilitar estas subastas de componentes, el objeto componentAuctions puede contener configuraciones de subasta adicionales para la subasta de componentes de cada vendedor. La oferta ganadora de cada una de estas subastas de componentes se pasará a la subasta de "nivel superior", que será la determinación final de la subasta. Es posible que el auctionConfig de las subastas de componentes no tenga su propio componentAuctions. Cuando componentAuctions no esté vacío, interestGroupBuyers también deberá estarlo. Es decir, en cualquier subasta de Protected Audience en particular, hay un solo vendedor y ninguna subasta 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 llama a navigator.runAdAuction() para iniciar una subasta de anuncios al navegador del usuario.
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
La llamada runAdAuction() muestra una promesa que se resuelve en el anuncio. No es posible que ningún código de la página del publicador inspeccione el anuncio ganador ni obtenga información sobre su contenido a partir del resultado de runAdAuction(). Si la marca resolveToConfig se configuró como verdadera en AuctionConfig, se muestra un objeto FencedFrameConfig que solo se puede renderizar en un marco vallado. Si la marca se estableció como falsa, se muestra un URN opaco que se puede renderizar en un iframe. Es posible que runAdSubasta muestre un valor nulo, lo que indica que no se seleccionó ningún anuncio. En este caso, el vendedor podría elegir renderizar un anuncio de segmentación contextual.