Compatibilidad con actividades para anuncios de pantalla completa

El entorno de ejecución de SDK impone restricciones sobre la forma en que los SDKs pueden iniciar actividades nuevas. Esto plantea un desafío para los formatos de anuncios de pantalla completa que generalmente dependen de iniciar una actividad separada para mejorar el control y la experiencia del usuario. Para abordar esto, el entorno de ejecución de SDK presenta un mecanismo novedoso para las actividades de zona de pruebas.

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

Si bien los SDKs también están restringidos para el lanzamiento de intents con esta acción, los SDKs 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 objeto android.app.Activity estándar que se inicia como parte de la tarea de la app cliente.

Precaución: La actividad proporcionada (android.app.Activity) tiene compatibilidad limitada con algunas bibliotecas de AndroidX del lado del SDK, en particular Compose.

Precaución: El SDK no debe usar el Context de esta actividad directamente. En cambio, los SDKs deben usar SandboxedSdkProvider#getContext() para obtener el contexto adecuado para sus operaciones.

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

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

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

Bibliotecas de actividades

Las bibliotecas de actividades ofrecen varias ventajas:

• Abstrae los detalles internos para registrar controladores de actividad y compartir sus identificadores con apps cliente.
• Brinda a los desarrolladores de apps más control sobre la forma en que los SDKs crean actividades dentro de sus apps, ya que les permite establecer condiciones (predicados) para que se cumplan.
• Crea una forma unificada para que los SDKs definan las APIs que lanzan actividades.

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

• La biblioteca core proporciona las interfaces que usan las apps cliente y las bibliotecas de proveedores.
• La biblioteca provider 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 SDK 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 actividades de inicio 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 a la 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:

1. El SDK agrega un parámetro del tipo SdkActivityLauncher a cualquier API que inicie actividades.
2. 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.
3. El SDK llama a SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) y recupera el token de identificador.
4. El SDK llama a launchSdkActivity para iniciar la actividad.

Nota: Si la app cliente quiere agregar una condición para que los SDKs creen actividades, puede pasar una expresión de predicado cuando se crea el selector. Si la app no quiere condicionar la creación de la actividad, puede hacer que el predicado muestre siempre true.

En el siguiente diagrama, se muestra el flujo en el que se usan bibliotecas de actividades.

Diagrama de secuencias que muestra el flujo de inicio de una actividad mediante bibliotecas de actividades.

APIs de plataforma

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

• SdkSandboxActivityHandler: El controlador de actividad se usa para notificar al SDK cuando se crea una actividad y este la registra.
• Para ayudarte 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 muestra un identificador IBinder.
  • .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler): Anula el registro de una instancia registrada de SdkSandboxActivityHandler con su identificador.
• SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): Cuando se invoca desde la app cliente, este método activa la creación de actividades para el SDK. La app cliente debe pasar como parámetros la actividad inicial elegida y el identificador del controlador de actividad del SDK.

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

1. El SDK registra un controlador de actividades usando las APIs proporcionadas y obtiene un identificador.
2. El SDK comparte este identificador con su app cliente.
3. La app cliente llama al método para iniciar una actividad en el entorno de ejecución de SDK con la API de la plataforma startSdkSandboxActivity(Activity, IBinder) y pasa como parámetros la actividad inicial elegida para esta actividad nueva y el identificador del controlador de actividades.
4. 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)).
5. El SDK usa la actividad para completarlo con un anuncio.

Nota: Se llama a onActivityCreated(Activity) a través de Activity.onCreate(Bundle). Se espera que los SDKs propaguen la vista de contenido en esta etapa.

El uso de las APIs de Platform 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 secuencias que muestra el flujo para iniciar una actividad con las APIs de la plataforma.

Visibilidad

Dentro del entorno de ejecución de SDK, los anuncios integrados en la jerarquía de vistas de la app cliente usan canales laterales para renderizar vistas del SDK desde el proceso del SDK hasta el 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 del SDK para determinar si el anuncio es visible para el usuario, ya que la vista de anuncio no está adjunta a la ventana de la aplicación (Visibilidad).

Por el contrario, la actividad que proporciona la plataforma se ejecuta de forma nativa dentro del proceso del entorno de ejecución de SDK, lo que elimina la necesidad de canales laterales y permite que los SDK usen las APIs estándar de Activity y View de Android.

Debido a estas diferentes implementaciones, los esfuerzos continuos apuntan a unificar las interfaces para recuperar los indicadores de visibilidad, independientemente del contexto de carga de anuncios.

Ciclo de vida

El ActivityHolder que se pasa al SDK a través de SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) implementa LifecycleOwner y se puede usar para obtener información sobre Lifecycle.Event.

Navegación hacia atrás

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