Afficher des éléments personnalisés avec le SDK Android

Lorsqu’un écran contenant un élément personnalisé s’ouvre, le SDK Adapty transmet le Type et l’ID de l’élément à un resolver dans le code de votre application. Le resolver retourne l’un des résultats suivants :

  • La vue correspondant au Type et à l’ID : les utilisateurs voient la vue native, comme une animation Lottie, un graphique interactif ou un aperçu de caméra.
  • Aucune vue : les utilisateurs voient le contenu de secours, c’est-à-dire le contenu défini dans l’élément personnalisé dans le Flow & Paywall Builder.

Les utilisateurs de versions de l’application sans resolver voient également le contenu de secours. Vous pouvez donc publier le flow avant de publier la nouvelle version de l’application.

Avant de commencer

Vous avez besoin de :

  • Adapty Android SDK 4.4 ou version ultérieure : les versions antérieures affichent le contenu de secours pour chaque élément personnalisé.
  • Une application Android native : les SDK Adapty pour les frameworks multiplateforme, tels que Flutter, affichent le contenu de secours pour chaque élément personnalisé.
  • Un schéma de nommage pour les éléments personnalisés : donnez à chaque vue native un Type, tel que lottie_animation. Utilisez uniquement des lettres minuscules, des chiffres et des underscores dans les Types. Pour distinguer les éléments personnalisés du même Type, donnez à chacun un ID, tel que welcome_wave. Les Types et les IDs dans votre code doivent correspondre à ceux définis dans le Flow & Paywall Builder.

Si votre application iOS affiche déjà des éléments personnalisés, réutilisez ses Types et IDs. Sauf si vous configurez une audience distincte pour chaque plateforme, les utilisateurs iOS et Android voient les mêmes flows.

Créer des vues pour les éléments personnalisés

Pour chaque Type, créez ou réutilisez un composable/View Android. Les vues suivantes du Type lottie_animation lisent une animation Lottie depuis le dossier assets de votre application. L’exemple Kotlin est un composable qui utilise la bibliothèque com.airbnb.android:lottie-compose. L’exemple Java crée une View Android depuis la bibliothèque com.airbnb.android:lottie :

Exigences et bonnes pratiques

  • Dimensionnement :

    • Rembourrage et alignement : Assurez-vous que la vue native s’adapte au conteneur que vous avez alloué dans le Flow & Paywall Builder, en tenant compte du rembourrage. Si la vue n’occupe pas toute la zone, elle apparaît par défaut dans le coin supérieur gauche. Pour la déplacer, modifiez l’alignement dans la section Layout de l’élément personnalisé.
    • Hauteur Hug : Si la hauteur de l’élément personnalisé est définie sur Hug, une vue qui s’étend pour remplir l’espace disponible (comme une liste paresseuse) se réduira ou s’étirera jusqu’à la hauteur de l’écran. Donnez plutôt à l’élément personnalisé une hauteur Fixed.
  • Thème : Pour afficher un composable dans les couleurs et polices de votre application sur un écran construit avec des Views, enveloppez-le dans votre thème Compose.

  • Actions de flow : La vue native ne peut pas déclencher d’actions de flow, comme une transition vers l’écran suivant. Gardez les boutons de navigation, les boutons d’achat et les autres boutons avec des actions de flow en dehors de l’élément personnalisé.

  • Éléments sélectionnables : Gardez l’élément personnalisé en dehors des cartes produits et des autres éléments sélectionnables. Lorsque la sélection change, la vue native peut perdre son état.

  • Gestion de la navigation : Lorsque l’utilisateur passe à l’écran suivant, le SDK retire la vue native de l’écran. Arrêtez ce que la vue a démarré, comme les sessions caméra, les lecteurs et les mises à jour de localisation :

    • Composable : Utilisez le bloc onDispose d’un DisposableEffect. Pour le travail asynchrone, utilisez LaunchedEffect : Compose l’annule lorsque le composable quitte la composition.
    • Android View : Surchargez onDetachedFromWindow dans votre sous-classe View, ou ajoutez un View.OnAttachStateChangeListener à la View.

    Lorsque l’utilisateur revient, ou après un changement de configuration comme une rotation, le SDK rappelle le resolver et crée une nouvelle vue native sans l’état de la précédente.

  • Carousels : Dans un carousel, les vues natives de toutes les diapositives restent actives tant que l’écran est ouvert, pas seulement la vue de la diapositive visible. Évitez de placer des aperçus caméra et des lecteurs audio dans les carousels.

Écrire un resolver pour faire correspondre les éléments personnalisés et les vues

Pour écrire un resolver, implémentez l’interface AdaptyCustomElementsResolver. Sa méthode resolve reçoit le Type et l’ID d’un élément personnalisé, et retourne la vue correspondante sous l’une des formes suivantes :

  • Un composable : Retournez AdaptyCustomElementContent.compose, avec le composable dans son lambda.
  • Une View Android : Retournez AdaptyCustomElementContent.view, avec une fonction qui crée la View. En Kotlin, nommez le paramètre factory : AdaptyCustomElementContent.view(factory = { context, _ -> ChartView(context) }). Sans le nom, Kotlin passe un lambda de fin au paramètre optionnel update, et le code ne compile pas.

Pour le type lottie_animation, le resolver suivant renvoie la vue Lottie. L’ID désigne le fichier d’animation dans le dossier assets, par exemple welcome_wave pour welcome_wave.json :

Pour tout autre type, retournez null. Si vous ajoutez un élément personnalisé avec un nouveau type après la publication de l’application, les utilisateurs de la version publiée verront son fallback.

Le resolver doit respecter les exigences suivantes :

  • Données réseau et lecteurs : Conservez les données réseau et les lecteurs dans l’état de la vue native, et non dans le resolver. Le SDK appelle le resolver de nombreuses fois pendant que l’écran est ouvert. Le code du resolver s’exécute à nouveau à chaque appel, ce qui relance les requêtes réseau et remet les lecteurs à zéro. Le SDK ne recrée pas la vue native entre ces appels, donc les données se chargent une seule fois et les lecteurs continuent de jouer. Créez les lecteurs, les sessions et les requêtes réseau à l’intérieur de la vue native :

    • Composable : Créez les lecteurs et les sessions dans remember, et les requêtes réseau dans LaunchedEffect.
    • Android View : Créez les lecteurs, les sessions et les requêtes réseau dans onAttachedToWindow.
  • Une vue native par élément personnalisé : Certaines vues natives changent pendant que l’écran est ouvert, par exemple lorsque leurs données se chargent ou lorsque l’utilisateur appuie dessus. Implémentez cette logique dans la vue native elle-même, pas dans le resolver. Si le resolver retourne un composable différent pour le même élément personnalisé, Compose réinitialise l’état de la vue.

  • Une nouvelle View à chaque apparition : Créez une nouvelle View à chaque appel de factory. Le SDK appelle factory chaque fois que l’élément personnalisé apparaît, par exemple à l’ouverture de l’écran, quand l’utilisateur y revient, ou après une rotation.

  • Données de l’application : Stockez un objet contenant les données, comme un StateFlow ou un LiveData avec une série quotidienne, dans une propriété du resolver. Passez l’objet à la vue native et observez-le là :

    • Composable : Collectez un StateFlow avec collectAsState, ou observez un LiveData avec observeAsState.
    • Android View : Observez l’objet dans onAttachedToWindow, et arrêtez dans onDetachedFromWindow.

    Une valeur que vous copiez dans le resolver, comme le numéro de série, reste telle qu’elle était au moment de la création du resolver.

Définir les conditions pour le contenu de secours

Pour afficher le contenu de secours à la place d’un élément personnalisé vide, ne renvoyez aucune vue dans les situations suivantes :

  • Rien à afficher — le fichier d’animation ou de données nécessaire est manquant.
  • Rien à traiter — l’utilisateur a passé une question du quiz et les données sont incomplètes.
  • Accès refusé — une permission refusée empêche la vue d’accéder à une ressource.

Par exemple, le resolver ne renvoie aucune vue lorsque le fichier d’animation est manquant.

Pour une permission, renvoyez null uniquement si l’utilisateur l’a refusée avant l’ouverture de l’écran. ContextCompat.checkSelfPermission renvoie la même valeur, PERMISSION_DENIED, dans deux cas : avant que votre application ait demandé la permission pour la première fois, et après que l’utilisateur l’a refusée. Pour distinguer ces deux cas, enregistrez le résultat de la demande de permission et lisez ce résultat enregistré dans le resolver. Si votre application n’a pas encore demandé la permission, renvoyez la vue native plutôt que null, et demandez la permission depuis la vue. Par exemple, demandez l’accès à la localisation lorsqu’une vue carte apparaît, et affichez la carte dès que l’utilisateur accorde l’accès. Si vous renvoyez null et que l’utilisateur accorde l’accès ensuite, il continuera à voir le fallback. Un changement de permission n’amène pas le SDK à rappeler le resolver. La vue native n’apparaît qu’après que le SDK rappelle le resolver, par exemple lorsque l’utilisateur revient sur l’écran.

Passer le resolver au SDK

Commencez par un resolver global. Le SDK l’appelle dans chaque flow qui ne possède pas son propre resolver. Les utilisateurs voient vos vues natives dans les nouveaux flows et tests A/B sans mise à jour de l’application. Ces vues affichent quand même les données propres à chaque utilisateur, comme une série quotidienne, car elles les lisent directement depuis votre application.

Attachez un resolver à un seul flow lorsque ce flow nécessite des données que votre application ne possède qu’au moment où elle ouvre ce flow. Par exemple, un paywall affiche le poids que l’utilisateur a saisi dans un flow précédent, ou prévisualise le document que l’utilisateur souhaite exporter. Vous pouvez également attacher un resolver à un seul flow pour afficher une vue différente pour un Type dans ce flow.

Afficher les vues dans chaque flow

Pour utiliser le resolver dans chaque flow, appelez AdaptyUI.setCustomElementsResolver une seule fois, par exemple dans la méthode onCreate de votre classe Application :

Tip

Pour afficher la même vue dans chaque élément personnalisé d’un Type, passez une map de Types et de vues à AdaptyCustomElementsResolver.of. Une map nécessite moins de code qu’une classe de résolution, mais vous ne pouvez pas définir des conditions pour le contenu de secours.

val appWideViews = mapOf(
    "confetti" to AdaptyCustomElementContent.compose { LottieElement("confetti.json") },
)
AdaptyUI.setCustomElementsResolver(AdaptyCustomElementsResolver.of(appWideViews))

Afficher les données d’un seul flow, par exemple un document à exporter

Un resolver que vous passez à une vue de flow remplace le resolver global dans cette vue de flow.

Pour conserver les vues globales dans ce flow, passez le resolver global à ce resolver, et appelez le resolver global pour les autres types et ID. Le resolver suivant affiche un aperçu du document que l’utilisateur souhaite exporter, et appelle le resolver global pour tous les autres éléments personnalisés :

Transmettez le resolver dans le paramètre customElementsResolver de AdaptyUI.getFlowView :

Si vous créez AdaptyFlowView vous-même, passez le résolveur à sa méthode showFlow. En Java, showFlow prend les mêmes arguments que getFlowView, à l’exception de activity. Avec Jetpack Compose, passez le résolveur à AdaptyFlowScreen. Pour un exemple de chaque appel, consultez Afficher les flows et paywalls.

Si vous utilisez AdaptyCustomElementsResolver.of plutôt que des classes resolver, fusionnez la map de vues globales avec une map pour ce flow : AdaptyCustomElementsResolver.of(appWideViews + flowViews). Passez le résultat à la vue du flow. Si un Type est présent dans les deux maps, ce code conserve la vue du flow.

Tester sur un appareil

Le Flow & Paywall Builder ne peut pas exécuter le code de votre application, donc son canvas n’affiche que le fallback. Une erreur dans la vue native peut faire planter l’application. Avant de publier l’application, testez chaque écran contenant un élément personnalisé sur un appareil :

  1. Pour voir la dernière version publiée de chaque flow au lieu d’une version en cache, enregistrez l’appareil comme appareil de test.

  2. Pour voir les avertissements du SDK Adapty dans Logcat, définissez le niveau de log sur AdaptyLogLevel.WARN ou un niveau plus détaillé. Avec le niveau par défaut, AdaptyLogLevel.NONE, le SDK ne consigne rien.

  3. Sur l’appareil, lancez un build qui inclut le resolver. Ouvrez chaque écran contenant un élément personnalisé et vérifiez que la vue native s’affiche correctement dans l’élément personnalisé. Si la vue défile ou réagit aux glissements, testez ces gestes.

  4. Si le fallback s’affiche à la place de la vue native, recherchez cet avertissement dans Logcat : custom element <type>:<id> is not served by a resolver. Vérifiez ensuite que :

    • Le Type et l’ID dans l’avertissement correspondent exactement à ceux de votre code, lettre pour lettre.
    • Votre application dispose du fichier, des données ou des permissions dont la vue a besoin.
    • Votre application définit le resolver à l’échelle de l’application.
    • Un resolver pour ce flow, si vous en passez un, renvoie une vue pour le Type et l’ID.

    Si l’avertissement n’apparaît pas, vérifiez que l’application utilise Adapty Android SDK 4.4 ou une version ultérieure.

  5. Si l’élément personnalisé reste vide, recherchez l’un de ces avertissements dans Logcat :

    • custom element <type>:<id> is not served by a resolver : L’élément personnalisé n’a pas de contenu de secours et aucun resolver ne retourne de vue pour lui. Vérifiez chaque élément de l’étape 4.
    • content does not report its size : Le composable n’a pas de hauteur propre. Donnez à l’élément personnalisé une hauteur Fixe.

    Le SDK enregistre l’avertissement de taille uniquement pour les composables. Si une View Android reste vide sans avertissement, donnez également une hauteur Fixed à l’élément personnalisé.

  6. Pour prévisualiser le fallback, renvoyez null pour le Type, puis rouvrez l’écran.

Exemples

Chaque exemple présente la configuration dans le builder et le code correspondant pour votre application :