API de présentation de l'UI du SDK Runtime

Le SDK Runtime permet aux SDK publicitaires de s'exécuter dans un environnement de bac à sable, ce qui les empêche d'accéder à la hiérarchie des vues d'un éditeur. Pour afficher des annonces, la plate-forme expose une API SandboxedSdkProvider.getView au SDK afin d'obtenir un visionnage de l'annonce, puis l'empaquette en tant que SurfacePackage à envoyer via IPC (communication inter-processus) à l'application cliente. Cette approche présente plusieurs inconvénients, qui sont abordés ci-dessous. Ce document présentera ensuite une proposition de bibliothèque Jetpack en cours de création pour répondre à ces défis.

Pourquoi étendre les API de la plate-forme ?

Les API de framework sont conçues pour être flexibles et la création d'un canal secondaire intermédiaire pour la présentation de l'UI est confiée à l'application et au SDK. Ce canal secondaire effectue les opérations suivantes :

  1. Il permet au SDK de gérer plusieurs visionnages d'annonces tout au long de leur durée de vie et de comprendre ce qu'il advient de l'UI de l'annonce une fois qu'elle a été créée par le SDK.
  2. Elle dissocie la création de vue et la liaison de contenu. L'utilisation du canal secondaire permet au SDK de renvoyer un objet correspondant à la demande d'annonce adressée à l'application (le contenu), qui peut être lié au conteneur d'annonces chaque fois que l'application le juge approprié.
  3. Elle élimine les constructions de plate-forme sous-jacentes utilisées pour afficher l'UI dans l'ensemble des processus. (La plate-forme utilise actuellement un SurfaceControlViewhost et génère un SurfacePackage à partir de celui-ci.)
  4. Permet aux SDK publicitaires du SDK Runtime de recevoir automatiquement des notifications lorsque l'UI du conteneur d'annonces change. Si un éditeur modifie la mise en page du conteneur d'annonces, le SDK n'en est pas informé, sauf si l'éditeur appelle explicitement une API pour l'en informer.
  5. Elle synchronise les redimensionnements de l'UI de l'annonce et du conteneur d'annonces sans aucun à-coup visible par l'utilisateur.
  6. Elle gère automatiquement la rétrocompatibilité. SurfacePackage n'est pas disponible avant le niveau d'API 30. Par ailleurs, sur les appareils sans SDK Runtime et sur lesquels le SDK est traité localement pour l'éditeur, il est inutile de créer un SurfacePackage pour une annonce lorsqu'une vue peut être directement obtenue auprès du SDK. La version secondaire élimine cette complexité du SDK et du code du développeur d'applications.
  7. Elle permet une intégration parfaite de l'UI des annonces avec les composables. Les développeurs Jetpack Compose qui ne travaillent pas avec des vues peuvent également continuer à héberger l'UI générée par le développeur du SDK qui travaille encore avec des vues.

Bibliothèques d'UI

Les bibliothèques d'UI éliminent les complexités décrites ci-dessus et fournissent le canal secondaire que l'éditeur et le SDK peuvent utiliser pour afficher l'UI dans les processus, et la maintenir à jour lorsque l'utilisateur interagit avec elle et avec l'appareil.

Il existe trois bibliothèques d'interface utilisateur : core, client et provider. La bibliothèque core fournit les interfaces utilisées par la bibliothèque cliente et la bibliothèque du fournisseur. Le fournisseur de l'UI (généralement le SDK) dépend de la bibliothèque du fournisseur, tandis que le consommateur de l'UI (généralement l'éditeur) dépend de la bibliothèque cliente. Ensemble, la bibliothèque cliente et la bibliothèque du fournisseur constituent le canal secondaire requis pour créer et gérer une session d'UI.

Les API

Les API pour la présentation de l'UI du SDK Runtime sont les suivantes :

SandboxedUiAdapter : créé par le SDK et permet d'obtenir le contenu à afficher dans l'UI de l'éditeur.

SandboxedSdkView : créé par l'éditeur, ce conteneur contient le contenu obtenu via SandboxedUiAdapter.

Session : créé par le SDK en réponse à SandboxedUiAdapter.openSession(). Représente un appel de session d'UI. Il s'agit de l'extrémité SDK du tunnel de communication entre le SDK et l'éditeur. Il reçoit des notifications sur les modifications de SandboxedSdkView, telles que les redimensionnements, les modifications de configuration ou la dissociation de fenêtres.

SessionClient : créé par la bibliothèque cliente, il constitue l'extrémité éditeur du tunnel de communication entre le SDK et l'éditeur.

SandboxedSdkUiSessionStateChangedListener : créé par l'éditeur. Un écouteur des modifications de l'état de la session d'UI associée à SandboxedSdkView.

Illustration représentant les relations entre les API de présentation de l'UI du SDK Runtime.
Relations entre les API de présentation de l'UI du SDK Runtime.

Pour en savoir plus sur ces API, consultez la documentation de référence sur privacysandbox-ui.

Flux de contrôle

Les schémas suivants illustrent les interactions entre la bibliothèque d'UI cliente et la bibliothèque d'UI du fournisseur dans différents scénarios :

Le schéma précédent montre comment l'éditeur peut créer un SandboxedSdkView par programmation ou via son fichier XML, et l'associer à un SdkSandboxUiAdapter obtenu auprès du SDK via une API définie par le SDK. Pour observer tous les changements d'état de l'UI, l'éditeur doit ajouter un SandboxedSdkUiSessionStateChangedListener à la SandboxedSdkView avant d'associer un SdkSandboxUiAdapter.

Illustration du processus d'ouverture de session.
Obtenez l'UI à partir du SDK.

Ce schéma montre comment, si l'activité de l'éditeur gère les modifications de configuration, la bibliothèque cliente se charge de transmettre ces modifications au SDK, afin qu'il puisse mettre à jour son UI en conséquence. Par exemple, ce flux peut être déclenché lorsque l'utilisateur fait pivoter l'appareil et que l'éditeur déclare gérer les modifications de configuration dans son activité, en définissant android:configChanges=["orientation"].

Modification de l'interface utilisateur initiée par l'éditeur.

Ce schéma montre comment le SDK peut demander une modification du conteneur d'annonces à l'aide de méthodes sur SessionClient. Cette API est déclenchée lorsque le SDK souhaite redimensionner l'annonce et a besoin que l'éditeur redimensionne le conteneur d'annonce pour l'adapter aux nouvelles dimensions. Cela peut se produire en réponse à une interaction de l'utilisateur, par exemple mraid.resize().

Modification de l'UI initiée par le SDK.

Ce schéma montre comment la session est fermée lorsque SandboxedSdkView est dissocié de la fenêtre. La session peut également être fermée à tout moment (par exemple, lorsque l'utilisateur perd la connectivité réseau) par le SDK en appelant SessionClient.onSessionError().

Fermeture de la session de l'interface utilisateur.

Ordre de plan

La bibliothèque d'UI cliente utilise une SurfaceView en interne pour héberger l'UI du SDK. SurfaceView peut utiliser l'ordre de plan pour afficher son UI au-dessus ou en dessous de la fenêtre de l'éditeur. Ce paramètre est contrôlé par la méthode SandboxedSdkView.orderProviderUiAboveClientUi(), qui accepte une valeur booléenne setOnTop.

Lorsque setOnTop est défini sur true, chaque android.view.MotionEvent dans la SandboxedSdkView est envoyé au SDK. Lorsque ce paramètre est défini sur false, ils sont envoyés à l'éditeur. Par défaut, les événements de mouvement sont envoyés au SDK.

En général, les éditeurs n'ont pas besoin de modifier l'ordre de plan par défaut des visionnages d'annonce. Toutefois, lorsque vous affichez une UI qui recouvre une annonce, par exemple un menu déroulant, l'ordre de plan doit être temporairement inversé par rapport à la valeur par défaut, puis restauré lorsque l'élément d'interface utilisateur recouvrant est fermé. Nous étudions des moyens d'automatiser ce processus dans la bibliothèque d'UI cliente.

Défilement

Lorsque l'ordre de plan de l'UI de l'annonce est défini au-dessus de la fenêtre de l'éditeur, les MotionEvents de l'UI de l'annonce sont envoyées au SDK. Les gestes de défilement ou de glissement d'un geste vif effectués dans l'UI de l'annonce font l'objet d'un traitement spécial :

  1. Ces gestes sont envoyés au conteneur de l'éditeur et sont gérés par celui-ci. Cela offre une bonne expérience utilisateur lorsque le conteneur de l'éditeur dans lequel est placée l'interface utilisateur de l'annonce est à défilement vertical. Cela ne nécessite aucun travail supplémentaire de la part du SDK ni de la part de l'éditeur.
  2. Les gestes de défilement horizontal et de glissement d'un geste vif sont envoyés au SDK et gérés par celui-ci. Cela offre une bonne expérience utilisateur lorsque l'UI elle-même est à défilement horizontal (par exemple, dans un carrousel d'annonces).

Guide d'implémentation

Le SDK doit implémenter les éléments suivants :

  • SandboxedUiAdapter: cette valeur est renvoyée à l'éditeur en réponse à une API définie par le SDK, telle que loadAd. La méthode openSession() de cette implémentation doit être utilisée pour envoyer une demande d'annonce aux serveurs du SDK et préparer un visionnage d'annonce pour cette demande.
  • Session**: cette valeur est renvoyée en réponse à l'appel SandboxedUiAdapter.openSession. Elle permet à la bibliothèque cliente d'obtenir l'UI de l'annonce et d'informer le SDK des modifications apportées à cette API. Toutes les méthodes Session doivent être implémentées ici.

L'éditeur doit procéder comme suit :

  1. Créer une SandboxedSdkView, soit via XML, soit de façon programmatique.
  2. Associer un SandboxedSdkUiSessionStateChangedListener à la SandboxedSdkView pour observer les modifications de l'UI.
  3. Associer un SandboxedUiAdapter fourni par le SDK à la SandboxedSdkView.
  4. Ajouter la SandboxedSdkView à la fenêtre comme d'habitude et laissez la bibliothèque cliente se charger de la création et de la gestion de la session d'UI avec le SDK.
  5. Aux moments opportuns, réagir aux changements d'état signalés par SandboxedSdkUiSessionChangedListener. Par exemple, si le SDK ferme la session de manière inattendue, l'éditeur peut remplacer SandboxedSdkView par une image statique ou la supprimer de sa hiérarchie des vues.
  6. Lors de transitions susceptibles de recouvrir l'UI de l'annonce, par exemple en cas de présence d'un menu déroulant, définir temporairement la valeur orderProviderUiAboveClientUi sur "false" pour placer l'UI de l'annonce en dessous de la fenêtre de l'éditeur. Une fois le menu déroulant fermé, définir orderProviderUiAboveClientUi sur true.

L'avenir des API de la plate-forme

Nous prévoyons d'abandonner les API de la plate-forme SDK Runtime liées à la présentation de l'UI, à savoir SdkSandboxManager.requestSurfacePackage() et SandbxedSdkProvider.getView(), une fois que les bibliothèques d'UI seront en version bêta.

Questions ouvertes

  1. Existe-t-il d'autres cas d'utilisation de l'UI d'annonce plus courants que les bibliothèques d'UI devraient gérer automatiquement ?
  2. Quels frameworks d'UI utilisez-vous pour afficher l'UI des annonces ? Anticipez-vous des problèmes d'intégration des bibliothèques d'UI à ces frameworks ?
  3. Vous arrive-t-il souvent d'avoir une UI d'annonce à défilement placée dans un conteneur d'éditeur à défilement ? Dans ce cas, quel est le sens du défilement pour l'UI de l'annonce et pour le conteneur ? Quel comportement attendez-vous lorsque l'utilisateur commence à effectuer un défilement dans l'UI de l'annonce ?