API de Protected Audience: Guía para desarrolladores

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

Si no conoces la API de Protected Audience, consulta la descripción general de la API de Protected Audience para obtener una explicación de alto nivel de la API.

Esta publicación se redactó para los desarrolladores como referencia técnica Iteración reciente de la API experimental de Protected Audience. Una demostración de un La implementación de la API de Protected Audience está disponible, al igual que Referencias de la API para compradores y vendedores de anuncios.

Estado de implementació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 el remarketing y el uso de públicos personalizados de seguridad, diseñados de modo que terceros no puedan rastrearlo de navegación en sitios. La API habilita las subastas integradas en el dispositivo el navegador, 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 del TURTLEDOVE.

Prueba la API de Protected Audience

Referencia de API disponible

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

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

Demostración de la API de Protected Audience

Una explicación de la implementación básica de la API de Protected Audience en el anunciante y el publicador está disponible en protected-audience-demo.web.app/.

Mira esta implementación de extremo a extremo para aprender 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.

Probar esta API

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

Renderiza anuncios en iframes o marcos vallados

Los anuncios se pueden renderizar en un objeto <iframe> o <fencedframe>, dependiendo de marcas.

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

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

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

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

Incluye la marca BiddingAndScoringDebugReportingAPI para habilitar métodos temporales de generación de informes de pérdida/adquisición de la depuración.

Funciones admitidas

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

  • Grupos de interés: Almacenados por el navegador, con los metadatos asociados a configurar ofertas y renderización de anuncios.
  • Ofertas integradas en el dispositivo por parte de compradores (DSP o anunciante): Se basan en las los grupos de interés y los indicadores del vendedor.
  • 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 de marcos vallados temporalmente flexibilizada: con el acceso a la red y los registros permitidos para la renderización de anuncios.

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

Permisos del grupo de interés

La configuración predeterminada de la implementación actual de la API de Protected Audience es permitir las llamadas joinAdInterestGroup() desde cualquier parte de una página, incluso desde iframes multidominio.

En el futuro, cuando los propietarios de los sitios hayan tenido tiempo de actualizar sus las políticas de permisos de iframe, es inhabilitar las llamadas desde 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 clave-valor para recuperar información en tiempo real que admite la subasta de anuncios de la API de Protected Audience. Esta la información se puede utilizar de varias maneras:

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

El código de servicio del par clave-valor de la API de Protected Audience ya está disponible. Consulta la entrada de blog del anuncio para ver la actualización del estado.

Para las pruebas iniciales, un servidor “Trae tu propio servidor” se introdujo el modelo de AA. A largo plazo, las tecnologías publicitarias deberán usar Servicios de clave-valor de la API de Protected Audience de código abierto que se ejecutan en una ejecución confiable entornos de prueba.

Consulta la entrada de blog sobre los servicios de la API de Protected Audience. para las actualizaciones del cronograma. Enviaremos una notificación importante a los desarrolladores para comenzar y la adopción de la solución antes de que se lleve a cabo la transición.

Cómo detectar la compatibilidad con funciones

Antes de usar la API, comprueba 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');

¿Cómo funciona la API de Protected Audience?

En este ejemplo, un usuario navega por el sitio web de un fabricante de bicicletas personalizado y, luego, Visita un sitio web de noticias y le aparece un anuncio de una bicicleta nueva del fabricante.

Se agregarán funciones de la API de Protected Audience a medida que avance el trabajo de implementación.

1. Un usuario visita el sitio de un anunciante.

Una persona visita 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 personalizada (el anunciante) en este ejemplo) y pasa algún tiempo en la página del producto de un producto en bicicleta. Esto le proporciona al fabricante de bicicletas una remarketing.

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

Un usuario abre un navegador en su laptop y visita un sitio. JavaScript código para unirse a grupos de interés de anuncios se ejecuta en el navegador.

La plataforma orientada a la demanda (DSP) del anunciante (o el propio anunciante) llama navigator.joinAdInterestGroup() para solicitar al navegador que agregue un grupo de interés a la lista de grupos a los que pertenece el navegador.

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 pertenencia a un grupo de interés. en el dispositivo del usuario y no se comparte con el proveedor del navegador ni con ninguna otra persona.

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

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

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

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

3. El usuario visita un sitio que vende espacio publicitario.

Una persona visita un sitio web de noticias en un navegador de su laptop. El sitio tiene un espacio publicitario vacío.

Luego, el usuario visita un sitio que vende espacio publicitario. En este ejemplo, se publica sitio web. El sitio tiene inventario de anuncios que se vende de manera programática con con las ofertas en tiempo real.

4. Se ejecuta una subasta de anuncios en el navegador.

Una persona ve un sitio web de noticias en un navegador de su laptop. Se ejecuta una subasta de anuncios de la API de Protected Audience a fin de elegir un anuncio para el espacio publicitario disponible.

Es probable que la subasta de anuncios la ejecute el proveedor de proveedores del publicador. (SSP) o el propio publicador. El propósito de la subasta es seleccionar anuncio más adecuado para un solo espacio publicitario disponible en la página actual. El 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 Servicios de par clave-valor.

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

El usuario ve un sitio web de noticias en un navegador de su laptop. Un anuncio una subasta con la API de Protected Audience, y un participante obtiene datos del servicio de par clave-valor.

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

Un comprador puede solicitar datos en tiempo real de su servicio de par clave-valor usando las propiedades trustedBiddingSignalsUrl y trustedBiddingSignalsKeys de El argumento del grupo de interés se pasa a navigator.joinAdInterestGroup().

Cuando se llama a runAdAuction(), el navegador realiza una solicitud a cada anuncio servidor de confianza del comprador. 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 obtiene de trustedBiddingSignalsKeys.

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

6. Se muestra el anuncio ganador

Una persona ve un sitio web de noticias en un navegador de su laptop. Un anuncio un 20% de descuento en una bicicleta se muestra en un marco vallado seguro.

La promesa que muestra 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 utiliza la configuración del marco para navegar por el marco hasta el anuncio ganador, pero la URL del anuncio no es visible para la incorporación de marcos.

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

7. Se informa 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 compradores con las APIs de Private Aggregation

Como mecanismo temporal de informes a nivel del evento, el código que implementa Se pueden utilizar reportResult() para el vendedor y reportWin() para el ofertante ganador llama a la función sendReportTo(). Toma un solo argumento: una cadena que representa una URL que se recupera después de que se completa la subasta, que codifica la información a nivel del evento que se informará.

8. Se registra un clic en el anuncio

Una persona hace clic en el anuncio de una bicicleta incrustado con un marco cercado en un sitio web de noticias. Los datos del informe se envían al vendedor y a los compradores.

Se registra un clic en un anuncio renderizado en un marco vallado. Para obtener más información Consulta el Informe de anuncios de marcos vallados para saber cómo podría funcionar.

Una descripción general de cada etapa de una subasta de anuncios de la API de Protected Audience
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 del familia de propuestas TURTLEDOVE.

La API de Protected Audience sigue los principios de alto nivel de TURTLEDOVE. Cierta publicidad en línea tiene se basó en mostrar un anuncio a un usuario potencialmente interesado que interactuó previamente con el anunciante o la red de publicidad. Históricamente, esto ha tenido que el anunciante haya realizado al reconocer a una persona específica mientras navega por sitios web, una de las preocupaciones principales de privacidad en la Web actual.

El esfuerzo TURTLEDOVE consiste en ofrecer una nueva API para abordar este caso de uso a la vez que ofreces algunos avances clave en materia de privacidad:

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

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

  • En SPARROW: Criteo propuso agregar de un modelo de servicio (“Gatekeeper”) que se ejecuta en un entorno de ejecución confiable (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.
  • los campos TERN de NextRoll y PARRROT de Magnite describían los distintos roles que tenían los compradores y vendedores en la subasta integrada en el dispositivo. El flujo de puntuación/ofertas de anuncios de la API de Protected Audience se basa en este trabajo.
  • Basado en resultados de RTB House y a nivel del producto Las modificaciones de TURTLEDOVE mejoraron el modelo de anonimato y la personalización capacidades 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 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 políticas propiedades. La API de Protected Audience no adoptó este modelo de proxy. Traemos las APIs de JavaScript para PARAKEET y la API de Protected Audience en alineación, en compatibilidad con trabajo futuro para combinar aún más las mejores características de ambas propuestas.

La API de Protected Audience aún no impide que la red de publicidad de un sitio web sepa qué anuncios ve una persona. Esperamos modificar la API para que sea más privada con el paso del 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 usarse como información contextual por un vendedor u ofertante. Un tema podría incluirse en las siguientes propiedades:

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

Configuración del navegador disponible

Los usuarios pueden ajustar su participación en las pruebas de Privacy Sandbox en Chrome de la siguiente manera: habilitar o inhabilitar la configuración de nivel superior en chrome://settings/adPrivacy

Durante las pruebas iniciales, las personas podrán usar esta política Parámetro de configuración de la zona de pruebas para inhabilitar la API de Protected Audience. Chrome planea permitir que los usuarios vean y administrar la lista de grupos de interés a los que se agregaron en la Web los sitios 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 según las pruebas y los comentarios. En el futuro, planeamos ofrecer parámetros de configuración más detallados para administrar la API de Protected Audience y en los datos asociados.

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

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

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

Interactúa y comparte tus comentarios

Obtenga asistencia

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

Si tienes preguntas más generales sobre cómo satisfacer tus necesidades con la API de Protected Audience, consulta lo siguiente: informa un problema en el repositorio de la API. También puedes analizar casos de uso de la industria en el Mejora del grupo empresarial de Publicidad Web.

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? Aprende a hacer lo siguiente: bloquear el acceso a la API de Protected Audience, como propietario del sitio o usuario individual.

Mantente al día