API de Protected Audience: Guía para desarrolladores

Guía para desarrolladores sobre subastas de anuncios integradas en el dispositivo para publicar públicos personalizados y de remarketing, sin seguimiento de terceros entre sitios.

Actualización: Se cambió el nombre de FLEDGE a la API de Protected Audience. Para obtener más información sobre este cambio, consulta esta entrada de blog.

Punto clave: La prueba de origen de medición y relevancia de Privacy Sandbox finalizó el 20 de septiembre de 2023, y las APIs ya están disponibles para el 99% de los usuarios de Chrome, y se cerró la inscripción en la prueba de origen. Para mantenerte al tanto del porcentaje de usuarios para los que está habilitada cada API, consulta los gráficos de estado de Chrome.

Si es la primera vez que usas la API de Protected Audience, lee la Descripción general de la API de Protected Audience para obtener una explicación detallada de la API.

Esta publicación se redactó para los desarrolladores como referencia técnica de la iteración más reciente de la API experimental de Protected Audience. Hay una demostración disponible de una implementación básica de la API de Protected Audience, al igual que las referencias de la API para compradores y vendedores de anuncios.

Estado de implementación

• La propuesta de la API de Protected Audience ahora cambiará a disponibilidad general. Formula preguntas y sigue la conversación.
• El estado de las funciones pendientes de la API de Protected Audience detalla los cambios y las mejoras en la API y las funciones de la API de Protected Audience.
• Estado de la luz intermitente
• Estado de la plataforma de Chrome de la API de Protected Audience: Específico de la API de Protected Audience en Chrome
• Estado de la plataforma de Chrome de la API de Ads: Es un conjunto de APIs para facilitar la publicidad, como la API de Protected Audience, los temas, los marcos protegidos y los informes de atribución.

Para recibir notificaciones sobre cambios de estado en la API, únete a la lista de distribución para desarrolladores.

¿Qué es la API de Protected Audience?

La API de Protected Audience es una API de Privacy Sandbox diseñada para publicar casos de uso de remarketing y públicos personalizados, de modo que terceros no puedan usarla para hacer un seguimiento del comportamiento de navegación de los usuarios en los sitios. La API permite que el navegador use las subastas integradas en el dispositivo para elegir anuncios relevantes para los sitios web que el usuario visitó anteriormente.

La API de Protected Audience es el primer experimento que se implementa en Chromium dentro de la familia de propuestas TURTLEDOVE.

Prueba la API de Protected Audience

Referencia de la API disponible

Este documento es una descripción general de la API de Protected Audience. Si buscas métodos y parámetros de API específicos, haz lo siguiente:

• Guía para compradores de joinAdInterestGroup() y generateBid().
• Guía para vendedores de la API de Protected Audience runAdAuction()
• Guía para compradores de reportWin() y guía para vendedores de reportResult()
• Soluciona problemas relacionados con la API de Protected Audience

También puedes consultar las prácticas recomendadas sobre la latencia de las subastas de anuncios de la API de Protected Audience.

Demostración de la API de Protected Audience

Puedes encontrar una explicación de una implementación básica de la API de Protected Audience en sitios de anunciantes y publicadores en protection-audience-demo.web.app/.

Mira esta implementación de extremo a extremo para obtener información sobre cómo funciona el código de demostración de la API de Protected Audience y cómo usar las Herramientas para desarrolladores de Chrome para la depuración.

Prueba con chrome://flags o marcas de función

Puedes probar la API de Protected Audience para un solo usuario en la versión beta 101.0.4951.26 de Chrome y versiones posteriores en computadoras de escritorio:

• Habilita chrome://flags/#privacy-sandbox-ads-apis.
• Configura marcas desde la línea de comandos. Puedes encontrar la lista completa de las marcas de la API de Protected Audience disponibles en la Búsqueda de código fuente público de Chromium.

Renderiza anuncios en iframes o marcos vallados

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

Si deseas usar <fencedframe> para renderizar anuncios, haz lo siguiente:

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

Si deseas usar <iframe> para renderizar anuncios, haz lo siguiente:

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

Incluye la marca BiddingAndScoringDebugReportingAPI para habilitar los métodos temporales de generación de informes de pérdida o ganancia de la depuración.

Nota: Esta es una versión en curso de la API de Protected Audience para pruebas anticipadas. No debe considerarse completa ni indicativa de la implementación final. El progreso y el estado de la API de Protected Audience se analizan en las reuniones regulares de WICG. El cronograma de Privacy Sandbox proporciona cronogramas de implementación para la API de Protected Audience y otras APIs de Privacy Sandbox.

Funciones admitidas

La API de Protected Audience detrás de las marcas de función en Chromium es un primer experimento para probar las siguientes funciones de la API de Protected Audience:

• Grupos de interés: El navegador los almacena, con metadatos asociados para configurar la oferta y la renderización de anuncios.
• Ofertas en el dispositivo por compradores (DSP o anunciante): Se basan en indicadores del vendedor y grupos de interés almacenados.
• Selección de anuncios 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 Fenced Frames: Se permite el acceso a la red y el registro para la renderización de anuncios.

Obtén más información sobre la compatibilidad y las restricciones de las funciones en la explicación de la API de Protected Audience.

Permisos del grupo de interés

La configuración predeterminada para la implementación actual de la API de Protected Audience consiste en permitir llamar a joinAdInterestGroup() desde cualquier parte de una página, incluso desde iframes multidominio.

En el futuro, una vez que los propietarios de los sitios hayan tenido tiempo de actualizar las políticas de permisos de sus iframes multidominio, el plan es inhabilitar las llamadas de iframes multidominio.

Servicio de par clave-valor

Para admitir la subasta de anuncios de la API de Protected Audience, el navegador puede acceder a un servicio de par clave-valor para recuperar información en tiempo real que admita la subasta de anuncios de la API de Protected Audience. Esta información se puede usar de varias maneras:

• Es posible que los compradores quieran calcular el presupuesto restante en una campaña publicitaria.
• Es posible que los vendedores deban verificar que las creatividades de anuncios cumplan con las políticas de los publicadores.

El código de servicio del par clave-valor de la API de Protected Audience ahora está disponible. Consulte la entrada de blog sobre el anuncio para conocer la actualización del estado.

Para las pruebas iniciales, se presentó un modelo de “trae tu propio servidor”. A largo plazo, las tecnologías publicitarias deberán usar los servicios de clave-valor de la API de Protected Audience de código abierto que se ejecutan en entornos de ejecución confiables.

Consulta la entrada de blog sobre los servicios de la API de Protected Audience para conocer las actualizaciones del cronograma. Antes de que se lleve a cabo esta transición, se notificará a los desarrolladores que deben comenzar a realizar pruebas y adopción.

Detecta la compatibilidad de funciones

Antes de usar la API, verifica si es compatible con el navegador 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');

Precaución: La compatibilidad de funciones en la página actual no garantiza que se pueda usar la API. Es posible que el usuario haya inhabilitado la API en la configuración del navegador o que tenga otra configuración que impida que se use la API. Para proteger la privacidad del usuario, no hay forma de verificar esto de manera programática.

¿Cómo funciona la API de Protected Audience?

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

Advertencia: No todas las funciones descritas en esta publicación se implementaron (o implementaron por completo) en la versión de la API de Protected Audience que se está probando en Chrome. En Pruebas con marcas de función, se explica qué funciones de la API de Protected Audience están disponibles actualmente para realizar pruebas en Chrome cuando se ejecutan desde la línea de comandos.

Las funciones de la API de Protected Audience se agregarán con el tiempo a medida que avance el trabajo en la implementación.

1. Un usuario visita el sitio de un anunciante.

Imagina que un usuario visita el sitio web de un fabricante de bicicletas personalizado (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

La plataforma orientada a la demanda (DSP) del anunciante (o el propio anunciante) llama a navigator.joinAdInterestGroup() para solicitar 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 interés (en este caso, la DSP) será un comprador en la subasta de anuncios de la API de Protected Audience. El navegador almacena la membresía del grupo de interés en el dispositivo del usuario, y no se comparte con el proveedor del navegador ni con nadie más.

• Lee la explicación de la API de Protected Audience: Grupos de interés de los registros de los navegadores.
• Lee la guía de API: Los compradores y las DSP, obtén información para joinAdInterestGroup() y generar ofertas.

Nota: El origen del contexto de llamada para joinAdInterestGroup() debe coincidir con el origen del propietario del grupo de interés. Se debe llamar a joinAdInterestGroup() desde un iframe que pertenezca al propietario del grupo de interés (por ejemplo, desde una DSP). Si el origen del documento actual es el mismo que el propietario del grupo de interés (por ejemplo, un sitio web con sus propios grupos de intereses), no se necesita un iframe.

Cómo especificar anuncios para un grupo de interés

Los objetos ads y adComponents incluyen una URL para la creatividad del 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?

Se llama a generateBid() para cada grupo de interés al que pertenece el navegador (si se invita al propietario a ofertar).

Lee la documentación para desarrolladores de generatedBid().

3. El usuario visita un sitio que vende espacio publicitario

Luego, el usuario visita un sitio que vende espacios publicitarios; en este ejemplo, un sitio web de noticias. El sitio tiene inventario de anuncios que vende de manera programática con ofertas en tiempo real.

4. Se ejecuta una subasta de anuncios en el navegador

Es probable que la subasta de anuncios la ejecute el proveedor del proveedor (SSP) del publicador o el propio publicador. El propósito de la subasta es seleccionar el anuncio más adecuado para un único espacio publicitario disponible en la página actual. La subasta tiene en cuenta los grupos de intereses a los que pertenece el navegador, junto con los datos de los compradores de espacios publicitarios y los vendedores de los servicios de par clave-valor.

• Lee la explicación de la API de Protected Audience: Los vendedores ejecutan subastas integradas en el dispositivo
• Lee la guía de API: Los vendedores pueden obtener más información sobre runAdAuction() y las prácticas recomendadas para la latencia de las subastas de anuncios.

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

Durante una subasta de anuncios, el vendedor puede solicitar datos en tiempo real sobre creatividades de anuncios específicas mediante una solicitud a su servicio de par clave-valor. El vendedor puede solicitar esta información durante runAdAuction() a través de la propiedad trustedScoringSignalsUrl, junto con las claves de las propiedades renderUrl de todas las entradas en los campos ads y adComponents de todos los grupos de intereses en la subasta.

Un comprador puede solicitar datos en tiempo real de su servicio de par clave-valor mediante las propiedades trustedBiddingSignalsUrl y trustedBiddingSignalsKeys del argumento de grupo de interés que se pasó 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 así:

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2

• La URL base proviene de trustedBiddingSignalsUrl.
• El navegador proporciona el hostname.
• El valor keys se toma de trustedBiddingSignalsKeys.

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

• Lee la explicación de la API de Protected Audience: Cómo recuperar datos en tiempo real del servicio de clave-valor de la API de Protected Audience.
• Lee el servicio de clave-valor de la API de Protected Audience en código abierto.

Punto clave: Durante la fase experimental inicial de prueba de la API de Protected Audience, trustedBiddingSignalsUrl debe tener el mismo origen que el propietario del grupo de interés. Obtén más información en Trae tu propio servidor.

6. Se muestra el anuncio ganador

La promesa que devuelve runAdAuction() se resuelve en un objeto de configuración de marco vallado (FencedFrameConfig) cuando la marca resolveToConfig se establece en true en la configuración de la subasta. Un marco vallado usa la configuración del marco para navegar por el marco al anuncio ganador, pero la URL del anuncio no es visible para la incorporación del marco.

Nota: El objeto FencedFrameConfig solo se muestra cuando la marca resolveToConfig se establece en true en la configuración de la subasta. Si la marca no está configurada o es false, se mostrará una URN opaca que solo se puede renderizar en un iframe.

El objeto de configuración de marcos vallados está disponible a partir de M114. Para obtener más información sobre el objeto FencedFrameConfig, consulta el artículo del blog de Chrome.

• Lee la explicación de la API de Protected Audience: Los navegadores renderizan el anuncio ganador

7. Se registra el resultado de la subasta

El plan a largo plazo es permitir que el navegador informe los resultados de la subasta para el vendedor y los compradores mediante las APIs de Private Aggregation.

Como mecanismo de informe temporal a nivel del evento, el código que implementa reportResult() para el vendedor y reportWin() para el ofertante ganador puede llamar a la función sendReportTo(). Esto toma un solo argumento: una cadena que representa una URL que se recupera después de que finaliza la subasta, que codifica la información a nivel del evento que se debe informar.

• Lee la guía de API: Obtén más información sobre los informes de vendedores y compradores.

8. Se informa un clic en el anuncio

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

---

En este diagrama, se describe cada etapa de una subasta de la API de Protected Audience.

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

La API de Protected Audience es el primer experimento que se implementa en Chromium dentro de la familia de propuestas TURTLEDOVE.

La API de 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 interactuó anteriormente con el anunciante o la red de publicidad. Históricamente, esto ha funcionado porque el anunciante reconoció a una persona específica mientras navegaba por sitios web, una preocupación central de privacidad en la Web actual.

El objetivo de TURTLEDOVE es ofrecer una nueva API para abordar este caso de uso y, al mismo tiempo, algunos avances clave en la 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 combinarlo con otra información sobre una persona, en particular, quién es o qué página está visitando.

La API de Protected Audience surgió a partir de TURTLEDOVE y una colección de propuestas de modificaciones relacionadas para ofrecer mejores resultados a los desarrolladores que usarían la API:

• En SPARROW: Criteo propuso agregar un modelo de servicio ("Gatekeeper") que se ejecuta en un entorno de ejecución de confianza (TEE). La API de 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 y PARRROT de NextRoll describieron las diferentes funciones que tenían los compradores y vendedores en la subasta integrada en el dispositivo. El flujo de puntuación/oferta de anuncios de la API de Protected Audience se basa en este trabajo.
• Las modificaciones basadas en resultados 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 de 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 tecnología publicitaria para anonimizar las solicitudes de anuncios y aplicar propiedades de privacidad. La API de Protected Audience no adoptó este modelo de proxy. Estamos alineando las APIs de JavaScript para PARAKEET y la API de Protected Audience a fin de respaldar el trabajo futuro para combinar aún más las mejores funciones de ambas propuestas.

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

¿Se puede usar la API de Topics con la API de Protected Audience?

Sí. Un tema observado para el usuario actual, proporcionado por la API de Topics, podría ser usado como información contextual por un vendedor o ofertante. Se podría incluir un tema en las siguientes propiedades:

• auctionSignals, una propiedad del objeto de configuración de la subasta que se pasa a navigator.runAdAuction()
• userBiddingSignals, una propiedad del objeto de configuración del grupo de interés que se pasa a navigator.joinAdInterestGroup()

Configuración disponible del navegador

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 este parámetro de configuración de Privacy Sandbox de alto nivel para inhabilitar la API de Protected Audience. Chrome planea permitir que los usuarios vean y administren la lista de grupos de intereses 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 personas.

Seguiremos actualizando los parámetros de configuración disponibles en Chrome en función de pruebas y comentarios. En el futuro, planeamos ofrecer una configuración más detallada para administrar la API de Protected Audience y los datos asociados.

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

¿El navegador almacena en caché los trabajos de Protected Audience?

El navegador almacena en caché los recursos que contienen los trabajos de Protected Audience (los de generación de ofertas y de informes del comprador, y los de informes y puntuación de anuncios del vendedor). Puedes usar el encabezado Cache-Control para controlar el comportamiento del almacenamiento en caché.

Interactúa y comparte comentarios

Cómo obtener asistencia

Para hacer preguntas y obtener asistencia con la implementación, la demostración o la documentación, sigue estos pasos:

• GitHub: Lee la explicación, plantea preguntas y sigue el debate.
• Demostración: Menciona un problema en el repositorio de código de demostración.
• Asistencia para desarrolladores: Haz preguntas y únete a debates en el repo de asistencia para desarrolladores de Privacy Sandbox. Selecciona la plantilla de problemas para la API de Protected Audience.
• Implementación de Chrome: Si tienes errores o problemas con la implementación de Chrome de la API de Protected Audience, puedes ver los problemas existentes o enviar un problema nuevo.

Si tienes preguntas más generales sobre cómo satisfacer tus necesidades con la API de Protected Audience, informa un problema en el repositorio de la API. También puedes analizar casos de uso de la industria en la guía Improving Web Advertising Business Group del W3C.

Usa el formulario de comentarios de Privacy Sandbox para compartir comentarios de forma privada con el equipo de Chrome fuera de los foros públicos.

Inhabilitación

¿Quieres inhabilitar la API de Protected Audience? Obtén información para bloquear el acceso a la API de Protected Audience como propietario del sitio o usuario individual.

Mantente al día

• Para recibir notificaciones sobre cambios en el estado de la API, únete a la lista de distribución para desarrolladores.
• Para seguir de cerca todos los debates en curso sobre la API, haz clic en el botón Mirar en la página de la API en GitHub. Esto requiere que tengas o crees una cuenta de GitHub.
• Para obtener actualizaciones generales sobre Privacy Sandbox, suscríbete al feed RSS [Progreso en Privacy Sandbox].
• Únete a las llamadas programadas para la API de Protected Audience (cada segunda semana). Todos son bienvenidos. Si deseas participar, primero asegúrate de unirte al WICG. Puedes participar activamente o solo escuchar.