Отображение онбордингов в React Native SDK

Если вы настроили онбординг с помощью билдера, вам не нужно беспокоиться о его отрисовке в коде мобильного приложения для показа пользователю. Такой онбординг содержит и то, что должно отображаться, и то, как это должно выглядеть.

Перед началом убедитесь, что:

Вы установили Adapty React Native SDK версии 3.8.0 или новее.
Вы создали онбординг.
Вы добавили онбординг в плейсмент.

Adapty React Native SDK предоставляет два способа показа онбордингов:

React-компонент: встроенный компонент позволяет интегрировать его в архитектуру приложения и систему навигации.
Модальное представление

React-компонент

Чтобы встроить онбординг в существующее дерево компонентов, используйте компонент AdaptyOnboardingView напрямую в иерархии React Native-компонентов. Встроенный компонент позволяет интегрировать его в архитектуру и навигационную систему приложения.

На Android рекомендуем выполнить дополнительную настройку AdaptyOnboardingView, чтобы избежать визуального артефакта при рендеринге. См. Системный UI перекрывает контент онбординга на 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
        },
      }}
    />
  );
}

Чтобы отобразить онбординг как отдельный экран, который пользователь может закрыть, вызовите метод view.present() на view, созданном методом createOnboardingView. Каждый view можно использовать только один раз. Если нужно показать онбординг снова, вызовите createOnboardingView ещё раз, чтобы создать новый экземпляр view.

Повторное использование одного и того же view без его пересоздания запрещено. Это приведёт к ошибке 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.registerEventHandlers(); // handle close press, etc

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

Настройка стиля презентации для iOS

Настройте способ отображения онбординга на iOS, передав параметр iosPresentationStyle в метод present(). Параметр принимает значения 'full_screen' (по умолчанию) или 'page_sheet'.

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

Загрузчик во время онбординга

При отображении онбординга в React Native вы можете заметить короткую белую вспышку или экран загрузки до того, как онбординг появится. Это происходит, пока нативный вид инициализируется. Справиться с этим можно по-разному — в зависимости от ваших потребностей и рабочего процесса.

Управление сплэш-экраном с помощью onFinishedLoading

Этот подход доступен только при использовании React-компонента. Для модальной презентации он недоступен.

Рекомендуемый подход для React Native — удерживать сплэш-экран или пользовательский оверлей видимым до полной загрузки онбординга, а затем скрывать его вручную.

При использовании React-компонента (AdaptyOnboardingView) дождитесь события onFinishedLoading, прежде чем скрывать сплэш-экран или оверлей:


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 />}
    </>
  );
}

Настройка нативного загрузчика

Expo-managed workflow не поддерживает размещение пользовательских нативных макетов (например, res/layout на Android). Для приложений на Expo единственным подходящим решением является управление экраном загрузки или использование оверлея React Native.

Вы можете заменить нативный загрузчик, используя платформенные макеты на Android и iOS. Если вы используете модальное представление, это ваш единственный вариант.

Однако такой подход обычно менее удобен для приложений React Native:

Требует отдельных реализаций для Android и iOS
Несовместим с Expo-managed workflow Определите плейсхолдер для каждой платформы:
iOS: Добавьте AdaptyOnboardingPlaceholderView.xib в ваш Xcode-проект. Подробнее.
Android: Создайте adapty_onboarding_placeholder_view.xml в res/layout и определите там плейсхолдер. Подробнее.

Настройка способа открытия ссылок в онбординге

Настройка способа открытия ссылок в онбординге поддерживается начиная с Adapty SDK v3.15.1.

По умолчанию ссылки в онбординге открываются во встроенном браузере. Это обеспечивает бесшовный пользовательский опыт: веб-страницы отображаются прямо внутри приложения, и пользователям не нужно переключаться между приложениями.

Если вы хотите открывать ссылки во внешнем браузере, это поведение можно изменить, установив параметр externalUrlsPresentation в значение 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
}

Устранение неполадок

Системный интерфейс перекрывает контент онбординга на Android

Эта настройка поддерживается только в bare-проектах React Native.

Если вы используете Expo managed workflow, добавить этот Android-ресурс напрямую не получится. Чтобы применить эту настройку, нужно создать пользовательский Expo config plugin, который добавит соответствующий Android-ресурс, и зарегистрировать его в app.config.js. Это необходимо, потому что Expo управляет нативным Android-проектом за вас.

При использовании AdaptyOnboardingView на Android системные элементы интерфейса — строка состояния и панель навигации — могут отображаться поверх контента онбординга. Чтобы этого избежать, добавьте следующий булев ресурс в ваше приложение:

Перейдите в android/app/src/main/res/values. Если файла bools.xml нет — создайте его.
Добавьте следующий ресурс:

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

Обратите внимание, что это изменение применяется глобально ко всем онбордингам в вашем приложении.

Дальнейшие шаги

После отображения онбординга вам нужно будет обработать действия пользователя и события. Узнайте, как обрабатывать события онбординга, чтобы реагировать на действия пользователей и отслеживать аналитику.

Отображение онбордингов в React Native SDK

React-компонент

Модальное отображение

Настройка стиля презентации для iOS

Загрузчик во время онбординга

Управление сплэш-экраном с помощью onFinishedLoading

Настройка нативного загрузчика

Настройка способа открытия ссылок в онбординге

Устранение неполадок

Системный интерфейс перекрывает контент онбординга на Android

Дальнейшие шаги