Flutter SDKでフローのデータを処理する

ユーザーがフローの入力フィールドに文字を入力したり、クイズに答えたり、トグルを切り替えたりすると、SDKはその値をアナリティクスコールバックを通じてアプリに渡します。

アプリでそのデータを活用する主な用途は次のとおりです：

• 独自バックエンドにユーザーを登録する: オンボーディングフローでユーザーが入力したメールアドレスと名前を使って、フローが閉じたときにアカウントを作成します。
• 回答と設定を保存する: ユーザーが選択した内容を記録しておき、後でアプリが活用できるようにします。たとえば、カスタム属性としてAdapty プロファイルに書き込むことができます。
• 今後のフローをカスタマイズする: クイズの回答をカスタム属性として保存し、後のプレースメントでターゲティングすることで、各セグメントに異なるフローや、その中の異なるペイウォールを表示できます。
• サードパーティの分析プラットフォームに送信する: 回答を Amplitude や Mixpanel など、使用しているプロダクト分析ツールに転送します。

インプットとセレクタブルグループは、自動的に値を報告します。コード内でそれぞれを区別するために、ビルダーでインプットには意味のある Element ID を、セレクタブルグループには Group ID を設定してください。

始める前に

以下が必要です：

• Adapty SDK v4以降: フローのコールバックは以前のバージョンには存在しません。
• フロー＆ペイウォールビルダーで作成されたフロー: コールバックを通じて入力値を報告するのはフローのみです。
• 最近公開されたフローのバージョン: フローがこの機能が利用可能になった後に公開された場合にのみ、入力値を報告します。アプリに何も届かない場合は、フローの新しいバージョンを公開して再試行してください。

入力値を受け取る

入力値は、フローから送られる他のすべてのアナリティクスイベントと同じコールバックを通じて、flow_user_input というイベント名で届きます。AdaptyUI().setFlowsEventsObserver で登録したオブザーバーに flowViewDidReceiveAnalyticEvent を実装してください。

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  handleFlowInput(name, params);
}

flowViewDidReceiveAnalyticEvent コールバックは、スクリーンビューを含む、フローからのすべての分析イベントを配信します。

• name パラメーターにはイベント名が含まれます。ユーザー入力イベントを絞り込むには、name を flow_user_input と比較してください。
• element_type パラメーターは要素のカテゴリを示します。
• 入力値は要素タイプによって異なるパラメーターに格納されます：
  • テキストフィールド、ピッカー、トグルはユーザーの入力を value に格納します
  • セレクタブルグループは選択中のオプションを item_ids と item_titles で報告します

void handleFlowInput(String name, Map<String, dynamic> params) {
  if (name != 'flow_user_input') return;

  final elementId = params['element_id'] as String;

  // The screen the input sits on. Pair it with elementId to tell apart
  // two fields that share an Element ID on different screens.
  final screenId = params['instanceId'] as String?;

  switch (params['element_type'] as String) {
    case 'text_input':
    case 'email_input':
    case 'number_input':
    case 'phone_input':
      final text = params['value'] as String;
      break;
    case 'date_picker':
    case 'time_picker':
    case 'date_time_picker':
      // Unix time in milliseconds. Arrives as int on iOS and double on Android — read it through num.
      final date = DateTime.fromMillisecondsSinceEpoch((params['value'] as num).toInt());
      break;
    case 'single_choice':
      final optionId = (params['item_ids'] as List).cast<String>().first;
      break;
    case 'multi_choice':
      final optionIds = (params['item_ids'] as List).cast<String>();
      break;
    case 'toggle':
      final isOn = params['value'] as bool;
      break;
  }
}

コールバックが実行されることを確認するには、自分のアプリのテストビルドで入力を操作してください。コールバックハンドラーがイベントを受信しない場合は、前提条件を確認してください。この機能が利用可能になった後にフローが公開されていることを確認してください。

アプリがインプットを受け取るタイミング

以下の要素がこのイベントをトリガーします：

• テキスト、メール、数値、電話フィールド
• 日付、時刻、日時ピッカー
• 単一選択・複数選択のセレクタブルグループ、トグル

以下の要素はトリガーしません：

• パスワードフィールド、プロダクト選択、タブ切り替え
• 複数画面で共有される Header 要素内のインプット
• 重複または欠落したオプションの Element ID を持つセレクタブルグループ、あるいは別の画面で Group ID が再利用されているグループ。このようなグループは、部分的な回答ではなく、何も送信しません。

イベントがトリガーされるタイミング：

• フィールドがフォーカスを失ったとき。クリアされたフィールドは空文字列を報告し、ユーザーが一度も編集しなかったフィールドは何も報告しません。プレースホルダーは値ではありません。ユーザーがフィールドに戻って編集し、再びフォーカスを外した場合、2回目のイベントが発生します。
• ユーザーが新しい値を選択した後にピッカーを閉じたとき。値を変えずに閉じた場合は何も報告されません。
• ユーザーがオプションまたはトグルをタップしたとき。複数選択イベントはすべての選択済みオプションを列挙するため、最後の1つを選択解除すると2つの空の配列が送信されます。

イベントがトリガーされないタイミング：

• ユーザーが入力中のとき。キーストリームは存在せず、フォーカスが外れた時点でフィールドが保持している値のみが送信されます。
• ユーザーがフローを送信または閉じたとき。その時点で編集中の値は失われる可能性があります。配信の制限事項 セクションでは、最後の画面をこれに合わせて設計する方法を説明しています。
• ユーザーの操作なしに値が設定されたとき。Set as default とマークされたオプションは画面が開いたときに事前選択されており、Set Variable アクションにより別の操作からオプションを選択したり入力フィールドを埋めたりできます。どちらもイベントを送信しません。事前入力済みの入力は、ユーザーが編集した時点で初めて報告されます。

受け取る内容

コールバックは2つのイベントを配信します。name でフィルタリングして flow_user_input イベントのみを表示してください。レスポンスのJSONペイロードは次のようになります。

{
  "name": "flow_user_input",
  "instanceId": "scr_registration",
  "isBackendEvent": false,
  "isCustomerEvent": true,
  "element_id": "email",
  "element_type": "email_input",
  "value": "jane@example.com"
}

各要素が報告する内容：

回答で分岐する場合は、item_titles ではなく item_ids で比較してください。タイトルは派生値です。設定されていればオプションの Element Title、なければデフォルトロケールのテキスト、それもなければElement IDが使用されます。別の言語でフローを閲覧したユーザーには異なるテキストが表示されます。

イベントの例

これらの例は、各イベントで利用可能なプロパティと、コメント内の説明用の値を示しています。

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  name;                      // 'flow_user_input'
  params['name'];            // 'flow_user_input'
  params['instanceId'];      // 'scr_J260KU5q'
  params['isCustomerEvent']; // true
  params['isBackendEvent'];  // false
  params['element_id'];      // 'email'
  params['element_type'];    // 'email_input'
  params['value'];           // 'jane@example.com'   (String)
}

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  params['element_id'];      // 'birthday'
  params['element_type'];    // 'date_picker'
  params['value'];           // 645408000000   (Unix milliseconds — 1990-06-15, local midnight; int on iOS, double on Android)
}

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  params['element_id'];      // 'experience'
  params['element_type'];    // 'single_choice'
  params['item_ids'];        // ['pro']   (List)
  params['item_titles'];     // ['I train professionally']
}

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  params['element_id'];      // 'interests'
  params['element_type'];    // 'multi_choice'
  params['item_ids'];        // ['sports', 'music']   (List)
  params['item_titles'];     // ['Sports', 'Music']
}

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  params['element_id'];      // 'reminders'
  params['element_type'];    // 'toggle'
  params['value'];           // true   (bool)
}

デリバリーと制限事項

• 最後の値が優先されます: フィールドごとに1つのイベントが届き、キーストロークのストリームではなくユーザーが最終的に入力した値が含まれます。フィールドを編集した場合、最後のバージョンのみが届きます。
• 送信の保証はありません: ユーザーがフローを進むにつれて値が届きますが、ユーザーはどの時点でも離脱できます。一連の回答が完成したと判断する前に、フローが閉じるのを待ってください。
• ベストエフォート方式での配信: フィールドがフォーカスされているときやピッカーが開いているときにユーザーがフローを閉じたりアプリをバックグラウンドに移動したりすると、その値が失われる場合があります。

最後のフィールドの値を確実に受け取るには、入力フィールドもピッカーもない画面でフローを終了し、その画面が表示されたときに自動的に閉じるのではなく、明示的なユーザー操作によってフローを閉じてください。最後の画面に移動すると前のフィールドからフォーカスが外れ、それが値の送信をトリガーします。

オブザーバーが受け取った時点で各入力値を保存しておき、フローが閉じられたタイミングで完全なセットを送信してください。そのタイミングを検知するには、同じオブザーバーに flowViewDidDisappear を実装します。このメソッドは、ユーザーがフローを完了した場合でも途中で閉じた場合でも、フロービューが閉じられると実行されます。

ユースケース

バックエンドでユーザーを登録する

値が届き次第収集し、フローが閉じたタイミングで一度にリクエストを送ることで、1回のリクエストに完全な回答セットをまとめられます。

ユーザーがフローを完了した場合でも、途中で離脱した場合でも、ビューは閉じられます。バックエンドを呼び出す前に、必要なフィールドが揃っているかを確認してください。

フローはバックエンドからのエラーを表示できません。コールバックには戻り値がなく、SDKには実行中のフローにデータを送り込むメソッドもありません。たとえばメールアドレスがすでに使用中であるなど、登録に失敗した場合は、フローが閉じた後に独自のUIでエラーを表示してください。

final Map<String, String> flowAnswers = {};

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  if (name != 'flow_user_input') return;

  final elementId = params['element_id'];
  final value = params['value'];
  if (elementId is! String || value is! String) return;

  flowAnswers[elementId] = value;
}

void flowViewDidDisappear(AdaptyUIFlowView view) {
  if (!flowAnswers.containsKey('email')) return;

  // Send flowAnswers to your backend here to create the account.

  flowAnswers.clear();
}

ユーザープロファイルにデータを反映する

ユーザーが入力した内容をプロファイルに紐付け、同じ情報を二度入力させないようにするには、値が入力されるたびにユーザープロファイルを更新してください。

たとえば、フローにElement ID name のテキスト入力とElement ID email のメール入力がある場合：

void handleFlowInput(String name, Map<String, dynamic> params) async {
  if (name != 'flow_user_input') return;

  final value = params['value'];
  if (value is! String) return;

  final builder = AdaptyProfileParametersBuilder();

  switch (params['element_id'] as String) {
    case 'name':
      builder.setFirstName(value);
      break;
    case 'email':
      builder.setEmail(value);
      break;
    default:
      return;
  }

  try {
    await Adapty().updateProfile(builder.build());
  } on AdaptyError catch (adaptyError) {
    // handle the error
  }
}

後のフローをカスタマイズする

クイズの回答を使って、後のプレースメントでユーザーに表示するコンテンツ（別のフロー、またはその中の別のペイウォール）を決定することもできます。

たとえば、オンボーディングフローでスポーツの経験について質問し、各グループに異なるプロダクトとコピーを持つ独自のフローを表示できます。

1. フローにクイズを追加します。選択可能グループにグループ ID experience を設定し、各オプションにわかりやすい要素 ID を設定します。
2. 回答を処理し、ユーザーにカスタム属性を設定します。

void handleFlowInput(String name, Map<String, dynamic> params) async {
  if (name != 'flow_user_input') return;
  if (params['element_id'] != 'experience') return;

  final optionId = (params['item_ids'] as List).cast<String>().first;

  final builder = AdaptyProfileParametersBuilder();
  // Set the custom attribute 'experience' to the option the user selected
  // (beginner, amateur, or pro).
  builder.setCustomStringAttribute(optionId, 'experience');

  try {
    await Adapty().updateProfile(builder.build());
  } on AdaptyError catch (adaptyError) {
    // handle the error
  }
}

3. セグメントを作成します（カスタム属性の値ごとに）。
4. プレースメントを作成し、各セグメントに対してオーディエンスを追加します。
5. アプリ内でそのプレースメントのフローを表示します。