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 fundamentales para seguir desarrollando y mejorando sus funciones.

Enviar comentarios

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 tienen restricciones en cuanto al lanzamiento de intents con esta acción, los SDKs pueden solicita 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 el anuncio de pantalla completa. una experiencia fluida a los desarrolladores.

La actividad que proporciona la plataforma es una android.app.Activity estándar, iniciar 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 Context de esta actividad no debe usar directamente el Context de esta actividad. de Google Cloud. En cambio, los SDKs deben usar SandboxedSdkProvider#getContext() para obtener la 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

Actividad bibliotecas proporcionan 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 aplicaciones cliente y bibliotecas de proveedores de servicios.
• 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 las 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 ): 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 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 SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) y recupera el token identificador.
4. El SDK llama 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 del inicio de una actividad con una actividad bibliotecas.

APIs de plataforma

La plataforma introduce 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): Cancela el registro de una instancia registrada de SdkSandboxActivityHandler con su identificador.
• SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): Invocado 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: onActivityCreated(Activity) se llama mediante Activity.onCreate(Bundle), Se espera que los SDKs propaguen la vista de contenido en esta etapa.

Usar las APIs de Platform hace que el SDK sea responsable de compartir el SdkSandboxActivityHandler identificador 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 un (definida como parte de la API del SDK). El objeto de escucha usa esta devolución de llamada. SDK para compartir el controlador de actividades (SdkSandboxActivityHandler) identificador con la app cliente.

Diagrama de secuencias que muestra el flujo de 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 lado canales para renderizar vistas del SDK del 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 del SDK para determinar si el anuncio es visible para el usuario porque la vista del anuncio que se 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 el para recuperar los indicadores de visibilidad, independientemente del contexto de carga de los anuncios.

Lifecycle

El ActivityHolder pasan al SDK mediante SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) implements LifecycleOwner y puede usarse para conocer el Lifecycle.Event.

Navegación hacia atrás

El método ActivityHolder.getOnBackPressedDispatcher() devoluciones OnBackPressedDispatcher que se puede usar para registrar OnBackPressedCallback para administrar la navegación hacia atrás.