Kotlin Multiplatform SDK'da flow'lardan gelen verileri işleme

Bir kullanıcı flow’daki bir giriş alanına yazı yazdığında, bir ankete yanıt verdiğinde veya bir geçiş düğmesini çevirdiğinde, SDK bu değeri analytics callback’i aracılığıyla uygulamanıza iletir.

Uygulamalar bu verileri en sık şu amaçlarla kullanır:

• Kullanıcıları kendi backend’lerinde kaydedin: Kullanıcının onboarding flow’unda girdiği e-posta adresini ve adı alıp, flow kapandığında hesaplarını oluşturun.
• Cevapları ve tercihleri kaydedin: Kullanıcının neyi seçtiğini takip edin; böylece uygulamanız bunu daha sonra kullanabilir — örneğin, özel nitelikler olarak Adapty profiline yazın.
• Gelecekteki flow’ları özelleştirin: Quiz cevaplarını özel nitelik olarak kaydedin, ardından sonraki bir placement’ı hedefleyin; böylece her segment farklı bir flow ya da içinde farklı bir paywall görsün.
• Üçüncü taraf analitik platformlarına veri gönderin: Cevapları Amplitude, Mixpanel veya kullandığınız ürün analitik platformuna iletin.

Girdi alanları ve seçilebilir gruplar, değerlerini otomatik olarak bildirir. Kodunuzda girdileri birbirinden ayırt edebilmek için builder’da her girdiye anlamlı bir Element ID, her seçilebilir gruba ise Group ID verin.

Başlamadan önce

Şunlara ihtiyacınız var:

• Adapty SDK v4 veya üzeri: Flow callback’leri önceki sürümlerde mevcut değildir.
• Flow & Paywall Builder’da oluşturulmuş bir flow: Yalnızca flow’lar bu callback aracılığıyla giriş değerlerini raporlar.
• Yakın zamanda yayımlanmış bir flow sürümü: Bir flow, yalnızca bu özellik kullanıma sunulduktan sonra yayımlandıysa giriş değerlerini raporlar. Uygulamanıza hiçbir şey ulaşmıyorsa flow’un yeni bir sürümünü yayımlayıp tekrar deneyin.

Giriş değerlerini alma

Giriş değerleri, bir flow’daki diğer tüm analitik olaylarla aynı callback’e ulaşır; olay adı flow_user_input olarak gelir. AdaptyUI.setFlowsEventsObserver ile kaydettiğiniz observer üzerinde flowViewDidReceiveAnalyticEvent metodunu override edin:

AdaptyUI.setFlowsEventsObserver(object : AdaptyUIFlowsEventsObserver {

    override fun flowViewDidReceiveAnalyticEvent(
        view: AdaptyUIFlowView,
        name: String,
        paramsJsonString: String,
    ) {
        handleFlowInput(name, paramsJsonString)
    }
})

flowViewDidReceiveAnalyticEvent callback’i, ekran görüntülemeleri dahil bir flow’dan gelen tüm analitik olayları iletir. Olay parametreleri paramsJsonString içinde tek bir JSON dizesi olarak gelir; bir kez çözümleyin ve alanları okuyun.

• name parametresi olay adını içerir. Kullanıcı girişi olaylarını filtrelemek için name değerini flow_user_input ile karşılaştırın.
• element_type parametresi element kategorisini belirtir.
• Girişin değeri, element türüne göre farklı parametrelerde saklanır:
  • Metin alanları, seçiciler ve geçiş düğmeleri kullanıcının girişini value içinde saklar
  • Seçilebilir gruplar, aktif seçenekleri item_ids ve item_titles olarak raporlar

private fun handleFlowInput(name: String, paramsJsonString: String) {
    if (name != "flow_user_input") return

    val params = Json.parseToJsonElement(paramsJsonString).jsonObject
    val elementId = params["element_id"]?.jsonPrimitive?.content ?: return

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

    when (params["element_type"]?.jsonPrimitive?.content) {
        "text_input", "email_input", "number_input", "phone_input" -> {
            val text = params["value"]?.jsonPrimitive?.content
        }
        "date_picker", "time_picker", "date_time_picker" -> {
            // Unix time in milliseconds. Read it as a double — Android serializes numbers that way.
            val millis = params["value"]?.jsonPrimitive?.double?.toLong()
        }
        "single_choice" -> {
            val optionId = params["item_ids"]?.jsonArray?.firstOrNull()?.jsonPrimitive?.content
        }
        "multi_choice" -> {
            val optionIds = params["item_ids"]?.jsonArray?.map { it.jsonPrimitive.content }
        }
        "toggle" -> {
            val isOn = params["value"]?.jsonPrimitive?.boolean
        }
    }
}

Callback’in tetiklendiğini doğrulamak için kendi uygulamanızın test derlemesindeki input ile etkileşime girin. Callback handler’ınız bir event almıyorsa ön koşulları kontrol edin. Flow’un bu özellik kullanıma sunulduktan sonra yayımlandığından emin olun.

Uygulamanız girdiyi aldığında

Aşağıdaki öğeler bu olayı tetikler:

• Metin, e-posta, sayı ve telefon alanları
• Tarih, saat ve tarih-saat seçicileri
• Tekli seçim ve çoklu seçim grupları ile geçiş düğmeleri (toggle)

Aşağıdakiler tetiklemez:

• Parola alanları, ürün seçimleri ve sekme geçişleri
• Ekranlar arasında paylaşılan bir Header öğesinin içindeki giriş alanları
• Yinelenen veya eksik seçenek Element ID’lerine sahip ya da başka bir ekranda Group ID’si tekrarlanan seçilebilir gruplar. Bu tür bir grup, yanıtın bir kısmını göndermek yerine hiçbir şey göndermez.

Olay şu durumlarda tetiklenir:

• Bir alan odağı kaybettiğinde. Temizlenmiş bir alan boş dize bildirir; kullanıcının hiç düzenlemediği bir alan hiçbir şey bildirmez. Yer tutucu (placeholder) bir değer değildir. Kullanıcı alana geri dönür, düzenler ve tekrar ayrılırsa ikinci bir olay oluşur.
• Kullanıcı yeni bir değer seçtikten sonra seçiciyi kapattığında. Değiştirilmeden kapatılması hiçbir şey bildirmez.
• Kullanıcı bir seçenek veya geçiş düğmesine (toggle) dokunduğunda. Çoklu seçim olayı, seçili olan tüm seçenekleri listeler; bu nedenle son seçeneğin seçimini kaldırmak iki boş dizi gönderir.

Olay şu durumlarda tetiklenmez:

• Kullanıcı yazarken. Tuş vuruşu akışı yoktur; yalnızca odak ayrıldığında alanın tuttuğu değer bildirilir.
• Kullanıcı flow’u gönderdiğinde veya kapattığında. O anda hâlâ düzenlenmekte olan bir değer kaybolabilir; teslimat sınırlamaları bölümü, son ekranın bu duruma göre nasıl tasarlanacağını ele alır.
• Kullanıcı etkileşimi olmadan bir değer ayarlandığında. Set as default olarak işaretlenen bir seçenek, ekran açıldığında önceden seçili gelir; Set Variable eylemi ise başka bir etkileşimden bir seçenek belirleyebilir veya bir girişi doldurabilir. Bu durumların hiçbiri olay göndermez; önceden doldurulmuş bir giriş yalnızca kullanıcı onu düzenlediğinde bildirilir.

Ne alırsınız

Callback iki olay iletir. Yalnızca flow_user_input olaylarını görüntülemek için name alanına göre filtreleyin. Yanıt JSON yükü şu şekilde görünür:

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

Her elementin bildirdikleri:

Bir cevaba göre dallanmak için item_titles değil item_ids ile karşılaştırın. Başlık türetilmiş bir değerdir: ayarladıysanız seçeneğin Element Title’ı, yoksa varsayılan dilinizdeki metni, o da yoksa Element ID’si kullanılır. Flow’u başka bir dilde okuyan kullanıcı farklı bir metin görmüştür.

Etkinlik örnekleri

Bu örnekler, her etkinlikte mevcut olan özellikleri ve açıklayıcı yorum değerlerini göstermektedir.

override fun flowViewDidReceiveAnalyticEvent(
    view: AdaptyUIFlowView,
    name: String,
    paramsJsonString: String,
) {
    name                       // "flow_user_input"
    paramsJsonString           // "{\"name\":\"flow_user_input\",\"instanceId\":\"scr_J260KU5q\",\"isBackendEvent\":false,\"isCustomerEvent\":true,\"element_id\":\"email\",\"element_type\":\"email_input\",\"value\":\"jane@example.com\"}"

    // paramsJsonString, çözümlendiğinde:
    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"
}

override fun flowViewDidReceiveAnalyticEvent(
    view: AdaptyUIFlowView,
    name: String,
    paramsJsonString: String,
) {
    // paramsJsonString, once decoded:
    params["element_id"]       // "birthday"
    params["element_type"]     // "date_picker"
    params["value"]            // 645408000000   (Unix milliseconds — 1990-06-15, local midnight)
}

override fun flowViewDidReceiveAnalyticEvent(
    view: AdaptyUIFlowView,
    name: String,
    paramsJsonString: String,
) {
    // paramsJsonString, once decoded:
    params["element_id"]       // "experience"
    params["element_type"]     // "single_choice"
    params["item_ids"]         // ["pro"]
    params["item_titles"]      // ["I train professionally"]
}

override fun flowViewDidReceiveAnalyticEvent(
    view: AdaptyUIFlowView,
    name: String,
    paramsJsonString: String,
) {
    // paramsJsonString, once decoded:
    params["element_id"]       // "interests"
    params["element_type"]     // "multi_choice"
    params["item_ids"]         // ["sports", "music"]
    params["item_titles"]      // ["Sports", "Music"]
}

override fun flowViewDidReceiveAnalyticEvent(
    view: AdaptyUIFlowView,
    name: String,
    paramsJsonString: String,
) {
    // paramsJsonString, bir kez çözüldüğünde:
    params["element_id"]       // "reminders"
    params["element_type"]     // "toggle"
    params["value"]            // true
}

Teslimat ve sınırlamalar

• Son değer geçerlidir: Alan başına bir olay alırsınız; bu olay, kullanıcının tuş tuş değil, en sonunda girdiği değeri taşır. Kullanıcı bir alanı düzenlerse yalnızca son sürüm size ulaşır.
• Gönderim garantisi yoktur: Kullanıcılar flow boyunca ilerledikçe değerler size ulaşır ve kullanıcı her an çıkabilir. Bir yanıt kümesini tamamlanmış saymadan önce flow’un kapanmasını bekleyin.
• En iyi çaba teslimatı: Bir alan odaklanmışken veya bir seçici açıkken kullanıcı flow’u kapatır ya da uygulamayı arka plana alırsa o değer kaybolabilir.

Son alanın değerinin güvenilir olmasını sağlamak için flow’u; giriş veya seçici içermeyen bir ekranla bitirin ve bu ekran açıldığında otomatik olarak değil, açık bir kullanıcı eylemiyle flow’u kapatın. Son ekrana geçmek, önceki alandaki odağı kaldırır ve bu sayede değer gönderilir.

Her girdi değerini observer’ınız aldığında saklayın ve flow kapandığında tam seti gönderin. Bu anı yakalamak için aynı observer üzerinde flowViewDidDisappear metodunu override edin. Bu metod, kullanıcı flow’u tamamlasa da yarıda bıraksa da, flow görünümü kapatıldığında çalışır.

Kullanım senaryoları

Kullanıcıları backend’inize kaydedin

Değerler geldikçe toplayın ve flow kapandığında tek bir istekle gönderin; böylece bir istek eksiksiz bir yanıt seti taşımış olur.

Kullanıcı flow’u tamamlasa da yarıda bıraksa da görünüm kaybolur. Backend’inizi çağırmadan önce ihtiyaç duyduğunuz alanları kontrol edin.

Flow, backend’inizden gelen hataları gösteremez. Callback’in dönüş değeri yoktur ve SDK’nın çalışan bir flow’a veri gönderen bir yöntemi de bulunmaz. Kayıt başarısız olursa, örneğin e-posta adresi zaten kullanımdaysa, flow kapandıktan sonra hatayı kendi arayüzünüzde gösterin.

class MyFlowsEventsObserver : AdaptyUIFlowsEventsObserver {

    private val flowAnswers = mutableMapOf<String, String>()

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

        val params = Json.parseToJsonElement(paramsJsonString).jsonObject
        val elementId = params["element_id"]?.jsonPrimitive?.content ?: return
        val value = params["value"]?.jsonPrimitive?.contentOrNull ?: return

        flowAnswers[elementId] = value
    }

    override fun flowViewDidDisappear(view: AdaptyUIFlowView) {
        if (!flowAnswers.containsKey("email")) return

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

        flowAnswers.clear()
    }
}

Kullanıcı profillerini veriyle zenginleştirme

Kullanıcının girdiği bilgileri profiline bağlamak ve aynı bilgileri iki kez sormamak için değerler geldikçe kullanıcı profilini güncelleyin.

Örneğin, flow’unuzda name Element ID’sine sahip bir metin girişi ve email Element ID’sine sahip bir e-posta girişi varsa:

private fun handleFlowInput(name: String, paramsJsonString: String) {
    if (name != "flow_user_input") return

    val params = Json.parseToJsonElement(paramsJsonString).jsonObject
    val value = params["value"]?.jsonPrimitive?.contentOrNull ?: return

    val builder = AdaptyProfileParameters.Builder()

    when (params["element_id"]?.jsonPrimitive?.content) {
        "name" -> builder.withFirstName(value)
        "email" -> builder.withEmail(value)
        else -> return
    }

    mainUiScope.launch {
        Adapty.updateProfile(builder.build())
            .onError { error ->
                // handle the error
            }
    }
}

Sonraki flow’larda gösterilecek içeriği özelleştirin

Quiz yanıtları, kullanıcının ilerleyen bir placement’ta göreceği içeriği de belirleyebilir — farklı bir flow veya içindeki farklı bir paywall.

Örneğin, onboarding flow’unuzda kullanıcılara sporla ilgili deneyimlerini sorun, ardından her gruba farklı ürünler ve metinler içeren kendi flow’unu gösterin.

1. Flow’unuza bir quiz ekleyin. Seçilebilir gruba experience Group ID’sini ve her seçeneğe anlamlı bir Element ID verin.
2. Yanıtları işleyin ve kullanıcı için özel attribute’lar ayarlayın.

private fun handleFlowInput(name: String, paramsJsonString: String) {
    if (name != "flow_user_input") return

    val params = Json.parseToJsonElement(paramsJsonString).jsonObject
    if (params["element_id"]?.jsonPrimitive?.content != "experience") return

    val optionId = params["item_ids"]?.jsonArray?.firstOrNull()
        ?.jsonPrimitive?.contentOrNull ?: return

    val builder = AdaptyProfileParameters.Builder()
    // Set the custom attribute 'experience' to the option the user selected
    // (beginner, amateur, or pro).
    builder.withCustomAttribute("experience", optionId)

    mainUiScope.launch {
        Adapty.updateProfile(builder.build())
            .onError { error ->
                // handle the error
            }
    }
}

3. Her özel özellik değeri için bir segment oluşturun.
4. Bir placement oluşturun ve her segment için bir kitle ekleyin.
5. Uygulamanızda o placement için flow’u görüntüleyin.