---
title: "Afficher des éléments personnalisés avec le SDK Android"
description: "Affichez un composable ou une vue Android dans chaque élément personnalisé d'un flow, et testez le flow sur un appareil."
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes`

Lorsqu'un écran contenant un [élément personnalisé](flow-custom-elements) 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 \{#before-you-start\}

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](flow-custom-elements#add-and-configure).

Si votre application iOS affiche déjà des éléments personnalisés, réutilisez ses Types et IDs. Sauf si vous configurez une [audience](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 \{#create-views-for-custom-elements\}

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` :

<Tabs groupId="current-os" queryString>
<TabItem value="kotlin" label="Kotlin" default>

```kotlin showLineNumbers title="Kotlin"
@Composable
fun LottieElement(animationFile: String) {
    val composition by rememberLottieComposition(LottieCompositionSpec.Asset(animationFile))
    LottieAnimation(
        composition = composition,
        iterations = LottieConstants.IterateForever,
    )
}
```

</TabItem>
<TabItem value="java" label="Java">

```java showLineNumbers title="Java"
public class LottieViews {
    public static View createLottieView(Context context, String animationFile) {
        LottieAnimationView view = new LottieAnimationView(context);
        view.setAnimation(animationFile);
        view.setRepeatCount(LottieDrawable.INFINITE);
        view.playAnimation();
        return view;
    }
}
```

</TabItem>
</Tabs>

### Exigences et bonnes pratiques \{#requirements-and-best-practices\}

- **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**](flow-custom-elements#add-and-configure).
- **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](flow-selectable-elements). 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](builder-containers#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 \{#write-a-resolver-to-match-custom-elements-and-views\}

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](#create-views-for-custom-elements). L'ID désigne le fichier d'animation dans le dossier `assets`, par exemple `welcome_wave` pour `welcome_wave.json` :

<Tabs groupId="current-os" queryString>
<TabItem value="kotlin" label="Kotlin" default>

```kotlin showLineNumbers title="Kotlin"
class CustomElementsResolver(context: Context) : AdaptyCustomElementsResolver {
    // the animation files in the assets folder, listed once
    private val animationFiles: Set<String> = try {
        context.assets.list("").orEmpty().toSet()
    } catch (e: IOException) {
        emptySet() // no list of files: every Lottie element shows the fallback
    }

    override fun resolve(type: String, id: String): AdaptyCustomElementContent? =
        when (type) {
            "lottie_animation" -> {
                // the ID names the animation file, such as welcome_wave.json
                val file = "$id.json"
                if (file in animationFiles) {
                    AdaptyCustomElementContent.compose { LottieElement(file) }
                } else {
                    null // no file for this ID: show the fallback
                }
            }
            else -> null
        }
}
```

</TabItem>
<TabItem value="java" label="Java">

```java showLineNumbers title="Java"
public class CustomElementsResolver implements AdaptyCustomElementsResolver {
    // the animation files in the assets folder, listed once
    private final Set<String> animationFiles = new HashSet<>();

    public CustomElementsResolver(Context context) {
        try {
            String[] files = context.getAssets().list("");
            if (files != null) {
                animationFiles.addAll(Arrays.asList(files));
            }
        } catch (IOException e) {
            // no list of files: every Lottie element shows the fallback
        }
    }

    @Override
    public AdaptyCustomElementContent resolve(String type, String id) {
        if (type.equals("lottie_animation")) {
            // the ID names the animation file, such as welcome_wave.json
            String file = id + ".json";
            if (!animationFiles.contains(file)) {
                return null; // no file for this ID: show the fallback
            }
            return AdaptyCustomElementContent.view(
                    (context, elementContext) -> LottieViews.createLottieView(context, file)
            );
        }
        return null;
    }
}
```

</TabItem>
</Tabs>

Pour tout autre type, retournez `null`. Si vous [ajoutez un élément personnalisé avec un nouveau type](flow-custom-elements#what-changes-require-an-app-release) 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](#create-views-for-custom-elements), 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](android-custom-element-lottie-animation), 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 \{#set-conditions-for-fallback-content\}

Pour afficher le [contenu de secours](flow-custom-elements#set-fallback-content) à 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](#write-a-resolver-to-match-custom-elements-and-views) 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](android-custom-element-map#3-match-the-map-to-the-custom-element) 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 \{#pass-the-resolver-to-the-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](android-custom-element-lottie-animation), 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](android-custom-element-interactive-chart), 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 \{#display-views-in-every-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` :

<Tabs groupId="current-os" queryString>
<TabItem value="kotlin" label="Kotlin" default>

```kotlin showLineNumbers title="Kotlin"
class App : Application() {
    // keep this instance: a resolver for one flow can reuse it
    // lazy: the context isn't attached yet while App is constructed
    val customElementsResolver by lazy { CustomElementsResolver(this) }

    override fun onCreate() {
        super.onCreate()
        AdaptyUI.setCustomElementsResolver(customElementsResolver)
    }
}
```

</TabItem>
<TabItem value="java" label="Java">

```java showLineNumbers title="Java"
public class App extends Application {
    // keep this instance: a resolver for one flow can reuse it
    private CustomElementsResolver customElementsResolver;

    @Override
    public void onCreate() {
        super.onCreate();
        customElementsResolver = new CustomElementsResolver(this);
        AdaptyUI.setCustomElementsResolver(customElementsResolver);
    }

    public CustomElementsResolver getCustomElementsResolver() {
        return customElementsResolver;
    }
}
```

</TabItem>
</Tabs>

:::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](#set-conditions-for-fallback-content).

```kotlin showLineNumbers title="Kotlin"
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 \{#display-data-for-one-flow\}

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 :

<Tabs groupId="current-os" queryString>
<TabItem value="kotlin" label="Kotlin" default>

```kotlin showLineNumbers title="Kotlin"
class ExportPaywallResolver(
    private val document: Document, // the document that the user wants to export
    private val appWideResolver: AdaptyCustomElementsResolver,
) : AdaptyCustomElementsResolver {

    override fun resolve(type: String, id: String): AdaptyCustomElementContent? =
        if (type == "document_preview") {
            AdaptyCustomElementContent.compose { DocumentPreview(document) }
        } else {
            // other Types: the views of the app-wide resolver
            appWideResolver.resolve(type, id)
        }
}
```

</TabItem>
<TabItem value="java" label="Java">

```java showLineNumbers title="Java"
public class ExportPaywallResolver implements AdaptyCustomElementsResolver {
    private final Document document; // the document that the user wants to export
    private final AdaptyCustomElementsResolver appWideResolver;

    public ExportPaywallResolver(Document document, AdaptyCustomElementsResolver appWideResolver) {
        this.document = document;
        this.appWideResolver = appWideResolver;
    }

    @Override
    public AdaptyCustomElementContent resolve(String type, String id) {
        if (type.equals("document_preview")) {
            return AdaptyCustomElementContent.view(
                    (context, elementContext) -> new DocumentPreviewView(context, document)
            );
        }
        // other Types: the views of the app-wide resolver
        return appWideResolver.resolve(type, id);
    }
}
```

</TabItem>
</Tabs>

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

<Tabs groupId="current-os" queryString>
<TabItem value="kotlin" label="Kotlin" default>

```kotlin showLineNumbers title="Kotlin"
val app = activity.application as App

val flowView = AdaptyUI.getFlowView(
    activity,
    flowConfiguration,
    products = null,
    eventListener = eventListener,
    customElementsResolver = ExportPaywallResolver(
        document = document,
        appWideResolver = app.customElementsResolver, // the instance that you set app-wide
    ),
)
```

</TabItem>
<TabItem value="java" label="Java">

```java showLineNumbers title="Java"
App app = (App) activity.getApplication();

AdaptyFlowView flowView = AdaptyUI.getFlowView(
        activity,
        flowConfiguration,
        null, // products
        eventListener,
        // defaults: if your app passes other values here, keep them
        AdaptyFlowInsets.Unspecified,
        AdaptyCustomAssets.Empty,
        AdaptyUiTagResolver.Default,
        AdaptyUiTimerResolver.Default,
        null, // observerModeHandler
        new ExportPaywallResolver(document, app.getCustomElementsResolver())
);
```

</TabItem>
</Tabs>

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](android-present-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 \{#test-on-a-device\}

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](test-devices).
2. Pour voir les avertissements du SDK Adapty dans Logcat, définissez le [niveau de log](sdk-installation-android#logging) 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](#display-data-for-one-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**](flow-custom-elements#add-and-configure).

   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 \{#examples\}

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

- [Afficher la progression d'un utilisateur avec une animation Lottie](android-custom-element-lottie-animation) : Un anneau qui se remplit à mesure qu'une série de jours augmente.
- [Afficher un graphique de poids interactif dans un paywall](android-custom-element-interactive-chart) : Un graphique d'objectif de poids, dans le flow de paywall qui suit le flow d'onboarding.
- [Afficher les lieux à proximité sur une carte dans un flow](android-custom-element-map) : Une carte des centres de fitness proches de chaque utilisateur.