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

Remarque :La Privacy Sandbox sur Android est un projet en cours, et ce document reflète sa conception actuelle. Vos commentaires sont essentiels pour nous permettre de continuer à développer et à améliorer ses fonctionnalités.

Le 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 en plein écran qui reposent généralement sur le démarrage d'une activité distincte pour améliorer le contrôle et l'expérience utilisateur. Pour y remédier, 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. À la place, une nouvelle action d'intent, START_SANDBOXED_ACTIVITY, est introduite.

Bien que les SDK ne soient pas autorisés à 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écute 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 le cadre de la tâche de l'application cliente.

Attention:L'activité fournie (android.app.Activity) est compatible 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'une activité sur le SDK Runtime

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

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

Bibliothèques d'activités

Les bibliothèques d'activités présentent 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éez 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 du fournisseur.
• La bibliothèque du fournisseur 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 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 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.
• SdkActivityLauncher.launchSdkActivity(IBinder): méthode utilisée par le SDK pour demander à l'application de lancer des activités.

Le flux de lancement d'activités avec des bibliothèques d'activités est le suivant:

1. Le SDK ajoute un paramètre de type SdkActivityLauncher à toutes les API qui démarrent des activités.
2. 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.
3. Le SDK appelle SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) et récupère le jeton d'identifiant.
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. Si l'application ne souhaite pas conditionner la création d'activités, elle peut toujours faire en sorte que le prédicat renvoie true.

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

Schéma de séquence illustrant le processus de démarrage d'une activité à l'aide de 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 des 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. 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) : 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émarrage choisie et l'identifiant du gestionnaire d'activités du SDK.

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

1. Le SDK enregistre un gestionnaire d'activités à 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 plate-forme startSdkSandboxActivity(Activity, IBinder), en transmettant comme paramètres l'activité de démarrage choisie pour cette nouvelle activité et l'identifiant de l'activité Handler.
4. La plate-forme démarre une activité et avertit le SDK via un rappel dans le gestionnaire d'activités (SdkSandboxActivityHandler.onActivityCreated(Activity)).
5. Le SDK utilise l'activité pour la renseigner avec une annonce.

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

L'utilisation des API de la plate-forme fait en sorte que le SDK soit chargé de partager l'identifiant du 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 l'API du SDK). Ce rappel est utilisé par le SDK pour partager l'identifiant de l'activité Handler (SdkSandboxActivityHandler) avec l'application cliente.

Schéma de séquence 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 à 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 Activity et View standards.

En raison de ces différentes implémentations, des efforts continus visent à unifier les interfaces pour 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 pour gérer la navigation arrière.