Prise en charge des activités pour les annonces plein écran

SDK Runtime impose des restrictions sur la façon dont les SDK peuvent lancer de nouvelles activités. Cela pose un problème pour les formats d'annonces plein écran qui s'appuient généralement sur le lancement d'une activité distincte pour un contrôle et une expérience utilisateur améliorés. Pour résoudre ce problème, le SDK Runtime introduit un nouveau mécanisme pour les activités en bac à sable.

Les SDK chargés dans l'environnement SDK Runtime ne peuvent pas définir directement de balises <activity> dans leur fichier manifeste ni lancer leurs propres activités. Une nouvelle action d'intent, START_SANDBOXED_ACTIVITY, est introduite.

Bien que les SDK ne soient pas autorisés à lancer des intents avec cette action, ils peuvent demander à l'application cliente d'initier cet intent. Le système crée ensuite une activité définie par la plate-forme et la transmet au SDK. Cette activité s'exécutera dans le même processus que le SDK.

Le SDK peut ensuite utiliser cette activité pour implémenter et gérer l'expérience publicitaire en plein écran.

L'activité fournie par la plate-forme est une android.app.Activity standard, lancée dans le cadre de la tâche de l'application cliente.

Création d'activités sur le SDK Runtime

Vous disposez de deux méthodes principales pour créer des activités : utiliser les bibliothèques d'activités Jetpack simplifiées ou interagir directement avec les API de plate-forme.

Nous vous recommandons d'utiliser les bibliothèques d'activités, car elles simplifient la création d'activités en masquant la complexité sous-jacente.

Bibliothèques d'activités

Les bibliothèques d'activités offrent plusieurs avantages :

Abstrait les détails internes de l'enregistrement des gestionnaires d'activités et du partage de leurs identifiants avec les applications clientes.
Permet aux développeurs d'applications de mieux contrôler la façon dont les SDK créent des activités dans leurs applications en leur permettant de définir des conditions (prédicats) à respecter.
Créer une méthode unifiée permettant aux SDK de définir des API qui lancent des activités.

Il existe trois bibliothèques d'activités : core, client et provider.

La bibliothèque core fournit les interfaces utilisées par les applications clientes et les bibliothèques de fournisseurs.
La bibliothèque provider fournit des API permettant aux SDK de lancer des activités.
La bibliothèque client fournit des API permettant aux applications clientes de créer un lanceur d'activités, que les SDK peuvent utiliser pour demander aux applications de lancer des activités.

Ces bibliothèques présentent les API suivantes :

SdkActivityLauncher : le lanceur d'activités permet aux SDK de gérer le lancement d'activités à partir de l'application cliente. Les applications clientes doivent créer un lanceur et le transmettre en tant que paramètre aux API du SDK qui démarrent les activités.
<T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ) : Fonction d'extension que l'application cliente peut appeler à partir de ses activités pour créer des lanceurs.
SdkActivityLauncher.launchSdkActivity(IBinder) : méthode utilisée par le SDK pour demander à l'application de lancer des activités.

Voici comment lancer des activités avec des bibliothèques d'activités :

Le SDK ajoute un paramètre de type SdkActivityLauncher à toutes les API qui démarreront des activités.
L'application cliente appelle createSdkActivityLauncher sur l'une de ses activités pour créer un lanceur qui peut être transmis au SDK lors des appels d'API.
Le SDK appelle SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) et récupère le jeton d'identifiant.
Le SDK appelle launchSdkActivity pour lancer l'activité.

Le schéma suivant illustre le flux en cas d'utilisation de bibliothèques d'activités.

Diagramme séquentiel de la bibliothèque d'activités — Schéma de séquence illustrant le processus de lancement d'une activité à l'aide de bibliothèques d'activités.

API de plate-forme

La plate-forme introduit les API suivantes pour faciliter la création et la gestion des activités mises en bac à sable dans le SDK Runtime :

SdkSandboxActivityHandler : Le gestionnaire d'activités est utilisé pour informer le SDK lorsqu'une activité est créée. Il est enregistré par le SDK.
Pour faciliter l'enregistrement des gestionnaires d'activités, le SDK peut utiliser les méthodes suivantes sous SdkSandboxController :
- .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler) : enregistre une instance de SdkSandboxActivityHandler, qui renvoie un identifiant IBinder.
- .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler) : Désenregistre une instance enregistrée de SdkSandboxActivityHandler à l'aide de son identifiant.
SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder) : invoquée à partir de l'application cliente, cette méthode déclenche la création d'activités pour le SDK. L'application cliente doit transmettre en tant que paramètres l'activité de démarrage choisie et l'identifiant du gestionnaire d'activités du SDK.

Pour démarrer une activité à l'aide des API de plate-forme, les SDK doivent suivre ce flux :

Le SDK enregistre un gestionnaire d'activités à l'aide des API fournies et obtient un identifiant.
Le SDK partage cet identifiant avec son application cliente.
L'application cliente appelle la méthode pour démarrer une activité dans le SDK Runtime avec l'API de plate-forme startSdkSandboxActivity(Activity, IBinder), en transmettant comme paramètres l'activité de démarrage choisie pour cette nouvelle activité et l'identifiant du gestionnaire d'activités.
La plate-forme démarre une activité et en informe le SDK via un rappel dans le gestionnaire d'activités (SdkSandboxActivityHandler.onActivityCreated(Activity)).
Le SDK utilise l'activité pour la remplir avec une annonce.

L'utilisation des API de plate-forme permet au SDK de partager l'identifiant de SdkSandboxActivityHandler avec l'application cliente via ses API au moment opportun, et de guider les applications clientes sur la façon de l'utiliser.

Dans l'organigramme suivant, l'exemple de SDK comporte une méthode launchActivity(AppCallback) qui attend un rappel (défini dans l'API du SDK). Ce rappel est utilisé par le SDK pour partager l'identifiant du gestionnaire d'activités (SdkSandboxActivityHandler) avec l'application cliente.

Diagramme de séquence des API de la plate-forme — Schéma de séquence illustrant le processus de lancement d'une activité à l'aide des API de la plate-forme.

Visibilité

Dans SDK Runtime, les annonces intégrées à la hiérarchie des vues de l'application cliente utilisent des canaux latéraux pour afficher les vues du SDK à partir du processus du SDK vers le processus de l'application cliente.

Le SDK ne peut pas utiliser les mêmes API View qu'en dehors du SDK Runtime pour déterminer si l'annonce est visible par l'utilisateur, car le visionnage de l'annonce n'est pas joint à la fenêtre de l'application (visibilité).

En revanche, l'activité fournie par la plate-forme s'exécute de manière native dans le processus SDK Runtime, ce qui élimine le besoin de canaux secondaires et permet aux SDK d'utiliser les API Android standards Activity et View.

En raison de ces différentes implémentations, des efforts continus sont déployés pour unifier les interfaces afin de récupérer les signaux de visibilité, quel que soit le contexte de chargement des annonces.

Cycle de vie

Le ActivityHolder transmis au SDK via SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) implémente LifecycleOwner et peut être utilisé pour en savoir plus sur Lifecycle.Event.

Navigation vers l'arrière

La méthode ActivityHolder.getOnBackPressedDispatcher() renvoie OnBackPressedDispatcher, qui peut être utilisé pour enregistrer des instances OnBackPressedCallback afin de gérer la navigation à l'arrière.