Guía para vendedores: Publique subastas de anuncios

Guía y referencias de la API del vendedor 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.

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 sobre cómo los vendedores ejecutan subastas 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 la subasta de anuncios del vendedor y los compradores se ejecuta en worklets de JavaScript aislados que no pueden comunicarse con el mundo exterior.

1. Un usuario visita un sitio que muestra anuncios.
2. El código del vendedor ejecuta navigator.runAdAuction(). Especifica qué espacio publicitario está a la venta y quién puede ofertar. Los vendedores también deben incluir un script que califique cada oferta, scoreAd().
3. El código del comprador invitado se ejecuta para generar una oferta, una URL para una creatividad del anuncio pertinente 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 clave/valor del comprador.
4. El código del vendedor califica cada oferta y selecciona un ganador. Esta lógica utiliza el valor de la oferta y otros datos para devolver 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.
5. El anuncio ganador se devuelve como un valor opaco, que se muestra en un marco delimitado. Ni el vendedor ni el publicador podrán ver este valor.
6. La subasta se informa a los vendedores y a los compradores ganadores.

¿Cuándo se realizará la subasta?

La API de Protected Audience se puede ejecutar por sí sola o con subastas programáticas. En una subasta programática con varios vendedores, sucede lo siguiente:

1. El usuario visita un sitio participante.
2. Otro vendedor ejecuta una subasta programática para encontrar un anuncio contextual para un espacio publicitario disponible.
3. Se ejecuta la subasta de la API de Protected Audience.
4. 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?

Hay varias partes que pueden ejecutar una subasta para vender espacio publicitario.

Por ejemplo:

• Publicador de contenido: Actúa por sí mismo para alojar contenido de anuncios en su sitio web.
• Plataforma de proveedores (SSP): Trabaja con el publicador y proporciona otros servicios.
• Secuencia de comandos de terceros: Actúa en nombre de un publicador para habilitar la participación en subastas de anuncios.

Con la API de Protected Audience, un vendedor tiene tres tareas:

• Aplicar las reglas del publicador: qué compradores y qué ofertas son aptos
• Ejecución de la lógica de la subasta: JavaScript que se ejecuta en worklets para calcular una puntuación de conveniencia para 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 la API

runAdAuction()

El vendedor realiza una solicitud al navegador del usuario para iniciar una subasta de anuncios llamando a navigator.runAdAuction().

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() devuelve una promesa que se resuelve en un URN (urn:uuid:<something>) que representa el resultado de la subasta de anuncios. El navegador solo puede decodificarlo cuando se pasa a un marco delimitado 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 metadatos asociados, uno a la vez, y luego le asigna una puntuación de conveniencia numérica.

auctionConfig propiedades

seller

Obligatorio

Ejemplo: 'https://ssp.example'

Rol: Origen del vendedor.

decisionLogicUrl

Obligatorio

Ejemplo: 'https://ssp.example/auction-decision-logic.js'

Rol: URL del 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 solicitó que presentaran ofertas en la subasta.

Notas: El vendedor puede especificar interestGroupBuyers: para permitir que todos los grupos de intereses realicen ofertas. Luego, se aceptan o rechazan los anuncios según criterios que no incluyen la pertenencia al propietario del grupo de interés. Por ejemplo, el vendedor puede revisar las creatividades de los anuncios para confirmar que cumplen con 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: Información basada en la configuración del publicador, la realización de una solicitud de anuncio contextual, etcétera

sellerTimeout

Opcional

Ejemplo: 100

Role: 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': {...}, ... }

Role: 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 (en ms) de las secuencias de comandos de generateBid() de un comprador en particular.

componentAuctions

Opcional

Ejemplo:

[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]

Rol: Configuraciones adicionales para las 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 un script para la función scoreAd(). Esta lógica se ejecuta una vez para cada anuncio para determinar su conveniencia.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

browserSignals

browserSignals es un objeto que construye el navegador y que incluye información que el navegador conoce y que el script 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 busca 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:

Preguntas frecuentes

¿Cómo se decide quién gana la subasta y quién lo elige?

El vendedor proporciona la lógica de puntuación para determinar la puntuación de conveniencia 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 el código fuera de él. 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.