Android 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, Adapty SDK aracılığıyla bu değeri ayarlayabilir. Örneğin, bir metin öğesi “Coins:” ve bir özel etiket içeriyorsa ve uygulamanız etiket için “120” değerini 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 etiket ekleme

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

Bir AdaptyUiTagResolver oluşturun ve bunu AdaptyUI.getFlowView metodunun tagResolver parametresine geçirin. SDK, her özel etiketin tam adıyla (örneğin user.streak) resolver’ı çağırır. Resolver aşağıdakilerden birini döndürür:

Bir string: Kullanıcılar etiketi bu değeri göreceği şekilde görür. “1250.0” gibi değil, “1.250” gibi insan tarafından okunabilir bir format olmalıdır. Adapty bunu biçimlendirmez veya çevirmez.
null: Kullanıcılar yedek olarak etiketin Başlangıç değerini görür.
Boş bir string: Kullanıcılar etiket yerine hiçbir şey görmez.

val customTags = mapOf(
    "username" to "DragonSlayer42",
    "coins" to "1,250",
)
val tagResolver = AdaptyUiTagResolver { tag -> customTags[tag] }

val flowView = AdaptyUI.getFlowView(
    activity,
    flowConfiguration,
    products = null,
    eventListener = eventListener,
    tagResolver = tagResolver,
)

Map<String, String> customTags = new HashMap<>();
customTags.put("username", "DragonSlayer42");
customTags.put("coins", "1,250");
AdaptyUiTagResolver tagResolver = customTags::get;

AdaptyFlowView flowView = AdaptyUI.getFlowView(
        activity,
        flowConfiguration,
        null,
        eventListener,
        AdaptyFlowInsets.Unspecified,
        AdaptyCustomAssets.Empty,
        tagResolver
);

AdaptyFlowView’ı kendiniz oluşturuyorsanız, resolver’ı onun showFlow metoduna geçirin. Jetpack Compose’da ise AdaptyFlowScreen’e geçirin. Her çağrı için örnek görmek üzere Flow’ları ve paywallları gösterme bölümünü okuyun.

Ö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 eski Paywall Builder paywallları için zaten özel etiket değerleri ayarlıyorsa, flow’lardaki özel etiketlerin nasıl farklılaştığını inceleyin.

Kullanıcılar değer olmadığında ne görür

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 VKİ gösterme

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’yi paywalle aktarma

Onboarding flow’unun flow_user_input olaylarından kullanıcının ağırlığını ve boyunu toplayın; bunun için Flow’lardan veri işleme bölümüne bakın. 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; bunun için Flow ekran görüntülemelerini takip etme bölümüne bakın. Kullanıcı o ekrandan sonra onboarding flow’unu kapattığında BMI’yi hesaplayın. Ardından paywallın flow görünümünü oluşturun ve bmi özel etiketi için BMI değerini aktarın.

Onboarding flow’unun görünümüne aşağıdaki listener’ı geçirin:

class OnboardingEventListener(
    private val onBmiCalculated: (bmi: String) -> Unit,
) : AdaptyFlowDefaultEventListener() {

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

    override fun onAnalyticEvent(
        name: String,
        params: Map<String, Any?>,
        context: Context,
    ) {
        if (name == "flow_screen_showed" && params["is_last_screen"] == true) {
            reachedLastScreen = true
            return
        }
        if (name != "flow_user_input") return

        val elementId = params["element_id"] as? String ?: return
        val value = params["value"] as? String ?: return

        bodyAnswers[elementId] = value
    }

    override fun onFlowClosed() {
        // Reset `bodyAnswers` and `reachedLastScreen` on every close,
        // so that the next run starts without old answers.
        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)

        onBmiCalculated(String.format(Locale.getDefault(), "%.1f", bmi))
    }
}

When the user closes the onboarding flow after its last screen, the listener calls onBmiCalculated with the BMI. Pass a lambda for onBmiCalculated that calls the following function. The function fetches the paywall flow, creates its view, and passes the BMI for the bmi custom tag:

fun showBmiPaywall(activity: Activity, bmi: String) {
    Adapty.getFlow("bmi_paywall") { flowResult ->
        when (flowResult) {
            is AdaptyResult.Success -> {
                AdaptyUI.getFlowConfiguration(flowResult.value) { configResult ->
                    when (configResult) {
                        is AdaptyResult.Success -> {
                            val flowView = AdaptyUI.getFlowView(
                                activity,
                                configResult.value,
                                products = null,
                                eventListener = AdaptyFlowDefaultEventListener(),
                                tagResolver = AdaptyUiTagResolver { tag ->
                                    if (tag == "bmi") bmi else null
                                },
                            )
                            // add flowView to your view hierarchy
                        }
                        is AdaptyResult.Error -> {
                            // handle the error
                        }
                    }
                }
            }
            is AdaptyResult.Error -> {
                // handle the error
            }
        }
    }
}

String.format ile Locale.getDefault() kullanmak, kullanıcının yerel ayarına göre ondalık ayracı uygular: İngilizce’de “22.7”, Almanca’da “22,7”.

BMI’yi kullanıcının profiline kaydet

Kullanıcılara BMI’lerine göre farklı flow’lar göstermek için bunu profillerinin bir custom attribute’ı olarak kaydedin. Adapty Kontrol Paneli’nde bmi anahtarıyla Number türünde bir custom attribute oluşturun. Ardından her flow’u bu attribute’tan oluşturulan bir kitle ile gösterin.

updateProfile metodunu onFlowClosed içinde, bmi’yi hesaplayan satırın hemen ardından çağırın. Bir segment’in BMI’yi 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()

Adapty.updateProfile(params) { error ->
    if (error != null) {
        // handle the error
    }
}