Propuesta de diseño de visibilidad del entorno de ejecución de SDK

Los SDKs de anuncios en el entorno de ejecución de SDK no pueden acceder a la jerarquía de vistas de un publicador. En cambio, los SDKs en el entorno de ejecución tienen sus propias vistas. El SDK no puede usar las mismas APIs de View que las que usan fuera del entorno de ejecución de SDK para determinar si el anuncio es visible para el usuario, ya que la vista de anuncio no está conectada a la ventana de la aplicación. Esto incluye las APIs de View de Android, como getLocationOnScreen, getLocationInWindow o getVisibility, que no muestran los valores esperados.

Uno de los requisitos principales del entorno de ejecución de SDK es admitir la medición de visibilidad de los anuncios. El objetivo de esta propuesta de diseño es lograr la compatibilidad con Open Measurement y servicios de medición similares. Las soluciones que se analizan aquí también pueden aplicarse a las APIs de Attribution Reporting. Te pedimos que nos envíes tus comentarios sobre esta propuesta.

Funciones

Este diseño tiene como objetivo admitir SDKs de anuncios o socios de medición para calcular los siguientes datos de visibilidad (los nombres son provisionales y están sujetos a cambios):

Ilustración que muestra cómo interoperan los componentes de la visibilidad del entorno de ejecución de SDK
Figura 1: Descripción general de la visibilidad del entorno de ejecución de SDK.
  • viewport [Rect]: Representa la pantalla del dispositivo o la geometría de la ventana de la app, según las funciones de la plataforma.
  • uiContainerGeometry [Rect]: Es la geometría de SandboxedSdkView que se renderiza.
  • alpha [float]: Es la opacidad de SandboxedSdkView que se renderiza.
  • onScreenGeometry [Rect]: Es el subconjunto de uiContainerGeometry que no está recortado por vistas superiores, hasta el elemento viewport inclusive.
  • occludedGeometry [Rect]: Son las partes de onScreenGeometry que obstruyen cualquier vista en la jerarquía de la aplicación. Incluye un elemento Rect para cada oclusión, que corresponde a ninguna, una o más vistas de app que se cruzan con SandboxedSdkView onScreenGeometry.

Requisitos

  • Los valores de uiContainerGeometry, onScreenGeometry y occludedGeometry se expresan en el espacio de coordenadas de viewport.
  • Los informes de cambios de visibilidad se realizan con una latencia mínima.
  • La visibilidad se puede medir en todo el ciclo de vida de la vista de anuncio, desde su primera aparición hasta la última.

Propuesta de diseño

Esta propuesta se basa en el funcionamiento de la presentación de la IU con las bibliotecas cliente y proveedor de la IU. Extenderemos las bibliotecas de la IU para permitir que el SDK registre uno o más observadores de la sesión de la IU. El observador recibirá información de la visibilidad cada vez que se detecten eventos relevantes que modifiquen los tipos de datos en la sección Funciones. Los SDKs de medición en el entorno de ejecución de SDK (implementaciones de OMID y MRAID) pueden conectar este observador a la sesión de la IU para que se les pueda enviar esta información directamente. Los socios de medición pueden combinar información obtenida de las bibliotecas de la IU con datos sobre contenido que ya esté disponible (por ejemplo, cuando se usan secuencias de comandos de medición insertadas en la creatividad del anuncio) para generar eventos de visibilidad de JavaScript.

Flujo de control para la visibilidad.
Figura 2: Flujo de control para la visibilidad.

La biblioteca cliente detecta los cambios en la IU del anuncio a través de objetos de escucha de eventos, como ViewTreeObserver. Cada vez que determina que la IU del anuncio cambió de una manera que podría afectar la medición de visibilidad, la biblioteca cliente verifica cuándo se envió la última notificación al observador. Si la última actualización es mayor que la latencia permitida (configurable por el SDK, hasta un mínimo de 200 ms en dispositivos móviles), se crea un objeto AdContainerInfo nuevo, y se envía una notificación a el observador. Este modelo basado en eventos es mejor para el estado del sistema que el sondeo que realizan la mayoría de las implementaciones de OMID en Android en la actualidad.

API

Se agregará lo siguiente a la biblioteca de privacysandbox.ui.core:

  • SessionObserver: Por lo general, es implementado por el SDK de medición, conectado a la sesión que muestra el SDK a través de privacysandbox.ui. Esta interfaz también permitirá que el SDK de medición habilite ciertas categorías de indicadores de visibilidad. Esto, a su vez, permite que la biblioteca cliente de la IU solo recopile indicadores que le interesen al observador, lo que es mejor para el estado del sistema en general.
  • registerObserver(): Este método, que se agregó a la clase Session, permite que cualquier persona con acceso a la sesión registre un observador. Si se registra el observador después de que se abrió la sesión de la IU, se les enviará, de inmediato, el elemento AdContainerInfo almacenado en caché. Si se registran antes de que se abra la sesión, se les enviará el objeto AdContainerInfo cuando esta se abra.
  • AdContainerInfo: Es una clase con métodos get que le permite al observador obtener información del contenedor de anuncios de solo lectura para los tipos de datos que se enumeran en la sección anterior Funciones. Los valores que muestran estos métodos get corresponderán, siempre que sea posible, a los valores parcelables que muestren los métodos get existentes en View y sus subclases. Si el contenedor de anuncios se creó con Jetpack Compose, se exponen las propiedades semánticas del contenedor. Esta clase se puede usar para calcular los eventos de MRAID y OMID que se relacionen con la visibilidad.
  • SessionObserverotifyAdContainerChanged(): Se usa para notificarle al observador cuando cambia la visibilidad. Pasa un objeto AdContainerInfo. Se llama a este objeto cada vez que se detectan eventos que afectan los tipos de datos que se enumeran en la sección Funciones. Nota: Se puede llamar a este método, además de otros en Session. Por ejemplo, se llama a Session.notifyResized() para solicitarle al SDK que cambie el tamaño del anuncio, y también se llama a SessionObserver.notifyAdContainerChanged() cuando esto sucede.
  • SessionObserverotifySessionClosed(): Le notifica al observador que se cerró la sesión.

Mejoras en el futuro

Cualquier código que se ejecute en el proceso de la aplicación, incluido el código de la biblioteca de privacysandbox.ui.client, se puede modificar si la aplicación está comprometida. Por lo tanto, cualquier lógica de recopilación de indicadores que se ejecute en el proceso de la aplicación suele ser alterada por el código de la aplicación. Esto también se aplica al código del SDK implementado antes de la disponibilidad de Privacy Sandbox que se ejecuta en el proceso de la aplicación. En consecuencia, la recopilación de indicadores por parte de la biblioteca de la IU no empeora la situación de seguridad.

Además, el código en el entorno de ejecución de SDK puede usar una API de la plataforma llamada setTrustedPresentationCallback que brinda garantías más sólidas del framework sobre la presentación de la IU del anuncio. setTrustedPresentationCallback funciona a nivel del elemento Surface y puede ayudar a realizar aserciones sobre el Surface que contiene la IU del anuncio, ya que especifica umbrales mínimos para la presentación, como el porcentaje de píxeles visibles, el tiempo en pantalla o la escala. Estos datos se pueden comparar con los datos de visibilidad que proporciona la biblioteca cliente de la IU, como se explicó anteriormente. Como los datos proporcionados por el framework son más confiables, se puede descartar cualquier evento de la biblioteca de la IU cuyos datos no coincidan con los del framework. Por ejemplo, si el objeto de escucha que se proporciona a setTrustedPresentationCallback se invoca con una notificación que indica que no se muestran píxeles de la IU de anuncio en la pantalla y si la biblioteca cliente de la IU muestra, en la pantalla, un valor de píxeles diferente a cero, se pueden descartar los datos de estos últimos.

Preguntas abiertas

Invitamos a que nos envíes comentarios sobre los siguientes puntos:

  1. ¿Qué indicadores de visibilidad te interesan que no se mencionan en esta explicación?
  2. Con la propuesta actual, se actualizará la visibilidad con una frecuencia que no sea menor a cada 200 milisegundos, siempre que haya un cambio relevante en la IU. ¿Te parece aceptable esta frecuencia? Si crees que no, ¿qué frecuencia preferirías?
  3. ¿Prefieres analizar la información de setTrustedPresentationCallback por tu cuenta o que la biblioteca proveedor de la IU quite los datos de la biblioteca cliente de la IU cuando no coincida con los datos de setTrustedPresentationCallback?
  4. ¿Cómo se consumen los indicadores de visibilidad? Envíanos comentarios que respondan estas preguntas para ayudarnos a comprender tus casos de uso.