Kotlin Multiplatform SDK'da flow'lara veri aktarma

Özel etiket, uygulamanızdan gelen bir değere sahip özel bir değişkendir. Bir değişkenin ayarlarında Value comes from outside the app seçeneğini belirledikten sonra, uygulamanız bu değeri Adapty SDK aracılığıyla ayarlayabilir. Örneğin, bir metin öğesi “Coins:” ve bir özel etiket içeriyorsa, uygulamanız etiket için “120” değeri aktarırsa kullanıcılar “Coins: 120” görür.

Başlamadan önce

Adapty SDK v4 veya daha yenisine ihtiyacınız var. v4’ten önceki sürümler flow’ları görüntülemez.

Flow’a özel etiketler ekleyin

Uygulamanızın değerlerini bir flow’da göstermek için builder’da özel etiketler oluşturun:

Uygulamanızın ilettiği her değer için özel bir etiket oluşturun.
Her etiketi bir metin öğesine ekleyin.
Her etiketin grubu dahil tam adını not edin. Uygulamanızın kodu her değeri bu ad altında iletir. Örneğin, user grubu içinde streak adlı bir etiket varsa, etiketin tam adı user.streak olur.

Özel etiket değerlerini aktarma

Uygulamanızın değerlerini AdaptyUI.createFlowView veya createNativeFlowView metodunun customTags parametresine Map<String, String> olarak aktarın:

Her anahtar, user.streak gibi özel etiketin tam adıdır.
Her değer, kullanıcıların etikет yerine göreceği metindir.
Her değer, “1250.0” değil “1,250” gibi kullanıcı dostu bir formatta olmalıdır. Adapty değeri biçimlendirmez veya çevirmez.

SDK değerleri yalnızca bir kez, görünümü oluştururken okur; dolayısıyla flow açıkken değerler değişmez.


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 layout’una flow’u yerleştirmek için aynı customTags parametresini AdaptyUIFlowPlatformView composable’ına aktarın. Farklı bir customTags map’i geçerseniz, composable yeni bir view oluşturur ve kullanıcılar flow’un ilk ekranına geri döner.


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,
)

Özel etiketlerinizi test etmek için, değerlerini ayarlayan kodu ekledikten sonra uygulamanızda flow’u açın. Builder canvas ve cihazlarda önizleme yalnızca Başlangıç değerlerini gösterir: Adapty mobil uygulaması özel etiket değerlerini ayarlamaz.

Uygulamanız zaten eski Paywall Builder paywallları için özel tag değerleri ayarlıyorsa, flow’lardaki özel tag’lerin nasıl farklılaştığını incelemenizi öneririz.

Kullanıcıların değer olmadan gördükleri

Kullanıcılar, aşağıdaki durumlarda özel etiketin Başlangıç değerini yedek olarak görür:

Uygulamanız etikete herhangi bir değer geçmez.
Kullanıcı, değeri geçen sürüme uygulamayı güncellememiştir.
Uygulama kodunuzdaki ad, büyük/küçük harf dahil etiketin tam adıyla eşleşmez.
Aynı metin öğesindeki başka bir özel etiketin değeri yoktur. Bu durumda o metin öğesindeki tüm özel etiketler Başlangıç değerini gösterir.

Etiketin yerine hiçbir şey göstermek için boş bir dize geçin. Adapty boş dizeyi bir değer olarak kabul eder; dolayısıyla yedek değer görünmez.

Örnek: onboarding yanıtlarından BMI gösterimi

Bir flow kullanıcılardan yanıtlar toplayabilir; özel bir tag ise uygulamanızdaki bir değeri gösterebilir. Kullanıcılara, uygulamanızın yanıtlarından hesapladığı bir skoru, önerilen bir planı veya bir sağlık metriğini göstermek için ikisini birleştirebilirsiniz:

Bir flow yanıtları toplar ve uygulamanıza gönderir.
Uygulamanız sonucu hesaplar.
Uygulamanız sonucu bir sonraki flow’a özel tag değeri olarak iletir.

Bu örnekte bir onboarding flow’u kullanıcının kilosunu ve boyunu toplar. Kullanıcı onboarding flow’unu son ekranından kapattığında uygulamanız vücut kitle indeksini (VKİ) hesaplar. Ardından VKİ’yi gösteren bir paywall flow’u açar.

Flow’ları ayarlayın

İki flow oluşturun: kullanıcının kilosunu ve boyunu toplayan bir onboarding flow’u ve BMI’sini gösteren bir paywall flow’u.
Onboarding flow’una iki Number (Sayı) girişi ekleyin:
- Kilogram cinsinden ağırlık için Element ID weight olan bir girişi.
- Santimetre cinsinden boy için Element ID height olan bir girişi.
Her iki girişin Format ayarını da Integer olarak belirleyin. Bir girişi, kullanıcının yazdığı gibi değerini metin olarak gönderir; örnek kod “70.5” ile “70,5” değerlerini aynı şekilde okumaz. Tam sayılarda ondalık ayraç olmadığından kod, bunları her yerel ayarda aynı şekilde okur.
Uygulamanızın her iki değeri de aldığından emin olmak için onboarding flow’unu hiç girişi olmayan bir ekranla bitirin. O ekrana Close flow eylemi olan bir düğme ekleyin. Girişler, odağı kaybettiklerinde veya kullanıcı başka bir ekrana geçtiğinde değerlerini gönderir. Close flow eylemi bunları göndermez. Örnek kod, yalnızca kullanıcı son ekrana ulaştıysa paywall’ı açar.
Paywall flow’unda bmi adında bir özel etiket oluşturun. Initial value alanına bir tire (—) girin. Uygulamanız BMI değeri iletmezse kullanıcılar bu tireyi görür.
Paywall flow’una “Your BMI:” yazan bir metin öğesi ekleyin. Bu kelimelerin ardından bmi özel etiketini ekleyin.
Onboarding flow’unu onboarding gibi bir placement’a ekleyin. Paywall flow’unu ise bmi_paywall ID’sine sahip bir placement’a ekleyin. Pass the BMI to the paywall bölümündeki kod, paywall’ı bu ID ile çeker.

BMI’ı paywall’a aktarın

Ağırlık ve boy bilgilerini onboarding flow’unun flow_user_input olaylarından toplayın; bunu Flow’lardan veri işleme bölümünde anlatıldığı gibi yapabilirsiniz. Kullanıcının son ekrana ulaştığını anlamak için is_last_screen değeri true olarak ayarlanmış bir flow_screen_showed olayını izleyin; bu konuda Flow ekran görüntülemelerini takip etme bölümüne bakabilirsiniz. Kullanıcı o ekranın ardından onboarding flow’unu kapattığında BMI’ı hesaplayın. Ardından paywall’ın görünümünü oluşturun ve BMI’ı bmi özel etiketine aktarın.

flowViewDidReceiveAnalyticEvent metodu, kotlinx.serialization.json kütüphanesini kullanarak event parametrelerini ayrıştırır. Projenizde bu kütüphane henüz yoksa, uygulamanızın bağımlılıklarına org.jetbrains.kotlinx:kotlinx-serialization-json ekleyin. Ardından AdaptyUI.setFlowsEventsObserver ile kaydettiğiniz observer üzerinde aşağıdaki metodları uygulayın:


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 her zaman nokta kullanır ondalık ayırıcı olarak: “22.7”. Kullanıcının yerel ayarına uygun ayırıcı kullanmak için BMI değerini her platformda yerel ayar farkında bir biçimlendirici ile formatlayın; örneğin Android’de java.text.NumberFormat, iOS’ta ise NSNumberFormatter.

BMI’yı kullanıcı profiline kaydetme

Kullanıcılara BMI değerlerine göre farklı flow’lar göstermek için bunu profillerinin bir özel özelliği olarak kaydedin. Adapty Kontrol Paneli’nde bmi anahtarıyla bir Number özel özelliği oluşturun. Ardından her flow’u bu özellikten oluşturulmuş bir kitle için gösterin.

flowViewDidDisappear içinde, bmi’yı hesaplayan satırın hemen ardından updateProfile metodunu çağırın. Bir segmentin BMI’yı bir eşik değeriyle karşılaştırabilmesi için biçimlendirilmiş string yerine Double değerini geçirin:


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

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