Guía para desarrolladores sobre la API de FLEDGE

¿A quién está dirigido este artículo?

Esta publicación es una referencia técnica a la iteración actual de la API experimental de Protected Audience.

¿Qué es Protected Audience?

La API de Protected Audience es una propuesta de Privacy Sandbox para publicar casos de uso de remarketing y de público personalizado. Estos casos de uso se diseñaron de modo que los terceros no puedan usarlos para hacer un seguimiento del comportamiento de navegación de los usuarios en diferentes sitios. La API habilita subastas integradas en el dispositivo por parte del navegador para elegir anuncios relevantes para los sitios web que el usuario visitó anteriormente.

Protected Audience es el primer experimento que se implementará en Chromium dentro de la familia de propuestas de TURTLEDOVE.

En el siguiente diagrama, se proporciona una descripción general del ciclo de vida de FLEDGE:

Ilustración que proporciona una descripción general de cada etapa del ciclo de vida de FLEDGE
Ciclo de vida de FLEDGE.

¿Cómo puedo probar Protected Audience?

Demo de Protected Audience

En protected-audience-demo.web.app, puedes encontrar una explicación paso a paso de una implementación básica de Protected Audience en los sitios de anunciantes y publicadores.

En el video de demostración, se explica cómo funciona el código de demostración y se muestra cómo usar DevTools de Chrome para la depuración de Protected Audience.

Participa en una prueba de origen de Protected Audience

Se puso a disposición una prueba de origen de relevancia y medición de Privacy Sandbox en Chrome beta 101.0.4951.26 y versiones posteriores para computadoras de escritorio para las APIs de Protected Audience, Topics y Attribution Reporting.

Para participar, regístrate para obtener un token de prueba de origen.

Una vez que te hayas inscrito correctamente en la prueba, podrás probar la API de JavaScript de Protected Audience en páginas que proporcionen un token de prueba válido: por ejemplo, para pedirle al navegador que se una a uno o más grupos de interés y, luego, ejecute una subasta de anuncios para seleccionar y mostrar un anuncio.

La demo de Protected Audience proporciona un ejemplo básico de una implementación de Protected Audience de extremo a extremo.

Proporciona un token de prueba para cada página en la que deseas ejecutar el código de la API de Protected Audience:

  • Como una metaetiqueta en <head>:

    <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">

  • Como un encabezado HTTP:

    Origin-Trial: TOKEN_GOES_HERE

  • Proporcionando un token de manera programática:

    const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);

Un iframe que ejecute código de Protected Audience, como una llamada a navigator.joinAdInterestGroup() de un propietario de grupo de interés, deberá proporcionar un token que coincida con su origen.

En Proposed First Protected Audience Origin Trial Details, se proporcionan más detalles sobre los objetivos de la primera prueba y se explica qué funciones son compatibles.

Prueba esta API

Puedes probar Protected Audience para un solo usuario en Chrome Beta 101.0.4951.26 y versiones posteriores en computadoras:

  • Habilitando todas las APIs de privacidad en los anuncios en chrome://settings/adPrivacy
  • Establece marcas desde la línea de comandos.

Renderiza anuncios en iframes o marcos delimitados

Los anuncios se pueden renderizar en un <iframe> o un <fencedframe>, según las marcas que se establezcan.

Para usar <fencedframe> y renderizar anuncios, haz lo siguiente:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

Para usar <iframe> y renderizar anuncios, haz lo siguiente:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

Incluye la marca BiddingAndScoringDebugReportingAPI para habilitar los métodos de informes de pérdidas o ganancias de depuración temporales.

En Cómo ejecutar Chromium con marcas, se explica cómo establecer marcas cuando se ejecuta Chrome y otros navegadores basados en Chromium desde la línea de comandos. La lista completa de marcas de Protected Audience está disponible en Chromium Code Search.

¿Qué funciones son compatibles con la versión más reciente de Chrome?

Protected Audience estará disponible detrás de marcas de función en Chromium como un primer experimento para probar las siguientes funciones de la propuesta de Protected Audience:

  • Grupos de intereses: El navegador los almacena con metadatos asociados para configurar la oferta y la renderización de anuncios.
  • Ofertas integradas en el dispositivo por parte de los compradores (DSP o anunciante): Se basan en los grupos de intereses almacenados y los indicadores del vendedor.
  • Selección de anuncios integrados en el dispositivo por parte del vendedor (SSP o publicador): Se basa en las ofertas de subasta y los metadatos de los compradores.
  • Renderización de anuncios en una versión temporalmente relajada de los fotogramas con perímetro: con acceso a la red y registro permitidos para la renderización de anuncios.

En la explicación de la API, se proporcionan más detalles sobre la compatibilidad y las restricciones de las funciones.

Permisos de los grupos de interés

El valor predeterminado en la implementación actual de Protected Audience es permitir llamar a joinAdInterestGroup() desde cualquier lugar de una página, incluso desde iframes de varios dominios. En el futuro, una vez que los propietarios de sitios tengan tiempo para ajustar sus políticas de permisos de iframes entre dominios, el plan es inhabilitar las llamadas de iframes entre dominios, como se describe en la explicación.

Servicio de par clave-valor

Como parte de una subasta de anuncios de Protected Audience, el navegador puede acceder a un servicio de par clave-valor que muestra pares clave-valor simples para proporcionar información a un comprador de anuncios, como el presupuesto restante de la campaña. La propuesta de Protected Audience exige que este servidor "no realice registros a nivel de evento y no tenga otros efectos secundarios basados en estas solicitudes".

El código del servicio de par clave-valor de Protected Audience ahora está disponible en un repositorio de GitHub de Privacy Sandbox. Los desarrolladores de Chrome y Android pueden usar este servicio. Consulta la entrada de blog del anuncio para conocer el estado actualizado. Obtén más información sobre el servicio de par clave-valor de Protected Audience en la explicación de la API y la explicación del modelo de confianza.

Para las pruebas iniciales, se usa el modelo “Trae tu propio servidor”. A largo plazo, las plataformas de tecnología publicitaria deberán usar los servicios de par clave-valor de Protected Audience de código abierto que se ejecutan en entornos de ejecución de confianza para recuperar datos en tiempo real.

Para garantizar que el ecosistema tenga tiempo suficiente para realizar pruebas, no esperamos que se requiera el uso de los servicios de par clave-valor o los TEE de código abierto hasta algún momento después de que se den de baja las cookies de terceros. Les enviaremos un aviso importante a los desarrolladores para que comiencen con las pruebas y la adopción antes de que se lleve a cabo esta transición.

Cómo detectar la compatibilidad con funciones

Antes de usar la API, verifica si el navegador la admite y si está disponible en el documento:

'joinAdInterestGroup' in navigator &&
  document.featurePolicy.allowsFeature('join-ad-interest-group') &&
  document.featurePolicy.allowsFeature('run-ad-auction') ?
  console.log('navigator.joinAdInterestGroup() is supported on this page') :
  console.log('navigator.joinAdInterestGroup() is not supported on this page');

¿Cómo puedo inhabilitar Protected Audience?

Puedes bloquear el acceso a la API de Protected Audience como propietario de un sitio o como usuario individual.

¿Cómo pueden los sitios controlar el acceso?

Con el tiempo, Protected Audience requerirá que los sitios establezcan una política de permisos para que la funcionalidad de Protected Audience esté disponible. Esto ayudará a garantizar que terceros arbitrarios no puedan usar la API sin el conocimiento del sitio. Sin embargo, para facilitar las pruebas durante la primera prueba de origen, este requisito se exime de forma predeterminada. Los sitios que deseen inhabilitar de forma explícita la funcionalidad de Protected Audience durante el período de prueba pueden usar la Política de Permisos relevante para bloquear el acceso.

Existen dos políticas de permisos de Protected Audience que se pueden configurar de forma independiente:

  • join-ad-interest-group habilita o inhabilita la funcionalidad para agregar un navegador a los grupos de interés
  • run-ad-auction habilita o inhabilita la funcionalidad para ejecutar una subasta integrada en el dispositivo.

El acceso a las APIs de Protected Audience se puede inhabilitar por completo en contextos propios si se especifica la siguiente política de permisos en un encabezado de respuesta HTTP:

Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()

Para inhabilitar el uso de las APIs en un iframe, agrega el siguiente atributo allow a un elemento de iframe:

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

En la sección Propuesta de política de permisos de la primera prueba de origen de Protected Audience, se proporcionan más detalles.

Rechazo de parte del usuario

Un usuario puede bloquear el acceso a la API de Protected Audience y a otras funciones de Privacy Sandbox con cualquiera de los siguientes mecanismos:

  • Inhabilita las pruebas de Privacy Sandbox en la configuración de Chrome: Configuración > Seguridad y privacidad > Privacy Sandbox. También puedes acceder a esta información en chrome://settings/adPrivacy.
  • Inhabilita las cookies de terceros en la configuración de Chrome: Configuración > Seguridad y privacidad.
  • En chrome://settings/cookies, establece Datos de sitios y cookies en "Bloquear cookies de terceros" o "Bloquear todas las cookies".
  • Usa el modo Incógnito.

En la explicación de Protected Audience, se proporcionan más detalles sobre los elementos de diseño de la API y se describe cómo la API busca cumplir con los objetivos de privacidad.

Cómo depurar worklets de Protected Audience

A partir de Chrome Canary 98.0.4718.0, es posible depurar worklets de Protected Audience en las Herramientas para desarrolladores de Chrome.

El primer paso es establecer puntos de interrupción a través de una categoría nueva en el panel Event Listener Breakpoints del panel Sources.

Captura de pantalla de DevTools en Chrome Canary, en la que se destaca el panel de puntos de interrupción del objeto de escucha de eventos en el panel Sources. En la worklet de subasta de anuncios, se selecciona Bidder Bidding Phase Start.

Cuando se activa un punto de interrupción, la ejecución se detiene antes de la primera sentencia en el nivel superior de la secuencia de comandos de la worklet. Puedes usar puntos de interrupción normales o comandos de paso para llegar a la función de ofertas, puntuación o informes.

Las secuencias de comandos de worklet en vivo también aparecerán en el panel de conversaciones.

Captura de pantalla de DevTools en Chrome Canary, en la que se destaca el panel Threads en el panel Sources, que muestra la secuencia de comandos de worklet actual que se detuvo.

Dado que algunos worklets pueden ejecutarse en paralelo, es posible que varios subprocesos terminen en el estado "pausado". Puedes usar la lista de subprocesos para cambiar entre ellos y reanudarlos o inspeccionarlos con mayor detalle según corresponda.

Observa los eventos de Protected Audience

En el panel Application de las Herramientas para desarrolladores de Chrome, puedes observar el grupo de interés de Protected Audience y los eventos de subasta.

Si visitas el sitio de compras de demostración de Protected Audience en un navegador con Protected Audience habilitado, DevTools mostrará información sobre el evento join.

El panel de la aplicación de DevTools en Chrome Canary, que muestra información sobre un evento de unión a un grupo de interés de Protected Audience

Ahora, si visitas el sitio del publicador de demostración de Protected Audience en un navegador con Protected Audience habilitado, DevTools muestra información sobre los eventos bid y win.

El panel de la aplicación de DevTools en Chrome Canary, que muestra información sobre la oferta de la subasta de Protected Audience y los eventos de ganancia.

¿Cómo funciona la API de Protected Audience?

En este ejemplo, un usuario explora el sitio web de un fabricante de bicicletas personalizadas y, luego, visita un sitio web de noticias, y se le muestra un anuncio de una bicicleta nueva del fabricante.

1. Un usuario visita el sitio de un anunciante

Ilustración que muestra a una persona visitando el sitio de un fabricante de bicicletas personalizadas en un navegador de su laptop.

Imagina que un usuario visita el sitio web de un fabricante de bicicletas personalizadas (el anunciante en este ejemplo) y pasa un tiempo en la página del producto de una bicicleta de acero hecha a mano. Esto le brinda al fabricante de bicicletas una oportunidad de remarketing.

2. Se le solicita al navegador del usuario que agregue un grupo de interés

Ilustración de una persona que ve un sitio en un navegador de su laptop. El código JavaScript joinAdInterestGroup() se ejecuta en el navegador.

Sección explicativa: Los navegadores registran grupos de intereses

La plataforma orientada a la demanda (DSP) del anunciante (o el anunciante en sí) llama a navigator.joinAdInterestGroup() para pedirle al navegador que agregue un grupo de interés a la lista de grupos de los que es miembro. En este ejemplo, el grupo se llama custom-bikes y el propietario es dsp.example. El propietario del grupo de intereses (en este caso, la DSP) será un comprador en la subasta de anuncios que se describe en el paso 4. El navegador almacena la membresía del grupo de intereses en el dispositivo del usuario y no la comparte con el proveedor del navegador ni con nadie más.

joinAdInterestGroup() requiere permiso de lo siguiente:

  • El sitio que se visita
  • El propietario del grupo de interés

Por ejemplo, no debe ser posible que malicious.example llame a joinAdInterestGroup() con dsp.example como propietario sin el permiso de dsp.example.

Permiso del sitio que se visita

Mismo origen: De forma predeterminada, se otorga implícitamente permiso para las llamadas joinAdInterestGroup() desde el mismo origen que el sitio que se visita, es decir, desde el mismo origen que el marco de nivel superior de la página actual. Los sitios pueden usar una directiva join-ad-interest-group del encabezado de la política de permisos de Protected Audience para inhabilitar las llamadas a joinAdInterestGroup().

Origen cruzado: Llamar a joinAdInterestGroup() desde orígenes diferentes de la página actual solo puede tener éxito si el sitio que se visita estableció una política de permisos que permita las llamadas a joinAdInterestGroup() desde iframes de origen cruzado.

Permiso del propietario del grupo de intereses

Para otorgar el permiso del propietario del grupo de intereses de forma implícita, llama a joinAdInterestGroup() desde un iframe con el mismo origen que el del propietario del grupo de intereses. Por ejemplo, un iframe dsp.example puede llamar a joinAdInterestGroup() para los grupos de intereses que pertenecen a dsp.example.

La propuesta es que joinAdInterestGroup() se pueda ejecutar en una página o un iframe en el dominio del propietario, o bien delegar a otros dominios proporcionados con una lista en una URL de .well-known.

Cómo usar navigator.joinAdInterestGroup()

Este es un ejemplo de cómo se podría usar la API:

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  dailyUpdateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

El objeto interestGroup que se pasa a la función no debe tener un tamaño superior a 50 KiB; de lo contrario, la llamada fallará. El segundo parámetro especifica la duración del grupo de intereses, con un límite de 30 días. Las llamadas sucesivas reemplazan los valores almacenados anteriormente.

Propiedades del grupo de interés

Propiedad Obligatorio Ejemplo Rol
owner Obligatorio 'https://dsp.example' Origen del propietario del grupo de interés.
name Obligatorio 'custom-bikes' Es el nombre del grupo de intereses.
biddingLogicUrl** Opcional* 'https://dsp.example/bid/custom-bikes/bid.js' Es la URL para ejecutar JavaScript de ofertas en una worklet.
biddingWasmHelperUrl** Opcional* 'https://dsp.example/bid/custom-bikes/bid.wasm' Es la URL del código de WebAssembly que se ejecuta desde biddingLogicUrl.
dailyUpdateUrl** Opcional 'https://dsp.example/bid/custom-bikes/update' Es la URL que muestra un JSON para actualizar los atributos del grupo de intereses. (consulta Cómo actualizar el grupo de intereses).
trustedBiddingSignalsUrl** Opcional 'https://dsp.example/trusted/bidding-signals' Es la URL base para las solicitudes de par clave-valor al servidor de confianza del ofertante.
trustedBiddingSignalsKeys Opcional ['key1', 'key2' ...] Son claves para solicitudes al servidor de confianza de par clave-valor.
userBiddingSignals Opcional {...} Son metadatos adicionales que el propietario puede usar durante las ofertas.
ads Opcional* [bikeAd1, bikeAd2, bikeAd3] Anuncios que se podrían renderizar para este grupo de intereses.
adComponents Opcional [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] Componentes para anuncios compuestos por varias piezas.

* Todas las propiedades son opcionales, excepto owner y name. Las propiedades biddingLogicUrl y ads son opcionales, pero obligatorias para participar en una subasta. Puede haber casos de uso para crear un grupo de intereses sin estas propiedades: por ejemplo, el propietario de un grupo de intereses podría querer agregar un navegador a un grupo de intereses para una campaña que aún no se publica o para algún otro uso futuro, o es posible que se haya quedado sin presupuesto publicitario de forma temporal.

** Las URLs biddingLogicUrl, biddingWasmHelperUrl, dailyUpdateUrl y trustedBiddingSignalsUrl deben tener el mismo origen que el propietario. Las URLs ads y adComponents no tienen esa restricción.

Actualiza los atributos del grupo de intereses

dailyUpdateUrl especifica un servidor web que muestra un JSON que define las propiedades del grupo de intereses, que corresponde al objeto del grupo de intereses que se pasa a navigator.joinAdInterestGroup(). Esto proporciona un mecanismo para que el propietario del grupo actualice periódicamente los atributos del grupo de intereses. En la implementación actual, se pueden cambiar los siguientes atributos:

  • biddingLogicUrl
  • biddingWasmHelperUrl
  • trustedBiddingSignalsUrl
  • trustedBiddingSignalsKeys
  • ads
  • priority

No se reemplazará ningún campo que no se especifique en el archivo JSON (solo se actualizarán los campos especificados en el archivo JSON), mientras que llamar a navigator.joinAdInterestGroup() reemplazará cualquier grupo de intereses existente.

Las actualizaciones se realizan de la mejor manera posible y pueden fallar en las siguientes condiciones:

  • Tiempo de espera de la solicitud de red (actualmente, 30 segundos).
  • Hay otro error de red.
  • Error de análisis de JSON.

Las actualizaciones también se pueden cancelar si se dedicó demasiado tiempo continuo a la actualización, aunque esto no impone ningún límite de frecuencia en las actualizaciones canceladas (restantes). Las actualizaciones tienen un límite de frecuencia de una por día como máximo. Las actualizaciones que no se realizan correctamente debido a errores de red se vuelven a intentar después de una hora, y las que no se realizan correctamente debido a una desconexión de Internet se vuelven a intentar inmediatamente después de la reconexión.

Actualizaciones manuales

Las actualizaciones de los grupos de intereses que pertenecen al origen de la trama actual se pueden activar manualmente a través de navigator.updateAdInterestGroups(). El límite de frecuencia evita que las actualizaciones se produzcan con demasiada frecuencia: las llamadas repetidas a navigator.updateAdInterestGroups() no hacen nada hasta que finaliza el período del límite de frecuencia (actualmente, un día). El límite de frecuencia se restablece si se vuelve a llamar a navigator.joinAdInterestGroup() para el mismo grupo de intereses owner y name.

Actualizaciones automáticas

Todos los grupos de intereses cargados para una subasta se actualizan automáticamente después de que se completa una subasta, sujetos a los mismos límites de tarifas que las actualizaciones manuales. Para cada propietario que tenga al menos un grupo de intereses que participe en una subasta, es como si se llamara a navigator.updateAdInterestGroups() desde un iframe cuyo origen coincida con ese propietario.

Especifica anuncios para un grupo de intereses

Los objetos ads y adComponents incluyen una URL para una creatividad de anuncio y, de manera opcional, metadatos arbitrarios que se pueden usar en el momento de la oferta. Por ejemplo:

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

¿Cómo realizan ofertas los compradores?

La secuencia de comandos en biddingLogicUrl que proporciona el propietario de un grupo de intereses debe incluir una función generateBid(). Cuando un vendedor de espacio publicitario llama a navigator.runAdAuction(), se llama a la función generatedBid() una vez por cada uno de los grupos de interés de los que es miembro el navegador, si se invita al propietario del grupo de interés a ofertar. En otras palabras, se llama a generateBid() una vez por cada anuncio candidato. El vendedor proporciona una propiedad decisionLogicUrl en el parámetro de configuración de la subasta que se pasa a navigator.runAdAuction(). El código de esta URL debe incluir una función scoreAd(), que se ejecuta para cada ofertante en la subasta, para calificar cada una de las ofertas que muestra generateBid().

La secuencia de comandos en biddingLogicUrl que proporciona un comprador de espacio publicitario debe incluir una función generateBid(). Se llama a esta función una vez por cada anuncio candidato. runAdAuction() verifica cada anuncio de forma individual, junto con su oferta y metadatos asociados, y, luego, le asigna una puntuación numérica de deseabilidad.

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

generateBid() toma los siguientes argumentos:

  • interestGroup
    Es el objeto que el comprador de anuncios pasa a joinAdInterestGroup(). (El grupo de intereses se puede actualizar a través de dailyUpdateUrl).

  • auctionSignals
    Es una propiedad del argumento auction config que el vendedor de espacio de anuncios pasa a navigator.runAdAuction(). Esto proporciona información sobre el contexto de la página (como el tamaño del anuncio y el ID del publicador), el tipo de subasta (precio primero o segundo) y otros metadatos.

  • perBuyerSignals
    Al igual que con auctionSignals, es una propiedad del argumento configuración de subasta que el vendedor pasa a navigator.runAdAuction(). Esto puede proporcionar indicadores contextuales del servidor del comprador sobre la página, si el vendedor es una SSP que realiza una llamada de ofertas en tiempo real a los servidores del comprador y devuelve la respuesta, o si la página del publicador se comunica directamente con el servidor del comprador. Si es así, es posible que el comprador desee verificar una firma criptográfica de esos indicadores dentro de generateBid() como protección contra la manipulación.

  • trustedBiddingSignals
    Un objeto cuyas claves son el trustedBiddingSignalsKeys del grupo de intereses y cuyos valores se muestran en la solicitud trustedBiddingSignals.

  • browserSignals
    Es un objeto que construye el navegador, que puede incluir información sobre el contexto de la página (como el hostname de la página actual, que el vendedor podría falsificar) y datos del grupo de intereses (como un registro de cuándo el grupo ganó una subasta anteriormente, para permitir el límite de frecuencia en el dispositivo).

El objeto browserSignals tiene las siguientes propiedades:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  joinCount: 3,
  bidCount: 17,
  prevWins: [[time1,ad1],[time2,ad2],...],
  wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
  dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}

Para calcular un valor bid, el código en generateBid() puede usar las propiedades de los parámetros de la función. Por ejemplo:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
    ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    ...
  }
}

generateBid() muestra un objeto con cuatro propiedades:

  • ad
    Metadatos arbitrarios sobre el anuncio, como la información que el vendedor espera obtener sobre esta oferta o creatividad del anuncio. El vendedor](/resources/glossary#ssp) usa esta información en su subasta y en la decisión de la creatividad del anuncio. El vendedor usa esta información en su subasta y lógica de decisión.

  • bid
    Es una oferta numérica que ingresará a la subasta. El vendedor debe poder comparar las ofertas de diferentes compradores, por lo que las ofertas deben estar en una unidad que elija el vendedor (p.ej., "USD por mil"). Si la oferta es cero o negativa, este grupo de intereses no participará en la subasta del vendedor. Con este mecanismo, el comprador puede implementar cualquier regla del anunciante para determinar dónde pueden aparecer sus anuncios o no.

  • render
    Es una URL o una lista de URLs que se usarán para renderizar la creatividad si esta oferta gana la subasta. (consulta Anuncios compuestos por varias piezas en la explicación de la API). El valor debe coincidir con el renderUrl de uno de los anuncios definidos para el grupo de intereses.

  • adComponents
    Es una lista opcional de hasta 20 componentes para anuncios compuestos por varias piezas, que se toma de la propiedad adComponents del argumento del grupo de intereses que se pasa a navigator.joinAdInterestGroup().

Cómo solicitarle a un navegador que salga de un grupo de intereses

El propietario del grupo de intereses puede solicitar que se quite un navegador de un grupo de intereses. En otras palabras, se le solicita al navegador que quite el grupo de intereses de la lista de los de los que es miembro.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

Si un usuario regresa al sitio que le pidió al navegador que agregara un grupo de interés, el propietario del grupo de interés puede llamar a la función navigator.leaveAdInterestGroup() para solicitar que el navegador quite el grupo de interés. El código de un anuncio también puede llamar a esta función para su grupo de intereses.

3. El usuario visita un sitio que vende espacio publicitario

Ilustración de una persona que visita un sitio web de noticias en un navegador de su laptop. El sitio tiene un espacio publicitario vacío.

Más tarde, el usuario visita un sitio que vende espacio publicitario, en este ejemplo, un sitio web de noticias. El sitio tiene un inventario de anuncios, que vende de forma programática mediante ofertas en tiempo real.

4. Se ejecuta una subasta de anuncios en el navegador

Ilustración de una persona que ve un sitio web de noticias en un navegador de su laptop. Se está realizando una subasta de anuncios con la API de Protected Audience.

Sección explicativa: Los vendedores ejecutan subastas integradas en el dispositivo

Es probable que la SSP del publicador o el publicador en sí ejecuten la subasta de anuncios. El objetivo de la subasta es seleccionar el anuncio más adecuado para un solo espacio publicitario disponible en la página actual. La subasta tiene en cuenta los grupos de intereses de los que es miembro el navegador, junto con los datos de los compradores de espacio publicitario y los vendedores de los servicios de par clave-valor.

El vendedor de espacio de anuncios 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': ...,
      ...
    },
    ...
  ]
};

const auctionResultPromise = navigator.runAdAuction(auctionConfig);

runAdAuction() muestra 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 protegido 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 numérica de deseabilidad.

auctionConfig propiedades

Propiedad Obligatorio Ejemplo Rol
seller Obligatorio 'https://ssp.example' Es el origen del vendedor.
decisionLogicUrl Obligatorio 'https://ssp.example/auction-decision-logic.js' Es la URL de JavaScript del worklet de subasta.
trustedScoringSignalsUrl Opcional 'https://ssp.example/scoring-signals' Es la URL del servidor de confianza del vendedor.
interestGroupBuyers* Obligatorio ['https://dsp.example', 'https://buyer2.example', ...] Origen de todos los propietarios de grupos de interés a los que se les pidió ofertar en la subasta.
auctionSignals Opcional {...} Información del vendedor sobre el contexto de la página, el tipo de subasta, etcétera
sellerSignals Opcional {...} Información basada en la configuración del publicador, la realización de una solicitud de anuncio contextual, etcétera
sellerTimeout Opcional 100 Es el tiempo de ejecución máximo (ms) de la secuencia de comandos scoreAd() del vendedor.
perBuyerSignals Opcional {'https://dsp.example': {...},
  'https://another-buyer.example': {...},
...}		 Indicadores contextuales sobre la página de cada comprador específico, desde su servidor.
perBuyerTimeouts Opcional 50 Es el tiempo de ejecución máximo (en ms) de las secuencias de comandos generateBid() de un comprador en particular.
componentAuctions Opcional [{'seller': 'https://www.some-other-ssp.com',
  'decisionLogicUrl': ..., ...},
  ...]		 Configuraciones adicionales para las subastas de componentes.

* El vendedor puede especificar interestGroupBuyers: '*' para permitir que todos los grupos de intereses realicen ofertas. Luego, los anuncios se aceptan o rechazan en función de 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.

** additionalBids no es compatible con la implementación actual de Protected Audience. Para obtener más información, lee la sección Participantes de la subasta en la explicación de Protected Audience.

¿Cómo se seleccionan los anuncios?

El código en decisionLogicUrl (una propiedad del objeto de configuración de subasta que se pasa a runAdAuction()) debe incluir una función scoreAd(). Se ejecuta una vez para cada anuncio para determinar su atractivo.

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

scoreAd() toma los siguientes argumentos:

  • adMetadata
    Son metadatos arbitrarios que proporciona el comprador.
  • bid
    Un valor de oferta numérico.
  • auctionConfig
    Es el objeto de configuración de la subasta que se pasó a navigator.runAdAuction().
  • trustedScoringSignals
    Son valores recuperados en el momento de la subasta desde el servidor de confianza del vendedor, que representan la opinión del vendedor sobre el anuncio.
  • browserSignals
    Es un objeto que construye el navegador, incluida la información que este conoce y que el guion 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 /* Data-Version value 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 su lógica scoreAd() es rechazar cualquier anuncio que no pueda superar al ganador contextual.

5. El vendedor y los compradores participantes reciben datos en tiempo real del servicio de par clave-valor.

Ilustración de una persona que ve un sitio web de noticias en un navegador de su laptop. Se está ejecutando una subasta de anuncios con la API de Protected Audience, y un participante obtiene datos del servicio de par clave-valor.

Sección explicativa: Cómo recuperar datos en tiempo real del servicio de par clave-valor de Protected Audience.

Durante una subasta de anuncios, el vendedor de espacio publicitario puede obtener datos en tiempo real sobre creatividades de anuncios específicas si realiza una solicitud a un servicio de par clave-valor con la propiedad trustedScoringSignalsUrl del argumento configuración de subasta que se pasa a navigator.runAdAuction(), junto con las claves de las propiedades renderUrl de todas las entradas de los campos ads y adComponents de todos los grupos de intereses de la subasta.

Del mismo modo, un comprador de espacio de anuncios puede solicitar datos en tiempo real del servicio de par clave-valor con las propiedades trustedBiddingSignalsUrl y trustedBiddingSignalsKeys del argumento del grupo de intereses que se pasa a navigator.joinAdInterestGroup().

Cuando se llama a runAdAuction(), el navegador realiza una solicitud al servidor de confianza de cada comprador de anuncios. La URL de la solicitud podría verse de la siguiente manera:

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
  • La URL base proviene de trustedBiddingSignalsUrl.
  • El navegador proporciona hostname.
  • El valor de keys se toma de trustedBiddingSignalsKeys.

La respuesta a esta solicitud es un objeto JSON que proporciona valores para cada una de las claves.

6. Se muestra el anuncio ganador

Ilustración de una persona que ve un sitio web de noticias en un navegador de su laptop. Se muestra un anuncio de una bicicleta (20% de descuento) con un candado arriba para mostrar que el anuncio se muestra en un marco protegido.

Sección explicativa: Los navegadores renderizan el anuncio ganador

Como se describió anteriormente, la promesa que muestra runAdAuction() se resuelve en una URN que se pasa a un marco de seguridad para la renderización, y el sitio muestra el anuncio ganador.

7. Se informa el resultado de la subasta

Sección explicativa: Informes a nivel del evento (por el momento)

El vendedor informa el resultado

Sección explicativa: Informes del vendedor sobre la renderización

El código JavaScript del vendedor proporcionado en decisionLogicUrl (que también proporcionó scoreAd()) puede incluir una función reportResult() para informar el resultado de la subasta.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Los argumentos que se pasan a esta función son los siguientes:

  • auctionConfig
    Es el objeto de configuración de la subasta que se pasó a navigator.runAdAuction().

  • browserSignals
    Es un objeto que construye el navegador y que proporciona información sobre la subasta. Por ejemplo:

    {
  'topWindowHostname': 'publisher.example',
  'interestGroupOwner': 'https://dsp.example',
  'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
  'bid:' <bidValue>,
  'desirability': <winningAdScore>
}

El valor que se muestra de esta función se usa como argumento sellerSignals para la función reportWin() del ofertante ganador.

El ofertante ganador informa el resultado

Sección explicativa: Informes del comprador sobre eventos de renderización y de anuncios

El código JavaScript del ofertante ganador (que también proporcionó generateBid()) puede incluir una función reportWin() para informar el resultado de la subasta.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

Los argumentos que se pasan a esta función son los siguientes:

  • auctionSignals y perBuyerSignals
    Los mismos valores que se pasan a generateBid() para el ofertante ganador.
  • sellerSignals
    Es el valor que se muestra de reportResult(), que le brinda al vendedor la oportunidad de pasar información al comprador.

  • browserSignals
    Es un objeto que construye el navegador y que proporciona información sobre la subasta. Por ejemplo:

    {
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid:' <bidValue>
}

Implementación temporal de los informes de pérdidas o ganancias

Hay dos métodos disponibles temporalmente en Chrome para los informes de subastas:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Cada uno de estos métodos toma un solo argumento: una URL para recuperar después de que se complete la subasta. Se puede llamar a estas funciones varias veces, en scoreAd() y generateBid(), con diferentes argumentos de URL.

Chrome solo envía informes de pérdida o ganancia de depuración cuando una subasta se ejecuta hasta completarse. Si se cancela una subasta (por ejemplo, debido a una navegación nueva), no se generarán informes.

Estos métodos están disponibles de forma predeterminada en Chrome. Para poder probar los métodos, habilita todas las APIs de privacidad en los anuncios en chrome://settings/adPrivacy. Si ejecutas Chrome con marcas de línea de comandos para habilitar Protected Audience, deberás habilitar los métodos de forma explícita, lo que implica incluir la marca BiddingAndScoringDebugReportingAPI. Si no se habilita la marca, los métodos seguirán disponibles, pero no harán nada.

8. Se informa un clic en el anuncio

Ilustración que muestra a una persona haciendo clic en un anuncio de una bicicleta, dentro de un marco cercado, en un sitio web de noticias, con los datos de informes que se envían al vendedor y a los compradores.

Se informa un clic en un anuncio renderizado en un marco delimitado. Para obtener más información sobre cómo podría funcionar, consulta Informes de anuncios de marcos delimitados.


En el siguiente diagrama, se describe cada etapa de una subasta de anuncios de Protected Audience:

Ilustración que proporciona una descripción general de cada etapa de una subasta de anuncios de Protected Audience


¿Cuál es la diferencia entre Protected Audience y TURTLEDOVE?

Protected Audience es el primer experimento que se implementará en Chromium dentro de la familia de propuestas de TURTLEDOVE.

Protected Audience sigue los principios de alto nivel de TURTLEDOVE. Parte de la publicidad en línea se basa en mostrar un anuncio a una persona potencialmente interesada que ya interactuó con el anunciante o la red de publicidad. Históricamente, esto funcionó porque el anunciante reconoció a una persona específica mientras navegaba por los sitios web, una preocupación fundamental de privacidad en la Web actual.

El esfuerzo de TURTLEDOVE consiste en ofrecer una nueva API para abordar este caso de uso y, al mismo tiempo, ofrecer algunos avances clave en materia de privacidad:

  • El navegador, no el anunciante, contiene la información sobre lo que el anunciante cree que le interesa a una persona.
  • Los anunciantes pueden publicar anuncios en función de un interés, pero no pueden combinar ese interés con otra información sobre una persona, en particular, quién es o qué página visita.

Protected Audience surgió de TURTLEDOVE y una colección de propuestas relacionadas para realizar modificaciones que brindaran un mejor servicio a los desarrolladores que usarían la API:

  • En SPARROW, Criteo propuso agregar un modelo de servicio ("administrador de acceso") que se ejecute en un entorno de ejecución confiable (TEE). Protected Audience incluye un uso más limitado de los TEE para la búsqueda de datos en tiempo real y los informes agregados.
  • Las propuestas de TERN de NextRoll y PARRROT de Magnite describieron los diferentes roles que tenían los compradores y vendedores en la subasta integrada en el dispositivo. El flujo de ofertas o puntuación de anuncios de Protected Audience se basa en este trabajo.
  • Las modificaciones de TURTLEDOVE basadas en el resultado y a nivel del producto de RTB House mejoraron el modelo de anonimato y las capacidades de personalización de la subasta integrada en el dispositivo.
  • PARAKEET es la propuesta de Microsoft para un servicio de anuncios similar a TURTLEDOVE que se basa en un servidor proxy que se ejecuta en un TEE entre el navegador y los proveedores de AdTech para anonimizar las solicitudes de anuncios y aplicar propiedades de privacidad. Protected Audience no adoptó este modelo de proxy. Estamos alineando las APIs de JavaScript para PARAKEET y Protected Audience para respaldar el trabajo futuro que combine aún más las mejores funciones de ambas propuestas.

Protected Audience aún no impide que la red publicitaria de un sitio web sepa qué anuncios ve una persona. Esperamos modificar la API para que sea más privada con el tiempo.

¿Qué configuración de navegador está disponible?

Los usuarios pueden ajustar su participación en las pruebas de Privacy Sandbox en Chrome habilitando o inhabilitando la configuración de nivel superior en chrome://settings/adPrivacy. Durante las pruebas iniciales, las personas podrán usar esta configuración de Privacy Sandbox de alto nivel para inhabilitar Protected Audience. Chrome planea permitir que los usuarios vean y administren la lista de grupos de interés a los que se agregaron en los sitios web que visitaron. Al igual que con las tecnologías de Privacy Sandbox, la configuración del usuario puede evolucionar con los comentarios de los usuarios, los reguladores y otras partes.

Seguiremos actualizando la configuración disponible en Chrome a medida que avance la propuesta de Protected Audience, según las pruebas y los comentarios. En el futuro, planeamos ofrecer una configuración más detallada para administrar Protected Audience y los datos asociados.

Los llamadores de API no pueden acceder a la membresía del grupo cuando los usuarios navegan en modo Incógnito, y la membresía se quita cuando los usuarios borran sus datos de sitios.



Interactúa y comparte comentarios

Obtenga asistencia

Para hacer una pregunta sobre tu implementación, la demo o la documentación, haz lo siguiente:

Si tienes errores y problemas con la implementación de la API de Protected Audience en Chrome, haz lo siguiente: * Consulta los problemas existentes informados para la API. * Informa un problema nuevo en crbug.com/new.

Mantente al día

Más información

Foto de Ray Hennessy en Unsplash.