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 que se publicará remarketing y públicos personalizados, diseñados para que terceros para realizar un seguimiento del comportamiento de navegación del usuario en los 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.

Protected Audience es el primer experimento que se implementa en Chromium dentro del 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?

Demostración de Protected Audience

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

El video de demostración se explica cómo funciona el código de demostración y se muestra cómo usar las Herramientas para desarrolladores de Chrome para la depuración de Protected Audience.

Participa en una prueba de origen de Protected Audience

Se inició una prueba de origen de Relevancia y medición de Privacy Sandbox está disponible en Chrome Beta 101.0.4951.26 y versiones posteriores en computadoras para Protected Audience Topics y APIs de Attribution Reporting.

Si quieres 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 las páginas que proporcionen un token de prueba válido; por ejemplo, para solicitar al navegador que se una a uno o más grupos de interés y, luego, ejecutar una subasta de anuncios para seleccionar y mostrar un anuncio.

La demostración 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 desees ejecutar el código de la API de Protected Audience:

  • Como metaetiqueta en la etiqueta <head>:

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

  • Como encabezado HTTP:

    Origin-Trial: TOKEN_GOES_HERE

  • Cuando proporcionas un token de manera programática, sucede lo siguiente:

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

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

Detalles de la prueba de origen del primer público protegido propuesto Brinda más detalles sobre los objetivos de la primera prueba y explica las funciones compatibles.

Probar esta API

Puedes probar Protected Audience para un solo usuario en Chrome Beta 101.0.4951.26 y versiones posteriores en una computadora de escritorio:

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

Renderiza anuncios en iframes o marcos vallados

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

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 los métodos temporales de generación de informes de pérdida/adquisición de la depuración.

Ejecutar Chromium con funciones experimentales se explica cómo configurar marcas cuando se ejecutan Chrome y otros navegadores basados en Chromium desde el comando línea. La lista completa de marcas de Protected Audience está disponible en Búsqueda de código de Chromium.

¿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 por primera vez para probar las siguientes funciones de la propuesta de Protected Audience:

  • Grupos de interés: Almacenados por el navegador, con metadatos asociados para configurar las ofertas de anuncios y la renderización.
  • Ofertas integradas en el dispositivo por parte de compradores (DSP o anunciante): Se basan en indicadores y grupos de interés almacenados. del vendedor.
  • Selección de anuncios en el dispositivo por parte del vendedor (SSP o publicador): Se basa en las ofertas de subasta y metadatos de los compradores.
  • Renderización de anuncios en una versión de marcos vallados temporalmente flexibilizada: con acceso a la red y para la renderización de anuncios.

La explicación de la API proporciona más detalles sobre la compatibilidad y las restricciones de las funciones.

Permisos del grupo de interés

La configuración predeterminada en la implementación actual de Protected Audience es permitir llamar a joinAdInterestGroup() desde en cualquier lugar de una página, incluso en iframes multidominio. En el futuro, una vez que los propietarios de los sitios tengan tiempo para ajustar sus políticas de permisos de iframe multidominio, el plan es deshabilitar las llamadas iframes multidominio, 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 clave-valor que devuelve pares clave-valor simples para proporcionar información a un comprador de anuncios, como los presupuesto de la campaña. La propuesta de Protected Audience los mandatos que este servidor "no realiza registros a nivel del evento ni tiene otros efectos secundarios basados en estas solicitudes".

El código de servicio de 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 ver la actualización del estado. Obtén más información sobre el servicio de par clave-valor de Protected Audience en la explicación de la API y en la explicación del modelo de confianza.

Para las pruebas iniciales, se usa el modelo “Trae tu propio servidor”. A largo plazo, las AdTech deberán usar los servicios de clave-valor de Protected Audience de código abierto que se ejecuten 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 exigir el uso de servicios de par clave-valor de código abierto o TEE hasta algún tiempo después de la baja de las cookies de terceros. Enviaremos una notificación importante a los desarrolladores para que comiencen a realizar pruebas y adopción antes de que se lleve a cabo esta 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 puedo inhabilitar Protected Audience?

Puedes bloquear el acceso a la API de Protected Audience como propietario del 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 permitir que esté disponible la funcionalidad de Protected Audience. Esto ayudará a garantizar que terceros arbitrarios no puedan usar la API sin la API conocimientos. Sin embargo, para facilitar las pruebas durante la primera prueba de origen, este requisito no se aplica de forma predeterminada. Los sitios que quieran inhabilitar explícitamente la funcionalidad de Protected Audience durante el período de prueba pueden usar la Política de Permisos correspondiente para bloquear el acceso.

Existen dos políticas de permisos de Protected Audience que se pueden establecer 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 especificando lo siguiente de permisos en un encabezado de respuesta HTTP:

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

Puedes inhabilitar el uso de las APIs en un iframe agregando el siguiente atributo allow a un elemento iframe:

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

En la sección Política de Permisos de la Prueba de Origen de Protected Audience Propuestos, 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 mediante cualquiera de los los siguientes mecanismos:

  • Inhabilita las pruebas de Privacy Sandbox en la configuración de Chrome: Configuración > Seguridad y privacidad > Privacy Sandbox. También se puede acceder a ella en chrome://settings/adPrivacy.
  • Inhabilitar las cookies de terceros en la configuración de Chrome: Configuración > Seguridad y privacidad.
  • Configura Cookies y otros datos de sitios en "Bloquear cookies de terceros". o "Bloquear todas las cookies" desde chrome://settings/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 los objetivos de privacidad.

Depura los worklets de Protected Audience

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

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

Captura de pantalla de Herramientas para desarrolladores en Chrome Canary, con el panel Event Listener Breakpoints destacado en el panel Sources. El inicio de la fase de oferta del ofertante se selecciona en Worklet de subasta de anuncios.

Cuando se activa un punto de interrupción, la ejecución se pausa antes de la primera sentencia en el nivel superior de la de gcloud. Puedes usar puntos de interrupción habituales o comandos de pasos para acceder a las ofertas, la puntuación o los informes. su propia función.

Las secuencias de comandos del worklet en vivo también se mostrarán en el panel Threads.

Captura de pantalla de Herramientas para desarrolladores en Chrome Canary, en la que se destaca el panel Threads en el panel Sources y que se muestra el valor actual secuencia de comandos del worklet que está en pausa.

Dado que algunos worklets pueden ejecutarse en paralelo, varios subprocesos pueden terminar en "pausados". ahí; puedes usar la lista de subprocesos para alternar entre ellos y reanudarlos o inspeccionarlos con más detalle lo que sea apropiado.

Observa los eventos de Protected Audience

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

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

El Panel de la aplicación de Herramientas para desarrolladores en Chrome Canary que muestra información sobre un grupo de interés de Protected Audience unirse al evento.

Ahora, si visitas el sitio para publicadores de demostración de Protected Audience En un navegador con Protected Audience habilitado, las Herramientas para desarrolladores muestran información sobre los eventos bid y win.

El Panel de la aplicación de Herramientas para desarrolladores en Chrome Canary, que muestra información sobre la oferta de subasta de Protected Audience y de eventos de éxito.

¿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 se le muestra un anuncio de una bicicleta nueva del fabricante de bicicletas.

1. Un usuario visita el sitio de un anunciante.

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

Imagina que un usuario visita el sitio web de un fabricante de bicicletas personalizada (el anunciante de este ejemplo) y pasa algún tiempo en la página del producto de una bicicleta de acero hecha a mano. Esto proporciona la de bicicletas con una oportunidad de remarketing.

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

Ilustración que muestra a una persona mirando un sitio en un navegador con su laptop. JavaScript el código joinAdInterestGroup() se está ejecutando en el navegador.

Sección de explicación: Los navegadores registran los grupos de interés

La plataforma orientada a la demanda (DSP) del anunciante (o el anunciante sí mismo) llama a navigator.joinAdInterestGroup() para pedirle al navegador que agregue un grupo de interés al lista de grupos a los que pertenece el navegador. En este ejemplo, el grupo se llama custom-bikes. 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 descrita en el paso 4. La pertenencia a un grupo de interés se almacena en el navegador del dispositivo del usuario y no se comparte con el proveedor del navegador o cualquier otra persona.

joinAdInterestGroup() requiere el permiso de:

  • El sitio que se está visitando
  • El propietario del grupo de interés

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

Permiso del sitio que se está visitando

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

Entre orígenes: Llama a joinAdInterestGroup() desde orígenes diferentes del actual página solo tendrá éxito si el sitio que se está visitando ha establecido una política de permisos que permita que las llamadas a joinAdInterestGroup() de iframes de origen cruzado.

Permiso del propietario del grupo de interés

El permiso de propietario del grupo de interés se otorga de forma implícita llamando a joinAdInterestGroup(). desde un iframe con el mismo origen que el del propietario del grupo de interés. Por ejemplo, un objeto dsp.example iframe 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 en un iframe en el dominio del propietario. se delegará a otros dominios proporcionados usando una lista en una URL .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 más de 50 kiB de tamaño; de lo contrario, el la llamada fallará. El segundo parámetro especifica la duración del grupo de interés, con un límite de 30. días. Las llamadas sucesivas reemplazan los valores almacenados con anterioridad.

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 interés.
biddingLogicUrl** Opcional* 'https://dsp.example/bid/custom-bikes/bid.js' URL para las ofertas de JavaScript ejecutada en worklet.
biddingWasmHelperUrl** Opcional* 'https://dsp.example/bid/custom-bikes/bid.wasm' URL del código de WebAssembly generado desde biddingLogicUrl.
dailyUpdateUrl** Opcional 'https://dsp.example/bid/custom-bikes/update' URL que muestra JSON para actualizar los atributos del grupo de interés. (Consulta Actualizar el grupo de interés).
trustedBiddingSignalsUrl** Opcional 'https://dsp.example/trusted/bidding-signals' URL base para las solicitudes de pares clave-valor al servidor de confianza del ofertante.
trustedBiddingSignalsKeys Opcional ['key1', 'key2' ...] Claves para solicitudes al servidor de confianza de par clave-valor.
userBiddingSignals Opcional {...} Metadatos adicionales que el propietario puede usar durante la licitación
ads Opcional* [bikeAd1, bikeAd2, bikeAd3] Anuncios que se podrían renderizar para este grupo de interés.
adComponents Opcional [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] Componentes para anuncios compuestos por varios elementos.

* Todas las propiedades son opcionales, excepto owner y name. biddingLogicUrl y ads Las propiedades son opcionales, pero se requieren para participar en una subasta. Puede haber casos de uso crear un grupo de interés sin estas propiedades; por ejemplo, el propietario de un grupo de interés podría agregar un navegador a un grupo de interés para una campaña que aún no se publica o para algunas otros usos futuros, o es posible que se queden temporalmente sin presupuesto publicitario.

** 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.

Actualizar los atributos del grupo de interés

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

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

Los campos que no se especifiquen en el archivo JSON no se reemplazarán; solo se obtendrán los campos especificados en el archivo JSON. se actualizó, mientras que la llamada a navigator.joinAdInterestGroup() reemplaza cualquier grupo de interés existente.

Las actualizaciones se realizan mediante el mejor esfuerzo y pueden fallar en las siguientes condiciones:

  • Tiempo de espera de la solicitud de red (actualmente, 30 segundos).
  • Otra falla de la red.
  • Error de análisis de JSON.

Las actualizaciones también se pueden cancelar si se dedicó demasiado tiempo contiguo a estas actualizaciones. Sin embargo, esto no impone ningún límite de frecuencia a las actualizaciones canceladas (restantes). Las actualizaciones tienen un límite de frecuencia como máximo de una por día. Las actualizaciones que fallan debido a errores de red se vuelven a intentar después de una hora. las actualizaciones que fallan debido a la desconexión de Internet se reintentan inmediatamente tras volver a conectarse.

Actualizaciones manuales

Las actualizaciones a los grupos de intereses que pertenecen al origen del fotograma actual se pueden activar manualmente mediante navigator.updateAdInterestGroups() El límite de frecuencia evita que las actualizaciones se realicen con demasiada frecuencia: Las llamadas repetidas a navigator.updateAdInterestGroups() no realizan ninguna acción hasta el límite de frecuencia (actualmente un día) haya transcurrido. El límite de frecuencia se restablece si Se vuelve a llamar a navigator.joinAdInterestGroup() para el mismo grupo de interés owner y name.

Actualizaciones automáticas

Todos los grupos de intereses que se cargaron para una subasta se actualizan automáticamente después de que esta finaliza, sujeta a los mismos límites de frecuencia que las actualizaciones manuales. Para cada propietario con, al menos, un grupo de interés participa en una subasta, es como si se llamara a navigator.updateAdInterestGroups() desde un iframe cuyo origen coincida con ese propietario.

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

Los objetos ads y adComponents incluyen una URL para una creatividad de anuncio y, opcionalmente, que se pueden usar en el momento de la licitación. Por ejemplo:

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

¿Cómo ofertan los compradores?

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

La secuencia de comandos en biddingLogicUrl que proporciona un comprador de espacio publicitario debe incluir una función generateBid(). Esta función se llama una vez para cada anuncio candidato. runAdAuction() Revisa individualmente cada anuncio, junto con la oferta y los metadatos asociados, y luego asigna al anuncio un puntuación de deseabilidad numérica.

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

generateBid() toma los siguientes argumentos:

  • interestGroup de
    El objeto que el comprador del anuncio pasa a joinAdInterestGroup(). (El grupo de interés se puede actualizar a través de dailyUpdateUrl).

  • auctionSignals de
    Una propiedad del argumento auction config que se pasa al navigator.runAdAuction() por el vendedor del espacio publicitario 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 (primer o segundo precio) y otros metadatos.

  • perBuyerSignals de
    Al igual que con auctionSignals, una propiedad de la configuración de subasta el argumento que pasó el vendedor a navigator.runAdAuction(). Esto puede proporcionar contexto indicadores del servidor del comprador sobre la página, si el vendedor es una SSP que realiza una llamada de licitación en tiempo real a los servidores del comprador y canaliza la respuesta, o si el publicador se comunica directamente con el servidor del comprador. Si es así, tal vez sea conveniente que el comprador verifique firma de esos indicadores dentro de generateBid() como protección contra la manipulación.

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

  • browserSignals de
    Un objeto construido por el navegador, que puede incluir información sobre la página contexto (como el hostname de la página actual, que el vendedor podría falsificar) y datos para el grupo de interés (como un registro de cuándo el grupo ganó una subasta anteriormente, para permitir limitación 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 de bid, el código en generateBid() puede usar las propiedades de la función parámetros. 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 de
    Metadatos arbitrarios sobre el anuncio, como información que el vendedor espera obtener sobre esta oferta o creatividad de anuncios. El vendedor](/privacy-sandbox/resources/glossary#ssp) usa esta información en la subasta y en la decisión que toma creatividad de anuncios. El vendedor usa esta información en su subasta y decisión lógica.

  • bid de
    Es una oferta numérica que ingresará en la subasta. El vendedor debe estar en posición de comparar. ofertas de diferentes compradores; por lo tanto, las ofertas deben estar en alguna unidad elegida por el vendedor (por ejemplo, "USD por mil"). Si la oferta es cero o negativa, este grupo de interés no participará del del vendedor en absoluto. Con este mecanismo, el comprador puede implementar reglas del anunciante en las que se indique dónde sus anuncios pueden aparecer o no.

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

  • adComponents de
    Una lista opcional de hasta 20 componentes para anuncios compuestos por varios elementos, tomado de la propiedad adComponents del argumento del grupo de interés pasado a navigator.joinAdInterestGroup().

Solicitar a un navegador que abandone un grupo de interés

El propietario del grupo de interés puede solicitar que se quite un navegador de un grupo de interés. En otro palabras, se solicita al navegador que elimine el grupo de interés de la lista de los grupos a los que pertenece.

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

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

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

Ilustración que muestra a una persona visitando un sitio web de noticias en un navegador con 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 inventario de anuncios, el cual vende de forma programática con ofertas en tiempo real.

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

Ilustración que muestra a una persona mirando un sitio web de noticias en un navegador con su laptop. Un anuncio subasta con la API de Protected Audience en curso.

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

Es probable que la SSP del publicador ejecute la subasta de anuncios, o el mismo publicador. El propósito de la subasta es seleccionar el anuncio más adecuado para una espacio publicitario disponible en la página actual. La subasta tiene en cuenta los grupos de interés navegador y los datos de los compradores de espacios publicitarios y los vendedores de los servicios de par clave-valor.

El vendedor del espacio publicitario realiza una solicitud al navegador del usuario para iniciar una subasta de anuncios llamando 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 la resultado de la subasta de anuncios. El navegador solo puede decodificarlo cuando se pasa a un marco vallado. para la renderización: La página del publicador no puede inspeccionar el anuncio ganador.

La secuencia de comandos decisionLogicUrl considera cada anuncio individual, junto con su oferta y metadatos, uno a la vez, y luego se le asigna una puntuación de deseabilidad numérica.

auctionConfig propiedades

Propiedad Obligatorio Ejemplo Rol
seller Obligatorio 'https://ssp.example' Origen del vendedor
decisionLogicUrl Obligatorio 'https://ssp.example/auction-decision-logic.js' URL del worklet de subasta en JavaScript.
trustedScoringSignalsUrl Opcional 'https://ssp.example/scoring-signals' URL del servidor de confianza del vendedor.
interestGroupBuyers* Obligatorio ['https://dsp.example', 'https://buyer2.example', ...] Orígenes 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 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 Tiempo de ejecución máximo (ms) de las secuencias de comandos generateBid() de un comprador específico.
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 interés oferten. Los anuncios se aceptan o rechazan según criterios distintos de la inclusión del propietario del grupo de interés. Por ejemplo, el vendedor puede revisar las creatividades de los anuncios para confirmar el cumplimiento de sus políticas.

** No se admite additionalBids en la implementación actual de Protected Audience. Lea la subasta Participantes en la Explicación de Protected Audience para obtener más información.

¿Cómo se seleccionan los anuncios?

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

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

scoreAd() toma los siguientes argumentos:

  • adMetadata de
    Metadatos arbitrarios proporcionados por el comprador.
  • bid de
    Es un valor numérico de la oferta.
  • auctionConfig de
    El objeto de configuración de la subasta que se pasa a navigator.runAdAuction().
  • trustedScoringSignals de
    Valores recuperados en el momento de la subasta del servidor de confianza del vendedor que representa la opinión del vendedor acerca del anuncio.
  • browserSignals de
    Un objeto construido por el navegador, incluida la información que este sabe y cuál es la secuencia de comandos de subasta del vendedor que 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 de 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 que muestra a una persona mirando un sitio web de noticias en un navegador con su laptop. Un anuncio una subasta con la API de Protected Audience, y un participante obtiene datos del servicio de par clave-valor.

Sección de explicación: Recupera datos en tiempo real del servicio de par clave-valor de Protected Audience.

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

Del mismo modo, un comprador del espacio publicitario puede solicitar datos en tiempo real del servicio de par clave-valor a través de la Propiedades trustedBiddingSignalsUrl y trustedBiddingSignalsKeys del argumento de grupo de interés pasado a navigator.joinAdInterestGroup().

Cuando se llama a runAdAuction(), el navegador realiza una solicitud al servidor de confianza de cada comprador de anuncios. El 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 el hostname.
  • El valor keys se obtiene 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 que muestra a una persona mirando un sitio web de noticias en un navegador con su laptop. Un anuncio de una bicicleta (20% de descuento), con un candado arriba para indicar que el anuncio aparece en una marco vallado.

Sección de explicación: Los navegadores renderizan el anuncio ganador

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

7. Se informa el resultado de la subasta

Sección de explicación: Informes a nivel del evento (por ahora)

El vendedor informa el resultado

Sección de explicación: Informes de vendedores sobre el procesamiento

El JavaScript del vendedor que se proporcionó 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 de
    El objeto de configuración de la subasta que se pasa a navigator.runAdAuction().

  • browserSignals
    Un objeto construido por el navegador 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 el argumento sellerSignals para el valor del ofertante ganador Función reportWin().

Resultado de los informes del ofertante ganador

Sección de explicación: Informes de compradores sobre el procesamiento y los eventos de anuncios

El 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
    Se pasan los mismos valores a generateBid() para el ofertante ganador.
  • sellerSignals de
    El valor que se muestra de reportResult(), que le da al vendedor la oportunidad de pasar información al comprador.

  • browserSignals de
    Un objeto construido por el navegador 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 de informes de pérdida/adquisición temporales

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

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

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

Chrome solo envía informes de pérdida/adquisición de depuración cuando se completa una subasta. Si se trata de una subasta cancelados (por ejemplo, debido a una nueva navegación), 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 que se encuentran en chrome://settings/adPrivacy. Si usas Chrome con marcas de línea de comandos para habilitar Protected Audience, deberás hacer lo siguiente: habilita explícitamente los métodos incluyendo la marca BiddingAndScoringDebugReportingAPI. Si el botón no está habilitada, los métodos seguirán estando disponibles, pero no hará nada.

8. Se registra un clic en el anuncio

Ilustración que muestra una persona haciendo clic en un anuncio de una bicicleta, dentro de un marco cercado, en un sitio web de noticias, con un informe que 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 sobre cómo podría funcionar, consulta Informes de anuncios de marcos vallados.


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 implementa en Chromium dentro de la familia de propuestas 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 un usuario potencialmente interesado que ya interactuó con el anunciante o la red de publicidad. Históricamente, el anunciante reconoce a una persona específica mientras navega por los sitios web, una preocupación de privacidad principal en la Web actual.

El objetivo de TURTLEDOVE es 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, conserva la información sobre lo que el anunciante considera que que le interesa a la persona.
  • Los anunciantes pueden publicar anuncios en función de un interés, pero no pueden combinarlo con otro. 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 de modificaciones para brindar un mejor servicio 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 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.
  • TERN de NextRoll y Magnite PARRROT describían los distintos roles que tenían los compradores y vendedores en la subasta integrada en el dispositivo. El flujo de ofertas y puntuación de anuncios de Protected Audience se basa en este trabajo.
  • los objetivos basados en los resultados y TURTLEDOVE a nivel del producto Las modificaciones mejoraron el modelo de anonimato y las capacidades de personalización de la subasta integrada en el dispositivo.
  • PARAKEET es 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. Protected Audience no adoptó este modelo de proxy. Incorporamos las APIs de JavaScript para PARAKEET y Protected Audience en la alineación, en apoyo del trabajo futuro para combinar aún más los mejores características de ambas propuestas.

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

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

Para ajustar su participación en las pruebas de Privacy Sandbox en Chrome, los usuarios pueden habilitar o inhabilitar la configuración de nivel superior en chrome://settings/adPrivacy. Durante las pruebas iniciales, usar este parámetro de configuración de Privacy Sandbox de alto nivel para inhabilitar Protected Audience. Chrome planea permitir usuarios vean y administren la lista de grupos de intereses 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 y evolucionar con la retroalimentación de los usuarios, los reguladores y otras personas.

Continuaremos actualizando los parámetros de configuración disponibles en Chrome a medida que avance la propuesta de Protected Audience, según sobre las pruebas y los comentarios. En el futuro, planeamos ofrecer parámetros de configuración más detallados para administrar Protected Audience y 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 la membresía está se quita cuando los usuarios borran los datos del sitio.



Interactúa y comparte tus comentarios

Obtenga asistencia

Para hacer preguntas sobre tu implementación, sobre la demostración o la documentación, haz lo siguiente:

Para errores y problemas con la implementación de la API de Protected Audience en Chrome, haz lo siguiente: * Ver 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.