React Native SDKでオンボーディングを表示する

オンボーディングは SDK v4 で非推奨となり、将来のリリースで削除される予定です。 バグ修正や改善は行われません。代わりにフローを使用してください。オンボーディングは WebView 内で動作しますが、フローはデバイス上でネイティブにレンダリングされるため、よりスムーズなアニメーション、一貫したネイティブの外観、高速な読み込み、WebView ランタイムへの依存がありません。詳しくはフローとペイウォールの取得およびフローとペイウォールの表示をご覧ください。

ペイウォールビルダーを使ってオンボーディングをカスタマイズした場合、モバイルアプリのコード上でレンダリング処理を実装しなくても、ユーザーに表示できます。このようなオンボーディングには、表示する内容と表示方法の両方が含まれています。

始める前に、以下を確認してください：

Adapty React Native SDK 3.8.0 以降をインストール済みであること。
オンボーディングを作成済みであること。
オンボーディングをプレースメントに追加済みであること。

Adapty React Native SDK では、オンボーディングを表示する方法が2つあります：

Reactコンポーネント: 埋め込み型コンポーネントとして、アプリのアーキテクチャやナビゲーションシステムに統合できます。
モーダル表示

React コンポーネント

AdaptyOnboardingView コンポーネントを React Native のコンポーネント階層に直接組み込むことで、既存のコンポーネントツリーにオンボーディングを埋め込めます。埋め込み型コンポーネントを使うと、アプリのアーキテクチャやナビゲーションシステムとシームレスに統合できます。

Android では、視覚的なレンダリングアーティファクトを避けるために、AdaptyOnboardingView の追加設定を推奨します。詳しくは Android でシステム UI がオンボーディングコンテンツと重なる場合を参照してください。


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

オンボーディングをユーザーが閉じられるスタンドアロン画面として表示するには、createOnboardingView メソッドで作成した view に対して view.present() メソッドを使用します。各 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.setEventHandlers(); // handle close press, etc

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

iOSの表示スタイルを設定する

present() メソッドに iosPresentationStyle パラメーターを渡すことで、iOSでのペイウォールの表示方法を設定できます。パラメーターには '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 マネージドワークフローでは、カスタムネイティブレイアウト（Android の res/layout など）を配置することはサポートされていません。Expo アプリの場合、スプラッシュスクリーンを制御するか、React Native オーバーレイを使用するのが唯一の選択肢です。

Android と iOS それぞれのプラットフォーム固有のレイアウトを使って、ネイティブローダーを差し替えることができます。モーダル表示を使用している場合は、この方法が唯一の選択肢になります。

ただし、React Native アプリではこのアプローチは通常あまり便利ではありません。

Android と iOS で別々の実装が必要
Expo マネージドワークフローとは互換性がない各プラットフォーム向けにプレースホルダーを定義します：
iOS: AdaptyOnboardingPlaceholderView.xib を Xcode プロジェクトに追加します。詳細はこちら。
Android: res/layout に adapty_onboarding_placeholder_view.xml を作成し、プレースホルダーを定義します。詳細はこちら。

オンボーディングでのリンクの開き方をカスタマイズする

オンボーディングでのリンクの開き方のカスタマイズは、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
}

トラブルシューティング

システムUIがAndroidのオンボーディングコンテンツと重なる

この設定はベアReact Nativeプロジェクトでのみサポートされています。

Expoマネージドワークフローを使用している場合、このAndroidリソースを直接追加することはできません。この設定を適用するには、対応するAndroidリソースを追加するカスタムExpo設定プラグインを作成し、app.config.jsに登録する必要があります。ExpoがネイティブAndroidプロジェクトを管理しているため、この手順が必要です。

AndroidでAdaptyOnboardingViewを使用すると、ステータスバーやナビゲーションバーなどのシステムUI要素がペイウォールコンテンツの上に表示される場合があります。これを防ぐには、次のboolean リソースをアプリに追加してください：

android/app/src/main/res/values に移動します。bools.xml ファイルがない場合は作成してください。
次のリソースを追加します：

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

この変更はアプリ内のすべてのオンボーディングにグローバルに適用されます。

次のステップ

オンボーディングを表示したら、ユーザーのインタラクションとイベントの処理について確認しましょう。オンボーディングイベントを処理して、ユーザーのアクションに応答したりアナリティクスを追跡したりする方法を学べます。