Présenter les onboardings dans le SDK React Native

Warning

Les onboardings sont dépréciés à partir du SDK Adapty v4. Créez des flows à la place : contrairement aux onboardings, qui s’exécutent dans une WebView, les flows s’affichent nativement sur l’appareil — animations plus fluides, aspect natif cohérent, temps de chargement réduits et aucune dépendance à l’environnement WebView.

Si vous avez personnalisé un onboarding avec le builder, vous n’avez pas à vous soucier de son rendu dans le code de votre application mobile pour l’afficher à l’utilisateur. Un tel onboarding contient à la fois ce qui doit être affiché et comment cela doit l’être.

Avant de commencer, assurez-vous que :

Vous avez installé le SDK Adapty React Native 3.8.0 ou une version ultérieure.
Vous avez créé un onboarding.
Vous avez ajouté l’onboarding à un placement.

Le SDK Adapty React Native propose deux façons de présenter les onboardings :

Composant React : Le composant intégré vous permet de l’incorporer dans l’architecture et le système de navigation de votre application.
Présentation modale

Composant React

Pour intégrer un onboarding dans votre arborescence de composants existante, utilisez le composant AdaptyOnboardingView directement dans votre hiérarchie de composants React Native. Ce composant intégré vous permet de l’incorporer à l’architecture et au système de navigation de votre application.

Note

Sur Android, nous recommandons une configuration supplémentaire pour AdaptyOnboardingView afin d’éviter un artefact de rendu visuel. Voir Le contenu de l’onboarding est recouvert par l’UI système sur Android.


function MyOnboarding({ onboarding }) {
  const onAnalytics = useCallback<OnboardingEventHandlers['onAnalytics']>((event, meta) => {}, []);
  const onClose = useCallback<OnboardingEventHandlers['onClose']>((actionId, meta) => {}, []);
  const onCustom = useCallback<OnboardingEventHandlers['onCustom']>((actionId, meta) => {}, []);
  const onPaywall = useCallback<OnboardingEventHandlers['onPaywall']>((actionId, meta) => {}, []);
  const onStateUpdated = useCallback<OnboardingEventHandlers['onStateUpdated']>((action, meta) => {}, []);
  const onFinishedLoading = useCallback<OnboardingEventHandlers['onFinishedLoading']>((meta) => {}, []);
  const onError = useCallback<OnboardingEventHandlers['onError']>((error) => {}, []);

  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={styles.container}
      onAnalytics={onAnalytics}
      onClose={onClose}
      onCustom={onCustom}
      onPaywall={onPaywall}
      onStateUpdated={onStateUpdated}
      onFinishedLoading={onFinishedLoading}
      onError={onError}
    />
  );
}


function MyOnboarding({ onboarding }) {
  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={{ flex: 1 }}
      eventHandlers={{
        onAnalytics(event, meta) { 
          // Handle analytics events
        },
        onClose(actionId, meta) { 
          // Handle close actions
        },
        onCustom(actionId, meta) { 
          // Handle custom actions
        },
        onPaywall(actionId, meta) { 
          // Handle paywall actions
        },
        onStateUpdated(action, meta) { 
          // Handle state updates
        },
        onFinishedLoading(meta) { 
          // Handle when onboarding finishes loading
        },
        onError(error) { 
          // Handle errors
        },
      }}
    />
  );
}

Pour afficher un onboarding en tant qu’écran autonome que les utilisateurs peuvent fermer, utilisez la méthode view.present() sur la view créée par la méthode createOnboardingView. Chaque view ne peut être utilisée qu’une seule fois. Si vous devez afficher l’onboarding à nouveau, appelez createOnboardingView une nouvelle fois pour créer une nouvelle instance de view.

Warning

Réutiliser la même view sans la recréer est interdit. Cela entraînera une erreur AdaptyUIError.viewAlreadyPresented.


const view = await createOnboardingView(onboarding);

// Optional: handle onboarding events (close, custom actions, etc)
// view.setEventHandlers({ ... });

try {
    await view.present();
} catch (error) {
    // handle the error
}


const view = await createOnboardingView(onboarding);

view.setEventHandlers(); // handle close press, etc

try {
    await view.present();
} catch (error) {
    // handle the error
}

Configurer le style de présentation iOS

Configurez la façon dont l’onboarding est présenté sur iOS en passant le paramètre iosPresentationStyle à la méthode present(). Ce paramètre accepte les valeurs 'full_screen' (par défaut) ou 'page_sheet'.

try {
  await view.present({ iosPresentationStyle: 'page_sheet' });
} catch (error) {
  // handle the error
}

Écran de chargement pendant l’onboarding

Lorsque vous affichez un onboarding dans React Native, vous pouvez remarquer un bref flash blanc ou un écran de chargement avant que l’onboarding n’apparaisse. Cela se produit pendant que la vue native sous-jacente est en cours d’initialisation. Vous pouvez gérer cela de différentes manières selon vos besoins et votre flux de travail.

Contrôler l’écran de démarrage avec onFinishedLoading

Note

Cette approche n’est disponible qu’avec le composant React. Elle n’est pas disponible pour la présentation en modal.

L’approche recommandée pour React Native est de maintenir votre écran de démarrage ou un overlay personnalisé visible jusqu’à ce que l’onboarding soit entièrement chargé, puis de le masquer manuellement.

Avec le composant React (AdaptyOnboardingView), attendez l’événement onFinishedLoading avant de masquer votre écran de démarrage ou overlay :


function MyOnboarding({ onboarding }) {
  const [isLoading, setIsLoading] = useState(true);

  const onFinishedLoading = useCallback<OnboardingEventHandlers['onFinishedLoading']>((meta) => {
    // Hide your splash screen or custom overlay here
    setIsLoading(false);
  }, []);

  return (
    <>
      <AdaptyOnboardingView
        onboarding={onboarding}
        onFinishedLoading={onFinishedLoading}
        // ... other callbacks
      />
      {isLoading && <YourCustomLoadingOverlay />}
    </>
  );
}


function MyOnboarding({ onboarding }) {
  const [isLoading, setIsLoading] = useState(true);

  return (
    <>
      <AdaptyOnboardingView
        onboarding={onboarding}
        eventHandlers={{
          onFinishedLoading(meta) {
            // Hide your splash screen or custom overlay here
            setIsLoading(false);
          },
          // ... other handlers
        }}
      />
      {isLoading && <YourCustomLoadingOverlay />}
    </>
  );
}

Personnaliser le loader natif

Important

Le workflow géré par Expo ne prend pas en charge le placement de layouts natifs personnalisés (par exemple, res/layout sur Android). Pour les applications Expo, la seule solution viable est de contrôler le splash screen ou d’utiliser un overlay React Native.

Vous pouvez remplacer le loader natif en utilisant des layouts spécifiques à chaque plateforme sur Android et iOS. Si vous utilisez une présentation modale, c’est votre seule option.

Cette approche est cependant généralement moins pratique pour les applications React Native :

Nécessite des implémentations distinctes pour Android et iOS
Non compatible avec le workflow géré par Expo

Définissez un placeholder pour chaque plateforme :

iOS : Ajoutez AdaptyOnboardingPlaceholderView.xib à votre projet Xcode. En savoir plus.
Android : Créez adapty_onboarding_placeholder_view.xml dans res/layout et définissez-y un placeholder. En savoir plus.

Personnaliser l’ouverture des liens dans les onboardings

Important

La personnalisation de l’ouverture des liens dans les onboardings est disponible à partir du SDK Adapty v3.15.1.

Par défaut, les liens dans les onboardings s’ouvrent dans un navigateur intégré à l’application. Cela offre une expérience fluide en affichant les pages web directement dans votre application, sans que l’utilisateur ait à changer d’app.

Si vous préférez ouvrir les liens dans un navigateur externe, vous pouvez personnaliser ce comportement en définissant le paramètre externalUrlsPresentation sur WebPresentation.BrowserOutApp :


function MyOnboarding({ onboarding }) {
  const onAnalytics = useCallback<OnboardingEventHandlers['onAnalytics']>((event, meta) => {}, []);
  const onClose = useCallback<OnboardingEventHandlers['onClose']>((actionId, meta) => {}, []);
  const onCustom = useCallback<OnboardingEventHandlers['onCustom']>((actionId, meta) => {}, []);
  const onPaywall = useCallback<OnboardingEventHandlers['onPaywall']>((actionId, meta) => {}, []);
  const onStateUpdated = useCallback<OnboardingEventHandlers['onStateUpdated']>((action, meta) => {}, []);
  const onFinishedLoading = useCallback<OnboardingEventHandlers['onFinishedLoading']>((meta) => {}, []);
  const onError = useCallback<OnboardingEventHandlers['onError']>((error) => {}, []);

  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={styles.container}
      externalUrlsPresentation={WebPresentation.BrowserOutApp} // default – BrowserInApp
      onAnalytics={onAnalytics}
      onClose={onClose}
      onCustom={onCustom}
      onPaywall={onPaywall}
      onStateUpdated={onStateUpdated}
      onFinishedLoading={onFinishedLoading}
      onError={onError}
    />
  );
}


const view = await createOnboardingView(
  onboarding, 
  { externalUrlsPresentation: WebPresentation.BrowserOutApp } // default – BrowserInApp
);

try {
    await view.present();
} catch (error) {
    // handle the error
}

Résolution des problèmes

L’interface système empiète sur le contenu de l’onboarding sur Android

Note

Ce paramètre n’est pris en charge que dans les projets React Native « bare ».

Si vous utilisez un workflow Expo géré, vous ne pouvez pas ajouter cette ressource Android directement. Pour appliquer ce paramètre, vous devez créer un plugin de configuration Expo personnalisé qui ajoute la ressource Android correspondante et l’enregistrer dans app.config.js. Cela est nécessaire car Expo gère le projet Android natif à votre place.

Lorsque vous utilisez AdaptyOnboardingView sur Android, les éléments de l’interface système tels que la barre d’état et la barre de navigation peuvent apparaître par-dessus le contenu du paywall. Pour éviter cela, ajoutez la ressource booléenne suivante à votre application :

Accédez à android/app/src/main/res/values. S’il n’existe pas de fichier bools.xml, créez-en un.
Ajoutez la ressource suivante :

<resources>
    <bool name="adapty_onboarding_enable_safe_area_paddings">false</bool>
</resources>

Notez que ces modifications s’appliquent globalement à tous les onboardings de votre application.

Étapes suivantes

Une fois votre onboarding affiché, vous voudrez gérer les interactions utilisateur et les événements. Découvrez comment gérer les événements d’onboarding pour répondre aux actions des utilisateurs et suivre les analytics.

Présenter les onboardings dans le SDK React Native

Composant React

Présentation modale

Configurer le style de présentation iOS

Écran de chargement pendant l’onboarding

Contrôler l’écran de démarrage avec onFinishedLoading

Personnaliser le loader natif

Personnaliser l’ouverture des liens dans les onboardings

Résolution des problèmes

L’interface système empiète sur le contenu de l’onboarding sur Android

Étapes suivantes