Guía de la API de Seller 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, tal como se usa en la iteración actual de la API experimental de Protected Audience.
Consulta la guía para desarrolladores para obtener información sobre la vida completa. 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 se ejecuta en el dispositivo del usuario para elegir un anuncio. Para preservar la privacidad, todos los El código de subasta del vendedor y los compradores se ejecuta en JavaScript aislado. worklets que no pueden comunicarse del mundo exterior.
.
- Un usuario visita un sitio que muestra anuncios.
- El código del vendedor ejecuta
navigator.runAdAuction(). Esto especifica qué el espacio publicitario está en venta y quién puede ofertar. Los vendedores también deben incluir un guion que califica cada oferta,scoreAd(). - El código del comprador invitado se ejecuta para generar una oferta (URL para un anuncio relevante). la creatividad y otros datos. La secuencia de comandos de licitación puede consultar datos en tiempo real como el presupuesto restante de la campaña publicitaria, del presupuesto Servicio de par clave-valor.
- El código del vendedor califica cada oferta y selecciona un ganador. Esta lógica usa el el valor de la oferta y otros datos muestran la deseabilidad de una oferta. Anuncios insuperables el ganador contextual se rechaza. El vendedor puede usar sus propios Servicio de par clave-valor para datos en tiempo real.
- El anuncio ganador se muestra como un valor opaco, que aparece en un marco vallado. Tanto el vendedor como el publicador no podrá ver este valor.
- Se informa la subasta 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 estrategia de varios vendedores, subasta programática:
- El usuario visita un sitio participante.
- Otro vendedor ejecuta 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 contenido de anuncios en su sitio web.
- Plataforma de proveedores (SSP): Trabajo con el publicador y proporciona otros servicios
- Secuencia de comandos de terceros: Actúa para un publicador que permite la participación en las subastas de anuncios.
Con la API de Protected Audience, un vendedor tiene tres trabajos:
- Aplicar las reglas del publicador: qué compradores y qué ofertas son aptos
- Lógica de subasta: ejecución de JavaScript en worklets para calcular puntuación de deseabilidad de cada oferta.
- Informa el resultado de la subasta.
Estos trabajos se realizan de forma programática, en el código que proporciona el vendedor cuando
inicia una subasta de anuncios llamando a la función de JavaScript.
navigator.runAdAuction()
Funciones de API
runAdAuction()
El vendedor llama a navigator.runAdAuction() para solicitar al navegador del usuario iniciar una subasta de anuncios.
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 un URN (urn:uuid:<something>) que representa la
resultado de la subasta de anuncios. El navegador solo puede decodificarlo 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 sus
una oferta y los metadatos asociados, uno a la vez, y luego se le asigna
puntuación de deseabilidad.
auctionConfig propiedades
seller- Obligatorio
- Ejemplo:
'https://ssp.example' - Rol: Es el origen del vendedor.
decisionLogicUrl- Obligatorio
- Ejemplo:
'https://ssp.example/auction-decision-logic.js' - Rol: URL para JavaScript del worklet de subasta.
trustedScoringSignalsUrl- Opcional
- Ejemplo:
'https://ssp.example/scoring-signals' - Rol: URL del servidor de confianza del vendedor.
interestGroupBuyers- Obligatorio
- Ejemplo:
['https://dsp.example', 'https://buyer2.example', ...] - Rol: 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 interés oferten. Los anuncios se aceptan o rechazan según criterios distintos de la inclusión del propietario del grupo de interés. Por ejemplo, el vendedor puede revisar las creatividades de los anuncios para confirmar el cumplimiento de sus políticas. auctionSignals- Opcional
- Ejemplo:
{...} - Rol: Información del vendedor sobre el contexto de la página, el tipo de subasta, etcétera.
sellerSignals- Opcional
- Ejemplo:
{...} - Rol: La información que se basa en la configuración del publicador, la realización de una solicitud de anuncios contextuales, etcétera.
sellerTimeout- Opcional
- Ejemplo:
100 - Rol: Tiempo 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 - Rol: Tiempo de ejecución máximo (ms) de las secuencias de comandos
generateBid()de un comprador específico. componentAuctions- Opcional
- Ejemplo:
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...] - Función: Configuración adicional para subastas de componentes.
decisionLogicUrl
decisionLogicUrl es una propiedad del objeto de configuración de la subasta.
pasado a runAdAuction(). Esta URL debe incluir una secuencia de comandos para el
función scoreAd(). Esta lógica se ejecuta una vez por cada anuncio
determinar su deseabilidad.
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
browserSignals
browserSignals es un objeto que construye el navegador, incluida la información
que el navegador conoce y cuál es la secuencia de comandos de subasta del vendedor
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 la
espacio publicitario disponible. Parte de la lógica de scoreAd() rechaza los anuncios que no pueden
superaron 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 |
Son 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 elige?
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 ejecuta la función en un worklet que tiene una comunicación limitada con 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.