English 中文TürkçeРусскийEspañol日本語Tiếng Việt

Flutter SDK でのオンボーディングイベントの処理

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

ビルダーで設定されたオンボーディングは、アプリが応答できるイベントを生成します。これらのイベントの処理方法は、どのプレゼンテーション方式を使用しているかによって異なります。

  • フルスクリーン表示：すべてのオンボーディングビューのイベントを処理するグローバルイベントオブザーバーの設定が必要です
  • 埋め込みウィジェット：ウィジェット内のインラインコールバックパラメーターを通じてイベントを処理します

開始する前に、以下を確認してください。

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

フルスクリーン表示のイベント

イベントオブザーバーの設定

フルスクリーンオンボーディングのイベントを処理するには、AdaptyUIOnboardingsEventsObserverを実装して、表示前に設定します：

AdaptyUI().setOnboardingsEventsObserver(this);

try {
  await onboardingView.present();
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

イベントを処理する

以下のメソッドをオブザーバーに実装してください：

void onboardingViewDidFinishLoading(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
) {
  // Onboarding finished loading
}

void onboardingViewDidFailWithError(
  AdaptyUIOnboardingView view,
  AdaptyError error,
) {
  // Handle loading errors
}

void onboardingViewOnCloseAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Handle close action
  view.dismiss();
}

void onboardingViewOnPaywallAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Dismiss onboarding before presenting paywall
  view.dismiss().then((_) {
    _openPaywall(actionId);
  });
}

void onboardingViewOnCustomAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Handle custom actions
}

void onboardingViewOnStateUpdatedAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String elementId,
  AdaptyOnboardingsStateUpdatedParams params,
) {
  // Handle user input updates
}

void onboardingViewOnAnalyticsEvent(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  AdaptyOnboardingsAnalyticsEvent event,
) {
  // Track analytics events
}

埋め込みウィジェットのイベント

AdaptyUIOnboardingPlatformView を使用する場合、ウィジェット内のインラインコールバックパラメータを通じてイベントを直接処理できます。イベントはウィジェットのコールバックとグローバルオブザーバーの両方に送信されますが、グローバルオブザーバーの設定は任意です。

AdaptyUIOnboardingPlatformView(
  onboarding: onboarding,
  onDidFinishLoading: (meta) {
    // Onboarding finished loading
  },
  onDidFailWithError: (error) {
    // Handle loading errors
  },
  onCloseAction: (meta, actionId) {
    // Handle close action
  },
  onPaywallAction: (meta, actionId) {
    _openPaywall(actionId);
  },
  onCustomAction: (meta, actionId) {
    // Handle custom actions
  },
  onStateUpdatedAction: (meta, elementId, params) {
    // Handle user input updates
  },
  onAnalyticsEvent: (meta, event) {
    // Track analytics events
  },
)

イベントの種類

以下のセクションでは、使用しているプレゼンテーション方式に関わらず処理できる各種イベントについて説明します。

カスタムアクションの処理

ビルダーでは、ボタンにカスタムアクションを追加してIDを割り当てることができます。

ios-events-1.webp

ユーザーがカスタムボタン（Login や Allow notifications など）をタップすると、デリゲートメソッド onboardingController が .custom(id:) ケースでトリガーされ、actionId パラメーターにはビルダーで設定した Action ID が渡されます。このIDをコード内で使用して、カスタムアクションとして処理できます。IDは「allowNotifications」のように自由に設定できます。

// Full-screen presentation
void onboardingViewOnCustomAction(
    AdaptyUIOnboardingView view,
    AdaptyUIOnboardingMeta meta,
    String actionId,
) {
    switch (actionId) {
        case 'login':
            _login();
            break;
        case 'allow_notifications':
            _allowNotifications();
            break;
    }
}

// Embedded widget
onCustomAction: (meta, actionId) {
    _handleCustomAction(actionId);
}
イベント例（クリックして展開）
{
  "actionId": "allowNotifications",
  "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 0,
    "screensTotal": 3
  }
}

オンボーディングの読み込み完了

オンボーディングの読み込みが完了すると、次のイベントがトリガーされます。

// Full-screen presentation
void onboardingViewDidFinishLoading(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
) {
  print('Onboarding loaded: ${meta.onboardingId}');
}

// Embedded widget
onDidFinishLoading: (meta) {
  print('Onboarding loaded: ${meta.onboardingId}');
}
イベントの例（クリックして展開）
{
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "welcome_screen",
        "screen_index": 0,
        "total_screens": 4
    }
}

オンボーディングを閉じる

ユーザーが Close アクションが割り当てられたボタンをタップすると、オンボーディングは閉じられたとみなされます。

ios-events-2.webp

ユーザーがオンボーディングを閉じたときの動作は、ご自身で管理する必要があります。たとえば、オンボーディング自体の表示を停止する処理が必要です。

// Full-screen presentation
void onboardingViewOnCloseAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  await view.dismiss();
}

// Embedded widget
onCloseAction: (meta, actionId) {
  Navigator.of(context).pop();
}
イベント例（クリックして展開）
{
  "action_id": "close_button",
  "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "final_screen",
    "screen_index": 3,
    "total_screens": 4
  }
}

ペイウォールを開く

オンボーディング内でペイウォールを開きたい場合は、このイベントを処理してください。ペイウォールが閉じた後に別のペイウォールを開きたい場合は、もっとシンプルな方法があります。クローズアクションを処理して、イベントデータに依存せずにペイウォールを開いてください。

オンボーディングでペイウォールをシームレスに扱うには、アクションIDをペイウォールのプレースメントIDと同じにするのがベストです。

iOSでは、ペイウォールまたはオンボーディングの1つのビューのみが画面上に同時に表示できます。オンボーディングの上にペイウォールを表示した場合、バックグラウンドのオンボーディングをプログラムで操作することはできません。オンボーディングを閉じようとすると、代わりにペイウォールが閉じられ、オンボーディングが残ったままになります。これを避けるため、ペイウォールを表示する前に必ずオンボーディングのビューを閉じてください。

// Full-screen presentation
void onboardingViewOnPaywallAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Dismiss onboarding before presenting paywall
  view.dismiss().then((_) {
    _openPaywall(actionId);
  });
}

Future<void> _openPaywall(String actionId) async {
  // Implement your paywall opening logic here
}

// Embedded widget
onPaywallAction: (meta, actionId) {
  _openPaywall(actionId);
}
イベントの例（クリックして展開）
{
    "action_id": "premium_offer_1",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "pricing_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}

ナビゲーションの追跡

オンボーディングフロー中にさまざまなナビゲーション関連イベントが発生すると、アナリティクスイベントを受け取ります。

// Full-screen presentation
void onboardingViewOnAnalyticsEvent(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  AdaptyOnboardingsAnalyticsEvent event,
) {
  trackEvent(event.type, meta.onboardingId);
}

// Embedded widget
onAnalyticsEvent: (meta, event) {
  trackEvent(event.type, meta.onboardingId);
}

event オブジェクトは以下のいずれかのタイプになります。

タイプ説明
onboardingStartedオンボーディングが読み込まれたとき
screenPresented任意の画面が表示されたとき
screenCompleted画面が完了したとき。オプションの elementId（完了した要素の識別子）とオプションの reply（ユーザーからの回答）を含みます。ユーザーが画面を離れるための操作を行ったときにトリガーされます。
secondScreenPresented2番目の画面が表示されたとき
userEmailCollected入力フィールドでユーザーのメールアドレスが収集されたときにトリガーされます
onboardingCompletedユーザーが final IDを持つ画面に到達したときにトリガーされます。このイベントが必要な場合は、最後の画面に final IDを割り当ててください。
unknown認識されないイベントタイプに対して使用されます。name（不明なイベントの名前）と meta（追加のメタデータ）を含みます
各イベントには以下のmeta情報が含まれます：
フィールド説明
onboardingIdオンボーディングフローの一意識別子
screenClientId現在のスクリーンの識別子
screenIndexフロー内での現在のスクリーンの位置
screensTotalフロー内のスクリーンの合計数
イベントの例（クリックして展開）
// onboardingStarted
{
  "name": "onboarding_started",
  "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "welcome_screen",
    "screen_index": 0,
    "total_screens": 4
  }
}

// screenPresented

{
    "name": "screen_presented",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "interests_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}

// screenCompleted

{
    "name": "screen_completed",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    },
    "params": {
        "element_id": "profile_form",
        "reply": "success"
    }
}

// secondScreenPresented

{
    "name": "second_screen_presented",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    }
}

// userEmailCollected

{
    "name": "user_email_collected",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    }
}

// onboardingCompleted

{
    "name": "onboarding_completed",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "final_screen",
        "screen_index": 3,
        "total_screens": 4
    }
}