Compatibilidad con actividades para anuncios de pantalla completa

Nota: Privacy Sandbox en Android es un proyecto en curso, y este documento refleja su diseño actual. Tus comentarios son esenciales para que sigamos desarrollando y mejorando sus funciones.

El entorno de ejecución de SDK impone restricciones sobre cómo los SDKs pueden iniciar actividades nuevas. Esto plantea un desafío para los formatos de anuncios de pantalla completa que, por lo general, dependen de iniciar una actividad independiente para mejorar el control y la experiencia del usuario. Para abordar este problema, el entorno de ejecución de SDK presenta 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 la restricción de no 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 de anuncios de pantalla completa.

La actividad que proporciona la plataforma es un 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 en el SDK, en particular con Compose.

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

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.

Te recomendamos que uses bibliotecas de actividades, ya que simplifican la creación de actividades abstrayendo la complejidad subyacente.

Bibliotecas de actividades

Las bibliotecas de actividades proporcionan varias ventajas:

• Abstrae los detalles internos del registro de controladores de actividades y comparte sus identificadores con las apps cliente.
• Les brinda a los desarrolladores de apps 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.
• Crea una forma unificada para que los SDKs definan APIs que inicien actividades.

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

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

Estas bibliotecas presentan 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 ): 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 desea 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 actividades, puede hacer que el predicado siempre devuelva true.

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

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

APIs de la plataforma

La plataforma presenta las siguientes APIs para facilitar la creación y la administración de actividades en la 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 actividades, el SDK puede usar los siguientes métodos en SdkSandboxController:
  • .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler): Registra una instancia de SdkSandboxActivityHandler, que muestra un identificador IBinder.
  • .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler): Cancela 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 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:

1. El SDK registra un controlador de actividades con 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 de inicio 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 propagarla 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 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 un momento adecuado y 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 actividades (SdkSandboxActivityHandler) con la app cliente.

Diagrama de secuencias que muestra el flujo de inicio de 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 de 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 de SDK, lo que elimina la necesidad de canales laterales y permite que los SDKs usen las APIs estándar de Activity y View de Android.

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

Lifecycle

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

Navegación hacia atrás

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