Compatibilidad con actividades para anuncios de pantalla completa

El entorno de ejecución de SDK impone restricciones sobre cómo los SDKs pueden iniciar actividades nuevas. Esto representa un desafío para los formatos de anuncios de pantalla completa que suelen depender del inicio de una actividad separada para mejorar el control y la experiencia del usuario. Para abordar este problema, el SDK Runtime introduce un mecanismo novedoso para las actividades en zona de pruebas.

Los SDKs cargados en el entorno de ejecución de SDK no pueden definir directamente etiquetas <activity> en su manifiesto ni iniciar sus propias actividades. En su lugar, se presenta una nueva acción de intent, START_SANDBOXED_ACTIVITY.

Si bien los SDKs también tienen restricciones para iniciar intents con esta acción, pueden solicitar a la app cliente que inicie este intent. Luego, el sistema crea una actividad definida por la plataforma y la pasa al SDK. Esta actividad se ejecutará en el mismo proceso que el SDK.

Luego, el SDK puede usar esta actividad para implementar y administrar la experiencia del anuncio de pantalla completa.

La actividad que proporciona la plataforma es un android.app.Activity estándar que se lanza como parte de la tarea de la app cliente.

Creación de actividades en el entorno de ejecución de SDK

Tienes dos métodos principales para crear actividades: usar las bibliotecas de Activity optimizadas de Jetpack o interactuar directamente con las APIs de la plataforma.

Recomendamos usar las bibliotecas de actividades, ya que simplifican la creación de actividades al abstraer la complejidad subyacente.

Bibliotecas de actividades

Las bibliotecas de actividades ofrecen varias ventajas:

Abstrae los detalles internos del registro de controladores de actividad y el uso compartido de sus identificadores con las apps cliente.
Permite que los desarrolladores de apps tengan más control sobre cómo los SDKs crean actividades dentro de sus apps, ya que les permite establecer condiciones (predicados) que se deben cumplir.
Crear una forma unificada para que los SDKs definan APIs que inician actividades

Existen tres bibliotecas de actividades: principal, cliente y proveedor.

La biblioteca principal proporciona las interfaces que usan las apps cliente y las bibliotecas de proveedores.
La biblioteca de proveedor proporciona APIs para que los SDKs inicien actividades.
La biblioteca client proporciona APIs para que las apps cliente creen un selector de actividades, que los SDKs pueden usar para solicitar que las apps inicien actividades.

Estas bibliotecas introducen las siguientes APIs:

SdkActivityLauncher: El selector de actividades permite que los SDKs controlen el inicio de actividades desde la app cliente. Las apps cliente deben crear un selector y pasarlo como parámetro a las APIs del SDK que inician actividades.
<T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ): Es una función de extensión que la app cliente puede llamar desde sus actividades para crear selectores.
SdkActivityLauncher.launchSdkActivity(IBinder): Es un método que usa el SDK para solicitar que la app inicie actividades.

El flujo de inicio de actividades con bibliotecas de actividades es el siguiente:

El SDK agrega un parámetro del tipo SdkActivityLauncher a todas las APIs que iniciarán actividades.
La app cliente llama a createSdkActivityLauncher en una de sus actividades para crear un selector que se pueda pasar al SDK en las llamadas a la API.
El SDK llama a SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) y recupera el token de identificador.
El SDK llama a launchSdkActivity para iniciar la actividad.

En el siguiente diagrama, se muestra el flujo en caso de usar bibliotecas de actividades.

Diagrama de secuencia de la biblioteca de actividades — Diagrama de secuencia que muestra el flujo del inicio de una actividad con bibliotecas de actividades.

APIs de la plataforma

La plataforma introduce las siguientes APIs para facilitar la creación y administración de actividades en zona de pruebas dentro del entorno de ejecución de SDK:

SdkSandboxActivityHandler: El controlador de actividades se usa para notificar al SDK cuando se crea una actividad y el SDK lo registra.
Para ayudar con el registro de los controladores de actividad, el SDK puede usar los siguientes métodos en SdkSandboxController:
- .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler): Registra una instancia de SdkSandboxActivityHandler, que devuelve un identificador IBinder.
- .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler): Anula el registro de una instancia registrada de SdkSandboxActivityHandler con su identificador.
SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): Se invoca desde la app cliente y activa la creación de actividades para el SDK. La app cliente debe pasar como parámetros la actividad de inicio elegida y el identificador del controlador de actividades del SDK.

Para iniciar una actividad con las APIs de la plataforma, los SDKs deben seguir este flujo:

El SDK registra un controlador de actividad con las APIs proporcionadas y obtiene un identificador.
El SDK comparte este identificador con su app cliente.
La app cliente llama al método para iniciar una actividad en el entorno de ejecución del SDK con la API de la plataforma startSdkSandboxActivity(Activity, IBinder), y pasa como parámetros la actividad de inicio elegida para esta nueva actividad y el identificador del controlador de actividad.
La plataforma inicia una actividad y notifica al SDK a través de una devolución de llamada en el controlador de actividades (SdkSandboxActivityHandler.onActivityCreated(Activity)).
El SDK usa la actividad para propagarla con un anuncio.

El uso de las APIs de la plataforma hace que el SDK sea responsable de compartir el identificador de SdkSandboxActivityHandler con la app cliente a través de sus APIs en el momento adecuado y de guiar a las apps cliente sobre cómo usarlo.

En el siguiente diagrama de flujo, el SDK de ejemplo tiene un método launchActivity(AppCallback) que espera una devolución de llamada (definida como parte de la API del SDK). El SDK usa esta devolución de llamada para compartir el identificador del controlador de actividad (SdkSandboxActivityHandler) con la app cliente.

Diagrama de secuencia de las APIs de la plataforma — Diagrama de secuencia que muestra el flujo del inicio de una actividad con las APIs de la plataforma.

Visibilidad

En el entorno de ejecución de SDK, los anuncios integrados en la jerarquía de vistas de la app cliente usan canales secundarios para renderizar vistas del SDK desde el proceso del SDK al proceso de la app cliente.

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 (visibilidad).

En cambio, la actividad proporcionada por la plataforma se ejecuta de forma nativa dentro del proceso del entorno de ejecución del SDK, lo que elimina la necesidad de canales secundarios y permite que los SDKs usen las APIs de Activity y View estándar de Android.

Debido a estas diferentes implementaciones, los esfuerzos en curso tienen como objetivo unificar las interfaces para recuperar los indicadores de visibilidad independientemente del contexto de carga de anuncios.

Lifecycle

El objeto ActivityHolder que se pasa al SDK a través de SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) implementa LifecycleOwner y se puede usar para conocer el objeto Lifecycle.Event.

Navegación hacia atrás

El método ActivityHolder.getOnBackPressedDispatcher() devuelve OnBackPressedDispatcher, que se puede usar para registrar instancias de OnBackPressedCallback para controlar la navegación hacia atrás.