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

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

アプリでこのデータを活用する主なケース：

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

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

始める前に

以下が必要です：

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

入力値を受け取る

入力値は、フローからの他のすべてのアナリティクスイベントと同じコールバックに、イベント名 flow_user_input として届きます。他のフローイベントハンドラーと一緒にコールバックを登録してください。

didReceiveAnalyticEvent クロージャを .flow モディファイアに渡します。

Text("Hello, AdaptyUI!")
    .flow(
        isPresented: $flowPresented,
        flowConfiguration: flowConfiguration,
        didFinishPurchase: { product, purchaseResult in /* handle the event */ },
        didFailPurchase: { product, error in /* handle the error */ },
        didFinishRestore: { profile in /* handle the event */ },
        didFailRestore: { error in /* handle the error */ },
        didReceiveError: { error in flowPresented = false },
        didReceiveAnalyticEvent: { name, params in
            handleFlowInput(name: name, params: params)
        }
    )

AdaptyFlowControllerDelegate にメソッドを実装してください：

func flowController(
    _ controller: AdaptyFlowController,
    didReceiveAnalyticEvent name: String,
    params: [String: any Sendable]
) {
    handleFlowInput(name: name, params: params)
}

クロージャとデリゲートメソッドはどちらも同じ2つの引数を受け取るため、値を読み取るコードはどちらの方法でも同じです。

didReceiveAnalyticEvent コールバックは、画面表示を含むフローのすべての分析イベントを配信します。

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

func handleFlowInput(name: String, params: [String: any Sendable]) {
    guard name == "flow_user_input",
          let elementId = params["element_id"] as? String,
          let elementType = params["element_type"] as? String
    else { return }

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

    switch elementType {
    case "text_input", "email_input", "number_input", "phone_input":
        let text = params["value"] as? String
    case "date_picker", "time_picker", "date_time_picker":
        // Integer Unix time in milliseconds, not the seconds Date expects.
        let date = (params["value"] as? Int).map { Date(timeIntervalSince1970: Double($0) / 1000) }
    case "single_choice":
        let optionId = (params["item_ids"] as? [String])?.first
    case "multi_choice":
        let optionIds = params["item_ids"] as? [String]
    case "toggle":
        let isOn = params["value"] as? Bool
    default:
        break
    }
}

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

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

Important

デフォルトの入力値や選択値は、このコールバックを通じてアプリに届くことはありません。ユーザーが Set as default とマークされたオプションをそのままにして次に進んだ場合、イベントは発火しません。イベントがないことを「回答なし」と解釈しないでください — ユーザーはデフォルト値をそのままにしただけです。

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

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

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

パスワードフィールド、プロダクト選択、タブ切り替え
複数画面で共有される 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"
}

パラメーター	説明
`name`	入力イベントの場合は `flow_user_input`、画面表示の場合は `flow_screen_showed`。
`instanceId`	入力要素が属する画面のID。要素IDはフロー全体ではなく、画面内で一意です。フロー内の複数の画面に入力がある場合は、イベントのフィルタリングに `instanceId` と `element_id` を組み合わせて使用してください。
`element_id`	入力の Element ID、または選択可能なグループの Group ID。
`element_type`	イベントを送信した要素の種類。以下のパラメーターのうちどれが入力値を保持するかを決定します。
`value`	テキストフィールド、ピッカー、トグルのみ。入力値：テキストフィールドの場合は文字列、ピッカーの場合は整数、トグルの場合はブール値。
`item_ids`	単一選択・複数選択の選択可能グループのみ。選択されたオプションの Element ID（ビルダーでの表示順）。単一選択グループでは1件、複数選択グループでは任意の件数。
`item_titles`	単一選択・複数選択の選択可能グループのみ。 `item_ids` に記載されたオプションのタイトル（同じ順序）。空になることはありません。タイトルのないオプションはIDが代わりに報告されます。
`isCustomerEvent`	ユーティリティフラグ。このイベントでは常に `true`。SDKがコールバックに配信するイベントを示します。1つのハンドラーがすべてのフローイベントをアナリティクスに転送し、`name` ではなくこのフラグで分岐する場合に便利です。
`isBackendEvent`	ユーティリティフラグ。このイベントでは常に `false`。AdaptyがAdapty自身のアナリティクス用に記録するイベントを示します。`false` は、ユーザーが入力した内容がアプリにのみ届き、他には渡らないことを確認します。Adaptyはその内容を受信・保存しません。

各要素が報告する内容：

ビルダー上の要素	`element_type`	値を格納するパラメーター	保持する内容
Text、Number、Phone number 入力	`text_input`、`number_input`、`phone_input`	`value`	ユーザーが入力した生の文字列。数値も文字列として届きます（数値型ではありません）。
E-mail 入力	`email_input`	`value`	ユーザーが入力した生の文字列。ビルダーの書式バリデーションに失敗した場合も含みます。使用前にアプリ側でバリデーションしてください。
Password 入力	なし	なし	イベントを送信しません。
Date 入力	`date_picker`	`value`	選択された日付のローカル時刻の深夜0時をUnix時間（ミリ秒、整数）で表した値。
Time 入力	`time_picker`	`value`	Unix時間（ミリ秒、整数）で、分未満を切り捨てた値。
Date & Time 入力	`date_picker` と `time_picker`	`value`	日付ピッカーと時刻ピッカーの2要素。それぞれが個別のイベントを送信します。
Type ドロップダウンで Date & Time に切り替えた入力	`date_time_picker`	`value`	Unix時間（ミリ秒、整数）で、分未満を切り捨てた値。
Single choice グループ	`single_choice`	`item_ids`、`item_titles`	2つの配列。`item_ids`：選択されたオプションのElement IDを含む配列。`item_titles`：そのオプションのタイトルを含む配列。
Multi-choice グループ	`multi_choice`	`item_ids`、`item_titles`	2つの配列。`item_ids`：選択されたすべてのオプションのElement ID（ビルダーでの表示順）。`item_titles`：同じ順序でのタイトル。何も選択されていない場合、両方の配列は空になります。
Toggle グループ	`toggle`	`value`	ブール値。

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

イベントの例

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

テキスト、メール、数値、電話番号の入力（クリックして展開）

func handleFlowInput(name: String, params: [String: any Sendable]) {
    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)
}

日付、時刻、日時ピッカー（クリックして展開）

func handleFlowInput(name: String, params: [String: any Sendable]) {
    params["element_id"];      // "birthday"
    params["element_type"];    // "date_picker"
    params["value"];           // 645408000000   (Unix milliseconds — 1990-06-15, local midnight)
}

Single choice (Click to expand)

func handleFlowInput(name: String, params: [String: any Sendable]) {
    params["element_id"];      // "experience"
    params["element_type"];    // "single_choice"
    params["item_ids"];        // ["pro"]
    params["item_titles"];     // ["I train professionally"]
}

複数選択 (クリックして展開)

func handleFlowInput(name: String, params: [String: any Sendable]) {
    params["element_id"];      // "interests"
    params["element_type"];    // "multi_choice"
    params["item_ids"];        // ["sports", "music"]
    params["item_titles"];     // ["Sports", "Music"]
}

Toggle (Click to expand)

func handleFlowInput(name: String, params: [String: any Sendable]) {
    params["element_id"];      // "reminders"
    params["element_type"];    // "toggle"
    params["value"];           // true   (Bool)
}

配信と制限事項

Warning

フローは生の値（メールアドレス、電話番号、ユーザーが入力したその他の情報）を送信します。アナリティクスコールバックが届けるものはすべて個人データとして扱い、メールアドレスを書き残さないような場所には保存しないでください。

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

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

ハンドラーが受け取った各入力値をその都度保存し、フローが閉じられたときにすべてのデータをまとめて送信してください。そのタイミングを検知するには、UIKit の場合は AdaptyFlowControllerDelegate に flowControllerDidDisappear を実装し、SwiftUI の場合は .flow モディファイアに didDisappear クロージャを渡します。どちらも、ユーザーがフローを完了した場合でも閉じた場合でも、フローのビューが画面から消えた後に実行されます。

ユースケース

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

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

ユーザーがフローを最後まで完了した場合でも、途中で離脱した場合でも、ビューは非表示になります。バックエンドを呼び出す前に、必要なフィールドの入力有無を確認してください。

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

private var flowAnswers: [String: String] = [:]

func handleFlowInput(name: String, params: [String: any Sendable]) {
    guard name == "flow_user_input",
          let elementId = params["element_id"] as? String,
          let value = params["value"] as? String
    else { return }

    flowAnswers[elementId] = value
}

func flowControllerDidDisappear(_ controller: AdaptyFlowController) {
    guard flowAnswers["email"] != nil else { return }

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

    flowAnswers.removeAll()
}

ユーザープロファイルにデータを紐づける

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

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

func handleFlowInput(name: String, params: [String: any Sendable]) {
    guard name == "flow_user_input",
          let elementId = params["element_id"] as? String,
          let value = params["value"] as? String
    else { return }

    let builder = AdaptyProfileParameters.Builder()

    switch elementId {
    case "name":
        builder.with(firstName: value)
    case "email":
        builder.with(email: value)
    default:
        return
    }

    // Delegate methods are synchronous; kick off the async update in a Task.
    Task {
        do {
            try await Adapty.updateProfile(params: builder.build())
        } catch {
            // handle the error
        }
    }
}

後続フローのカスタマイズ

クイズの回答によって、ユーザーが後から見るプレースメントの内容（別のフロー、またはその中の別のペイウォール）を変えることもできます。

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

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

func handleFlowInput(name: String, params: [String: any Sendable]) {
    guard name == "flow_user_input",
          params["element_id"] as? String == "experience",
          let optionId = (params["item_ids"] as? [String])?.first
    else { return }

    let builder = AdaptyProfileParameters.Builder()
    // Set the custom attribute 'experience' to the option the user selected
    // (beginner, amateur, or pro).
    try? builder.with(customAttribute: optionId, forKey: "experience")

    Task {
        do {
            try await Adapty.updateProfile(params: builder.build())
        } catch {
            // handle the error
        }
    }
}

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