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

Le SDK Runtime impose des restrictions sur la façon dont les SDK peuvent lancer de nouvelles activités. Cela peut poser un problème pour les formats d'annonces plein écran qui reposent généralement sur le lancement d'une activité distincte pour améliorer le contrôle et l'expérience utilisateur. Pour résoudre ce problème, 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 des balises <activity> dans leur fichier manifeste ni lancer leurs propres activités. À la place, une nouvelle action d'intent, START_SANDBOXED_ACTIVITY, est introduite.

Bien que les SDK ne puissent pas lancer d'intents avec cette action, ils peuvent demander à l'application cliente de lancer 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 un android.app.Activity standard, lancé dans la tâche de l'application cliente.

Attention:L'activité fournie (android.app.Activity) est compatible de façon limitée avec certaines bibliothèques AndroidX côté SDK, en particulier Compose.

Attention:Le Context de cette activité ne doit pas être utilisé directement par le SDK. À la place, les SDK doivent utiliser SandboxedSdkProvider#getContext() pour obtenir le contexte approprié pour leurs opérations.

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

Il existe deux méthodes principales pour créer des activités: utiliser les bibliothèques Activity simplifiées de Jetpack ou interagir directement avec les API Platform.

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

Bibliothèques d'activités

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

• Extraire les détails internes liés à l'enregistrement des gestionnaires d'activité et au 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) à remplir.
• Créez une méthode unifiée permettant aux SDK de définir les API qui lancent des activités.

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

• 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 cliente 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 introduisent les API suivantes:

• SdkActivityLauncher: le lanceur d'activités permet aux SDK de gérer le lancement des activités à partir de l'application cliente. Les applications clientes doivent créer un lanceur d'applications et le transmettre en tant que paramètre aux API du SDK qui lancent des 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 d'applications.
• SdkActivityLauncher.launchSdkActivity(IBinder): méthode utilisée par le SDK pour demander à l'application de lancer des activités.

Pour lancer des activités avec les bibliothèques d'activités, procédez comme suit:

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

Remarque :Si l'application cliente souhaite ajouter une condition pour que les SDK créent des activités, elle peut transmettre une expression de prédicat lors de la création du lanceur d'applications. Si l'application ne souhaite pas conditionner la création d'activités, elle peut faire en sorte que le prédicat renvoie toujours true.

Le schéma suivant illustre la procédure à suivre en cas d'utilisation de bibliothèques d'activités.

Schéma séquentiel illustrant le processus de démarrage d'une activité à l'aide des bibliothèques d'activités

API de la plate-forme

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

• SdkSandboxActivityHandler : le gestionnaire d'activités permet d'informer le SDK lorsqu'une activité est créée. Elle est enregistrée 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) : annule l'enregistrement d'une instance enregistrée de SdkSandboxActivityHandler à l'aide de son identifiant.
• SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder) : appelé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épart choisie et l'identifiant du gestionnaire d'activités du SDK.

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

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

Remarque :onActivityCreated(Activity) est appelé via Activity.onCreate(Bundle). Les SDK doivent remplir la vue de contenu à ce stade.

Grâce aux API de plate-forme, le SDK est chargé 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 le diagramme de flux suivant, l'exemple de SDK comporte une méthode launchActivity(AppCallback) qui attend un rappel (défini dans le cadre de l'API du SDK). Ce rappel permet au SDK de partager l'identifiant du gestionnaire d'activités (SdkSandboxActivityHandler) avec l'application cliente.

Schéma séquentiel illustrant le processus de démarrage d'une activité à l'aide des API de la plate-forme

Visibilité

Dans le SDK Runtime, les annonces intégrées à la hiérarchie des vues de l'application cliente utilisent des canaux secondaires pour afficher les vues du SDK du processus du SDK jusqu'au 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 associé à 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 du SDK Runtime, ce qui élimine le besoin de versions secondaires et permet aux SDK d'utiliser les API Android Activity et View standards.

En raison de ces différentes implémentations, nos efforts continus visent à unifier les interfaces afin de récupérer les signaux de visibilité, quel que soit le contexte de chargement de l'annonce.

Cycle de vie

Le ActivityHolder transmis au SDK via SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) implémente LifecycleOwner et peut être utilisé pour connaître le Lifecycle.Event.

Navigation arrière

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