Kotlin Multiplatform SDKでフローにデータを渡す

カスタムタグは、アプリからの値を持つカスタム変数です。変数の設定で Value comes from outside the app を選択すると、アプリはAdapty SDKを通じてその値を設定できます。たとえば、テキスト要素に「コイン:」とカスタムタグが含まれていて、アプリがタグに「120」を渡すと、ユーザーには「コイン: 120」と表示されます。

始める前に

Adapty SDK v4 以降が必要です。v4 より前のバージョンではフローが表示されません。

フローにカスタムタグを追加する

アプリの値をフローで表示するには、ビルダーでカスタムタグを設定します。

アプリが渡す各値に対してカスタムタグを作成します。
各タグをテキスト要素に挿入します。
グループ名を含む各タグのフルネームを確認してください。アプリのコードはこの名前で各値を渡します。たとえば、user グループに streak タグが含まれている場合、タグのフルネームは user.streak となります。

カスタムタグの値を渡す

アプリの値を AdaptyUI.createFlowView または createNativeFlowView の customTags パラメータに Map<String, String> 形式で渡します。

各キーは user.streak のように、カスタムタグの完全な名前です。
各値は、タグの代わりにユーザーに表示される文字列です。
各値は「1,250」のように人が読める形式にしてください。「1250.0」は不可です。Adapty はフォーマットや翻訳を行いません。

SDK はビューの作成時に値を一度だけ読み込むため、フローが開いている間は値が変わりません。


viewModelScope.launch {
    val customTags = mapOf(
        "username" to "DragonSlayer42",
        "coins" to "1,250",
    )

    AdaptyUI.createFlowView(
        flow = flow,
        customTags = customTags,
    ).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}

Compose レイアウトにフローを埋め込むには、同じ customTags パラメータを AdaptyUIFlowPlatformView コンポーザブルに渡します。異なる customTags マップを渡すと、コンポーザブルは新しいビューを作成し、ユーザーはフローの最初の画面に戻ります。


val customTags = mapOf(
    "username" to "DragonSlayer42",
    "coins" to "1,250",
)

val nativeView = AdaptyUI.createNativeFlowView(
    context = context,
    viewModelStoreOwner = activity,
    flow = flow,
    observer = myFlowObserver,
    customTags = customTags,
)


val customTags = mapOf(
    "username" to "DragonSlayer42",
    "coins" to "1,250",
)

val nativeView = AdaptyUI.createNativeFlowView(
    flow = flow,
    observer = myFlowObserver,
    customTags = customTags,
)

カスタムタグをテストするには、タグの値を設定するコードを追加した後、アプリでフローを開いてください。ビルダーのキャンバスおよびデバイスでのプレビューには初期値のみが表示されます。Adapty モバイルアプリはカスタムタグの値を設定しません。

アプリがすでに旧ペイウォールビルダーのペイウォール向けにカスタムタグの値を設定している場合は、フローにおけるカスタムタグの違いを確認してください。

値がない場合にユーザーに表示されるもの

以下の場合、ユーザーにはカスタムタグの初期値がフォールバックとして表示されます。

アプリがそのタグに値を渡していない場合。
ユーザーがアプリを値を渡すバージョンにアップデートしていない場合。
アプリのコード内の名前が、大文字・小文字を含めタグのフルネームと一致していない場合。
同じテキスト要素内の別のカスタムタグに値がない場合。その場合、そのテキスト要素内のすべてのカスタムタグが初期値を表示します。

タグの位置に何も表示しないようにするには、空の文字列を渡してください。Adapty は空の文字列を値として扱うため、フォールバックは表示されません。

例：オンボーディングの回答からBMIを表示する

フローはユーザーから回答を収集でき、カスタムタグはアプリの値を表示できます。この2つを組み合わせることで、スコア、おすすめプラン、健康指標など、回答からアプリが計算した結果をユーザーに表示できます：

フローが回答を収集し、アプリに送信します。
アプリが結果を計算します。
アプリが次のフローにカスタムタグの値として結果を渡します。

この例では、オンボーディングフローがユーザーの体重と身長を収集します。ユーザーがオンボーディングフローの最後の画面を閉じると、アプリがBMI（ボディマス指数）を計算します。そして、BMIを表示するペイウォールフローを開きます。

フローを設定する

2つのフローを作成します: ユーザーの体重と身長を収集するオンボーディングフローと、BMIを表示するペイウォールフローです。
オンボーディングフローに2つのNumber入力を追加します:
- 体重（キログラム）用。Element IDをweightに設定します。
- 身長（センチメートル）用。Element IDをheightに設定します。
両方の入力で、FormatをIntegerに設定します。入力はユーザーが入力した通りのテキストとして値を送信するため、サンプルコードは”70.5”と”70,5”を同じように読み取りません。整数には小数点区切り文字がないため、すべてのロケールで同じように読み取られます。
アプリが両方の値を確実に受け取れるよう、オンボーディングフローを入力のない画面で終了させます。その画面に、Close flowアクションを持つボタンを追加します。入力はフォーカスを失ったとき、またはユーザーが別の画面に移動したときに値を送信します。Close flowアクションは値を送信しません。サンプルコードは、ユーザーが最後の画面に到達した場合にのみペイウォールを開きます。
ペイウォールフローで、bmiという名前のカスタムタグを作成します。Initial valueフィールドにダッシュ（—）を入力します。アプリがBMIを渡さない場合、ユーザーにはダッシュが表示されます。
ペイウォールフローに「Your BMI:」という文字列を含むテキスト要素を追加します。この文字列の後に、bmiカスタムタグを挿入します。
オンボーディングフローをonboardingなどのプレースメントに追加します。ペイウォールフローをID bmi_paywallのプレースメントに追加します。BMIをペイウォールに渡すのコードは、このIDでペイウォールを取得します。

ペイウォールにBMIを渡す

オンボーディングフローのflow_user_inputイベントから体重と身長を収集します。詳細はフローからデータを処理するを参照してください。ユーザーが最後の画面に到達したことを確認するには、is_last_screenがtrueに設定されたflow_screen_showedイベントを監視します。詳細はフローの画面表示を追跡するを参照してください。その画面の後にユーザーがオンボーディングフローを閉じたら、BMIを計算します。次にペイウォールのビューを作成し、bmiカスタムタグにBMIを渡します。

flowViewDidReceiveAnalyticEventメソッドは、kotlinx.serialization.jsonライブラリを使用してイベントパラメータを解析します。プロジェクトにこのライブラリがまだない場合は、アプリの依存関係にorg.jetbrains.kotlinx:kotlinx-serialization-jsonを追加してください。次に、AdaptyUI.setFlowsEventsObserverで登録するオブザーバーに以下のメソッドを実装してください：


class MyFlowsEventsObserver(
    private val scope: CoroutineScope,
) : AdaptyUIFlowsEventsObserver {

    private val bodyAnswers = mutableMapOf<String, String>()
    private var reachedLastScreen = false

    override fun flowViewDidReceiveAnalyticEvent(
        view: AdaptyUIFlowView,
        name: String,
        paramsJsonString: String,
    ) {
        if (name != "flow_user_input" && name != "flow_screen_showed") return

        val params = Json.parseToJsonElement(paramsJsonString).jsonObject
        if (name == "flow_screen_showed") {
            if (params["is_last_screen"]?.jsonPrimitive?.booleanOrNull == true) {
                reachedLastScreen = true
            }
            return
        }
        val elementId = params["element_id"]?.jsonPrimitive?.content ?: return
        val value = params["value"]?.jsonPrimitive?.contentOrNull ?: return

        bodyAnswers[elementId] = value
    }

    override fun flowViewDidDisappear(view: AdaptyUIFlowView) {
        // The observer receives events from every flow. Reset `bodyAnswers` and
        // `reachedLastScreen` whenever a flow disappears, so that the paywall
        // doesn't open again when the user closes it.
        val answers = bodyAnswers.toMap()
        val finished = reachedLastScreen
        bodyAnswers.clear()
        reachedLastScreen = false

        // Number inputs send their values as strings.
        if (!finished) return
        val weight = answers["weight"]?.toDoubleOrNull() ?: return
        val height = answers["height"]?.toDoubleOrNull()?.takeIf { it > 0 } ?: return

        val heightInMeters = height / 100
        val bmi = weight / (heightInMeters * heightInMeters)
        val bmiText = ((bmi * 10).roundToInt() / 10.0).toString()

        scope.launch { showBmiPaywall(bmiText) }
    }
}

suspend fun showBmiPaywall(bmi: String) {
    Adapty.getFlow(placementId = "bmi_paywall").onSuccess { flow ->
        AdaptyUI.createFlowView(
            flow = flow,
            customTags = mapOf("bmi" to bmi),
        ).onSuccess { view ->
            view.present()
        }.onError { error ->
            // handle the error
        }
    }.onError { error ->
        // handle the error
    }
}

toString は小数点区切り文字として常にピリオドを使用します（例：「22.7」）。ユーザーのロケールに応じた区切り文字を使用するには、各プラットフォームのロケール対応フォーマッターを使用してください（Androidなら java.text.NumberFormat、iOSなら NSNumberFormatter など）。

BMIをユーザーのプロファイルに保存する

BMIに基づいてユーザーに異なるフローを表示するには、BMIをプロファイルのカスタム属性として保存します。Adapty ダッシュボードで、キー bmi を持つ Number 型のカスタム属性を作成してください。その後、その属性から作成したオーディエンスに各フローを表示します。

flowViewDidDisappear 内の bmi を計算する行のすぐ後で updateProfile メソッドを呼び出します。セグメントがBMIをしきい値と比較できるよう、フォーマット済みの文字列ではなく Double 型の値を渡してください：


val params = AdaptyProfileParameters.Builder()
    .withCustomAttribute("bmi", bmi)
    .build()

scope.launch {
    Adapty.updateProfile(params).onError { error ->
        // handle the error
    }
}