Guía de la API del vendedor y referencias para la subasta de anuncios de la API de Protected Audience
En este artículo, encontrarás una referencia técnica para la subasta de anuncios, como se usa en la iteración actual de la API experimental de Protected Audience.
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.
¿No eres desarrollador? Consulta la descripción general de la API de Protected Audience.
¿Qué es la subasta de anuncios de la API de Protected Audience?
Una subasta de anuncios de la API de Protected Audience es una colección de pequeños programas de JavaScript que el navegador ejecuta en el dispositivo del usuario para elegir un anuncio. Para preservar la privacidad, todo el código de subasta de anuncios del vendedor y de los compradores se ejecuta en trabajos de JavaScript aislados que no pueden comunicarse con el mundo exterior.
- 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.
¿Cuándo se lleva a cabo la subasta?
La API de Protected Audience se puede ejecutar por su cuenta o con subastas programáticas. En una subasta programática de varios vendedores:
- El usuario visita un sitio participante.
- Otro vendedor realiza una subasta programática para encontrar un anuncio contextual para un espacio publicitario disponible.
- Se ejecuta la subasta de la API de Protected Audience.
scoreAd()compara las ofertas del comprador con los resultados de la primera subasta.
Se rechazan las ofertas que no pueden superar al ganador contextual.
¿Quién ejecuta la subasta de anuncios de la API de Protected Audience?
Existen varias partes que podrían realizar una subasta para vender espacio publicitario.
Por ejemplo:
- Publicador de contenido: Actúa por su cuenta para alojar el contenido del anuncio en su sitio web.
- Plataforma de proveedor (SSP): Trabajar con el publicador y proporcionar otros servicios.
- Secuencia de comandos de terceros: Actuar en nombre de un publicador para habilitar la participación en subastas de anuncios.
Con la API de Protected Audience, un vendedor tiene tres trabajos:
- Aplicar las reglas del publicador, es decir, qué compradores y qué ofertas son aptas
- Ejecuta la lógica de subasta: JavaScript se ejecuta en trabajos para calcular una puntuación de deseabilidad para cada oferta.
- Informa el resultado de la subasta.
Estos trabajos se realizan de manera programática, en el código que proporciona el vendedor cuando se inicia una subasta de anuncios con una llamada a la función navigator.runAdAuction() de JavaScript.
Funciones de API
runAdAuction()
El vendedor llama a navigator.runAdAuction() para iniciar una subasta de anuncios al navegador del usuario.
Por ejemplo:
const auctionConfig = {
seller: 'https://ssp.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://dsp.example': {...},
'https://another-buyer.example': {...},
...
},
perBuyerTimeouts: {
'https://dsp.example': 50,
'https://another-buyer.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://some-other-ssp.example',
'decisionLogicUrl': ...,
...
},
...
]
};
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
runAdAuction() muestra una promesa que se resuelve en una URN (urn:uuid:<something>) que representa el resultado de la subasta de anuncios. El navegador solo puede decodificar esto cuando se pasa a un marco vallado para la renderización: la página del publicador no puede inspeccionar el anuncio ganador.
La secuencia de comandos decisionLogicUrl considera cada anuncio individual, junto con su oferta y sus metadatos asociados, uno a la vez y, luego, le asigna una puntuación de deseabilidad numérica.
auctionConfig propiedades
seller- Obligatorio
- Ejemplo:
'https://ssp.example' - Función: Origen del vendedor.
decisionLogicUrl- Obligatorio
- Ejemplo:
'https://ssp.example/auction-decision-logic.js' - Función: URL para el worklet de JavaScript de la subasta.
trustedScoringSignalsUrl- Opcional
- Ejemplo:
'https://ssp.example/scoring-signals' - Función: URL del servidor de confianza del vendedor.
interestGroupBuyers- Obligatorio
- Ejemplo:
['https://dsp.example', 'https://buyer2.example', ...] - Rol: Los orígenes de todos los propietarios de grupos de interés a los que se les pidió ofertar en la subasta.
- Notas: El vendedor puede especificar
interestGroupBuyers:para permitir que todos los grupos de intereses oferten. Luego, los anuncios se aceptan o rechazan en función de criterios que no sean la inclusión del propietario del grupo de interés. Por ejemplo, el vendedor puede revisar las creatividades de anuncios para confirmar el cumplimiento de sus políticas. auctionSignals- Opcional
- Ejemplo:
{...} - Función: Información del vendedor sobre el contexto de la página, tipo de subasta, etcétera.
sellerSignals- Opcional
- Ejemplo:
{...} - Rol: información basada en la configuración del publicador, la realización de una solicitud de anuncio contextual, etcétera.
sellerTimeout- Opcional
- Ejemplo:
100 - Función: entorno de ejecución máximo (ms) de la secuencia de comandos
scoreAd()del vendedor. perBuyerSignals- Opcional
- Ejemplo:
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... } - Rol: Indicadores contextuales sobre la página para cada comprador específico, desde su servidor.
perBuyerTimeouts- Opcional
- Ejemplo:
50 - Función: entorno de ejecución máximo (ms) de secuencias de comandos
generateBid()de un comprador específico. componentAuctions- Opcional
- Ejemplo:
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...] - Función: Parámetros de configuración adicionales para subastas de componentes.
decisionLogicUrl
decisionLogicUrl es una propiedad del objeto de configuración de la subasta, que se pasa a runAdAuction(). Esta URL debe incluir una secuencia de comandos para la función scoreAd(). Esta lógica se ejecuta una vez por cada anuncio para determinar su conveniencia.
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
browserSignals
browserSignals es un objeto que crea el navegador, incluida la información que este conoce y que la secuencia de comandos de subasta del vendedor podría querer verificar:
{
topWindowHostname: 'publisher.example',
interestGroupOwner: 'https://dsp.example',
renderUrl: 'https://cdn.example/render',
adComponents: ['https://cdn.com/ad-component-1', ...],
biddingDurationMsec: 12,
dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}
Antes de que comience una subasta, el vendedor encuentra el mejor anuncio contextual para el espacio publicitario disponible. Parte de la lógica de scoreAd() rechaza cualquier anuncio que no pueda superar al ganador contextual.
scoreAd()
scoreAd() toma los siguientes argumentos:
| Argumento | Rol |
|---|---|
adMetadata |
Metadatos arbitrarios proporcionados por el comprador. |
auctionConfig |
El objeto de configuración de la subasta que se pasa a navigator.runAdAuction(). |
bid |
Es un valor numérico de la oferta. |
trustedScoringSignals |
Valores recuperados en el momento de la subasta del servidor de confianza del vendedor, que representan la opinión del vendedor sobre el anuncio. |
Preguntas frecuentes
¿Cómo se decide el ganador de la subasta y quién lo hace?
El vendedor proporciona la lógica de puntuación para determinar la puntuación de deseabilidad de cada anuncio, y el navegador selecciona la puntuación más alta como el anuncio ganador.
El vendedor incluye lógica en la función scoreAd(), y el navegador la ejecuta en un worklet que tiene una comunicación limitada con el código externo. El navegador en sí no califica los anuncios. El navegador es el único responsable de ejecutar la lógica de puntuación y seleccionar la oferta con la puntuación más alta.
Todas las referencias de la API de Protected Audience
Las guías de referencia de la API están disponibles:
- Guía para desarrolladores sobre la API de Protected Audience
- Guía para compradores de anuncios sobre los grupos de interés y la generación de ofertas de Protected Audience.
- Guía para vendedores de anuncios sobre las subastas de anuncios de Protected Audience.
- Guía para informar los resultados de las subastas
- Prácticas recomendadas para la latencia de subasta de anuncios de Protected Audience
- Cómo solucionar problemas de Protected Audience
La explicación de la API de Protected Audience también proporciona detalles sobre la compatibilidad y las restricciones de funciones.