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

Lorsqu’un écran contenant un élément personnalisé s’ouvre, le SDK Adapty transmet le Type et l’ID de l’élément à un résolveur dans le code de votre application. Le résolveur renvoie l’une des valeurs suivantes :

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

Si l’utilisateur possède une ancienne version de votre application — une version qui n’a pas du tout le resolver — il voit quand même le contenu de secours. Vous pouvez donc publier le flow avant de déployer la mise à jour de l’application.

Avant de commencer

Vous avez besoin de :

  • Adapty iOS SDK 4.4 ou version ultérieure : les versions antérieures affichent le fallback pour chaque élément personnalisé.
  • Une application iOS native : les SDK Adapty pour les frameworks multiplateforme, comme Flutter, affichent le fallback 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 traits de soulignement 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 ID dans votre code doivent correspondre à ceux du Flow & Paywall Builder.

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

Pour chaque Type, créez une vue SwiftUI native ou réutilisez-en une de votre application. La vue suivante du Type lottie_animation joue une animation Lottie :


struct LottieElementView: View {
    let animation: LottieAnimation?

    var body: some View {
        LottieView(animation: animation)
            .resizable()
            .looping()
    }
}

Exigences et bonnes pratiques

  • Dimensionnement :
    • Padding 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 padding. Si la vue n’occupe pas toute la zone, elle apparaît par défaut dans le coin supérieur gauche de cette zone. 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’étire pour remplir l’espace disponible (comme une carte) se réduira à zéro. Donnez plutôt à l’élément personnalisé une hauteur Fixed.
  • Actions de flow : La vue native ne peut pas déclencher d’actions de flow, comme la 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 produit 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, SwiftUI exécute l’action onDisappear de la vue native. Dans cette action, arrêtez ce que la vue a démarré, comme les sessions caméra, les lecteurs et les mises à jour de localisation. Pour le travail asynchrone, utilisez .task : SwiftUI l’annule lorsque la vue disparaît. Lorsque l’utilisateur revient, le SDK appelle à nouveau le resolver, et SwiftUI réinitialise l’état de la vue.
  • Vues UIKit : Encapsulez-les dans UIViewRepresentable.

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

Pour écrire un resolver, faites en sorte qu’un type soit conforme au protocole AdaptyUICustomElementsResolver, et implémentez la méthode view(forType:id:context:).

Pour le type lottie_animation, le resolver suivant renvoie LottieElementView. L’ID désigne le fichier d’animation dans le bundle de l’app, par exemple welcome_wave :


struct CustomElementsResolver: AdaptyUICustomElementsResolver {
    func view(
        forType type: String,
        id: String,
        context: AdaptyUICustomElementContext
    ) -> AnyView? {
        switch type {
        case "lottie_animation":
            // the ID names the animation file, such as welcome_wave.json
            guard let animation = LottieAnimation.named(id) else {
                return nil // no file for this ID: show the fallback
            }
            return AnyView(LottieElementView(animation: animation))
        default:
            return nil
        }
    }
}

Dans le cas default, retournez nil. Si vous ajoutez un élément personnalisé avec un nouveau Type après la sortie 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, pas dans le resolver. Le SDK appelle le resolver de nombreuses fois pendant que l’écran est ouvert, par exemple au chargement des produits ou au démarrage d’un achat. Le code du resolver s’exécute à nouveau à chaque appel, ce qui entraîne la répétition des requêtes réseau et le redémarrage des lecteurs. SwiftUI conserve l’état de la vue native entre les appels, de sorte que les données ne se chargent qu’une seule fois et que les lecteurs continuent de jouer. Créez les lecteurs, les sessions et les requêtes réseau dans .task ou dans un @StateObject, pas dans la valeur initiale d’une propriété @State. Swift réévalue cette valeur initiale chaque fois que le resolver crée la vue.
  • Une vue native par élément personnalisé : Certaines vues natives changent pendant que l’écran est ouvert, par exemple au chargement de leurs données ou lorsque l’utilisateur appuie dessus. Implémentez cette logique dans le body de la vue elle-même, pas dans le resolver. Si le resolver retourne une vue différente pour le même élément personnalisé, SwiftUI réinitialise l’état de la vue.
  • Données de l’application : Stockez un objet applicatif contenant les données, par exemple un ObservableObject avec la série quotidienne, dans une propriété du resolver. Passez l’objet à la vue native et observez-le avec @ObservedObject. Une valeur copiée dans le resolver, comme le numéro de série, reste telle qu’elle était lors de la création du resolver. N’utilisez pas d’objets d’environnement pour ces données : avec le contrôleur de flow UIKit, la vue native ne reçoit pas l’environnement SwiftUI de votre application.

Définir les conditions pour le contenu de secours

Pour afficher aux utilisateurs le contenu de secours à la place d’un élément personnalisé vide, retournez nil 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, l’instruction guard dans le résolveur renvoie nil lorsque le fichier d’animation est manquant.

Pour une permission, ne renvoyez nil que si l’utilisateur l’a refusée avant l’ouverture de l’écran. Si l’utilisateur n’a pas encore répondu à la demande de permission, renvoyez la vue native plutôt que nil, et demandez la permission à l’intérieur. Par exemple, dans Afficher des lieux à proximité sur une carte dans un flow, iOS affiche l’invite d’accès à la localisation lorsque la carte apparaît. La vue native peut afficher la carte dès que l’utilisateur accorde l’accès. Si vous renvoyez nil avant que l’utilisateur réponde, le contenu de secours reste affiché même après qu’il ait accordé l’accès, jusqu’à ce que le SDK rappelle le resolver.

Passer le resolver au SDK

Commencez par un resolver global. Le SDK l’appelle dans chaque flow sans resolver propre. 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 flow spécifique lorsque ce flow nécessite des données que votre application ne possède qu’au moment de l’ouverture de 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 flow spécifique pour afficher une vue différente pour un Type dans ce flow.

Définir un résolveur global pour l’application

Pour utiliser le résolveur dans chaque flow, appelez AdaptyUI.setCustomElementsResolver(_:) une seule fois, par exemple au lancement de l’application :


// keep this instance: a resolver for one flow can reuse it
@MainActor let customElementsResolver = CustomElementsResolver()

AdaptyUI.setCustomElementsResolver(customElementsResolver)
Tip

L’alternative plus simple et plus limitée à l’approche par résolveur consiste à passer un dictionnaire [String: AdaptyUICustomElementBuilder] avec des clés de type. Cela nécessite moins de code, mais vous ne pouvez pas définir des conditions pour le contenu de secours.

AdaptyUI.setCustomElementsResolver([
    "lottie_animation": .init { _, id, _ in LottieElementView(animation: .named(id)) },
])

Associer un resolver à un flow

Un resolver associé à un flow remplace le resolver global dans ce flow. Les valeurs que vous lui transmettez restent telles qu’elles étaient lors de la récupération de la configuration du flow. Pour afficher de nouvelles valeurs, récupérez à nouveau la configuration.

Pour conserver les vues globales dans ce flow, transmettez 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 :


struct ExportPaywallResolver: AdaptyUICustomElementsResolver {
    let document: Document // the document that the user wants to export
    let appWideResolver: any AdaptyUICustomElementsResolver

    func view(
        forType type: String,
        id: String,
        context: AdaptyUICustomElementContext
    ) -> AnyView? {
        if type == "document_preview" {
            return AnyView(DocumentPreview(document: document))
        }
        // other Types: the views of the app-wide resolver
        return appWideResolver.view(forType: type, id: id, context: context)
    }
}

Associez le resolver au flow lors de la récupération de sa configuration :

func showExportPaywall(flow: AdaptyFlow, document: Document) async {
    do {
        let flowConfiguration = try await AdaptyUI.getFlowConfiguration(
            forFlow: flow,
            customElementsResolver: ExportPaywallResolver(
                document: document,
                appWideResolver: customElementsResolver // the instance that you set app-wide
            )
        )
        // present the flow
    } catch {
        // handle the error
    }
}

Si vous utilisez des dictionnaires plutôt que des résolveurs, fusionnez les deux dictionnaires et attachez le résultat au flow : appWideViews.merging(flowViews) { _, flowView in flowView }. Si un Type est présent dans les deux dictionnaires, ce code conserve la vue associée au flow.

Tester sur un appareil

Le Flow & Paywall Builder ne peut pas exécuter le code de votre application, donc son canvas affiche uniquement 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 plutôt qu’une version en cache, enregistrez l’appareil comme appareil de test.

  2. 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 et s’intègre correctement dans l’élément personnalisé. Si la vue défile ou réagit aux glissements, testez ces gestes.

  3. Si le contenu de secours s’affiche à la place de la vue native, recherchez cet avertissement dans la console Xcode : 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, caractère par caractère.
    • Votre app dispose du fichier, des données ou des autorisations nécessaires à la vue.
    • Votre app définit le resolver global avant que l’écran contenant l’élément personnalisé ne s’ouvre.
    • Un resolver pour ce flow, si vous en attachez un, retourne une vue pour le Type et l’ID concernés.

    Si l’avertissement n’apparaît pas, vérifiez que l’application utilise le SDK iOS Adapty 4.4 ou une version ultérieure, et que Adapty.logLevel n’est pas .error.

  4. Pour prévisualiser le paywall de secours, renvoyez nil pour le Type et rouvrez l’écran.

Exemples

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