Android SDK ile özel öğeleri görüntüleme

Özel bir element içeren bir ekran açıldığında, Adapty SDK; elementin Type ve ID bilgilerini uygulama kodunuzdaki bir resolver’a iletir. Resolver aşağıdakilerden birini döndürür:

  • Type ve ID ile eşleşen view: Kullanıcılar, Lottie animasyonu, interaktif grafik veya kamera önizlemesi gibi native view’ı görür.
  • View döndürülmez: Kullanıcılar yedek içeriği görür; bu, Flow & Paywall Builder’daki özel elementin içindeki içeriktir.

Resolver’ı olmayan uygulama sürümlerinin kullanıcıları da yedek içeriği görür. Bu nedenle, uygulamayı yayınlamadan önce flow’u yayımlayabilirsiniz.

Başlamadan önce

Şunlara ihtiyacınız var:

  • Adapty Android SDK 4.4 veya üzeri: Daha eski sürümler, her özel öğe için yedek gösterir.
  • Yerel bir Android uygulaması: Flutter gibi çapraz platform framework’leri için Adapty SDK’ları, her özel öğe için yedek gösterir.
  • Özel öğeler için bir adlandırma şeması: Her yerel görünüme lottie_animation gibi bir Tür verin. Türlerde yalnızca küçük harf, rakam ve alt çizgi kullanın. Aynı Türden özel öğeleri birbirinden ayırt etmek için her birine welcome_wave gibi bir ID verin. Kodunuzdaki Türler ve ID’ler, Flow & Paywall Builder içindekilerle eşleşmelidir.

iOS uygulamanız zaten özel öğeler görüntülüyorsa, mevcut Types ve ID’leri yeniden kullanın. Her platform için ayrı bir kitle oluşturmadığınız sürece, iOS ve Android kullanıcıları aynı flow’ları görür.

Özel öğeler için view oluşturma

Her Type için bir composable/Android View oluşturun veya mevcut olanı yeniden kullanın. Aşağıdaki lottie_animation Type’ına ait view’lar, uygulamanızın assets klasöründen bir Lottie animasyonu oynatır. Kotlin örneği, com.airbnb.android:lottie-compose kütüphanesini kullanan bir composable’dır. Java örneği ise com.airbnb.android:lottie kütüphanesinden bir Android View oluşturur:

Gereksinimler ve en iyi uygulamalar

  • Boyutlandırma:

    • Padding ve hizalama: Native view’ın, Flow & Paywall Builder’da ayırdığınız kapsayıcıya (padding hariç) tam olarak sığdığından emin olun. View tüm alanı kaplamıyorsa varsayılan olarak alanın sol üst köşesinde görünür. Konumunu değiştirmek için özel öğenin Layout bölümündeki hizalama ayarını kullanın.
    • Hug yüksekliği: Özel öğenin yüksekliği Hug olarak ayarlandığında, mevcut alanı dolduracak şekilde uzayan bir view (lazy list gibi) ya çöker ya da ekran yüksekliğine uzar. Bunun yerine özel öğeye Fixed yüksekliği verin.
  • Tema: Views ile oluşturulmuş bir ekranda composable’ı uygulamanızın renkleri ve yazı tipleriyle görüntülemek için onu Compose temanıza sarın.

  • Flow aksiyonları: Native view, bir sonraki ekrana geçiş gibi flow aksiyonlarını tetikleyemez. Navigasyon düğmelerini, satın alma düğmelerini ve flow aksiyonlu diğer düğmeleri özel öğenin dışında tutun.

  • Seçilebilir öğeler: Özel öğeyi ürün kartlarının ve diğer seçilebilir öğelerin dışında tutun. Seçim değiştiğinde native view durumunu kaybedebilir.

  • Navigasyon yönetimi: Kullanıcı bir sonraki ekrana geçtiğinde SDK, native view’ı ekrandan kaldırır. View’ın başlattığı kamera oturumları, oynatıcılar ve konum güncellemeleri gibi işlemleri durdurun:

    • Composable: DisposableEffect’in onDispose bloğunu kullanın. Asenkron işler için LaunchedEffect kullanın: composable kompozisyondan çıktığında Compose onu iptal eder.
    • Android View: View alt sınıfınızda onDetachedFromWindow’u override edin ya da View’a bir View.OnAttachStateChangeListener ekleyin.

    Kullanıcı geri döndüğünde veya ekran döndürme gibi bir yapılandırma değişikliği sonrasında SDK, resolver’ı yeniden çağırır ve önceki görünümün durumunu taşımayan yeni bir native view oluşturur.

  • Carousel’lar: Bir carousel’da, tüm slaytlardaki native view’lar ekran açık olduğu sürece aktif kalır; yalnızca görünür slayttaki görünüm değil. Kamera önizlemelerini ve sesli oynatıcıları carousel’ların içinde kullanmayın.

Özel öğeler ve görünümler için resolver yazın

Bir resolver yazmak için AdaptyCustomElementsResolver arayüzünü uygulayın. Bu arayüzün resolve metodu, özel bir öğenin Type ve ID bilgilerini alır ve eşleşen görünümü aşağıdaki biçimlerden biriyle döndürür:

  • Composable: AdaptyCustomElementContent.compose döndürün; lambda içine composable’ı yerleştirin.
  • Android View: AdaptyCustomElementContent.view döndürün; View’ı oluşturan bir fonksiyon geçirin. Kotlin’de factory parametresini isimlendirin: AdaptyCustomElementContent.view(factory = { context, _ -> ChartView(context) }). İsimlendirmezseniz Kotlin, trailing lambda’yı isteğe bağlı update parametresine geçirir ve kod derlenmez.

lottie_animation Türü için aşağıdaki resolver, Lottie görünümünü döndürür. ID, assets klasöründeki animasyon dosyasını adlandırır; örneğin welcome_wave.json için welcome_wave:

Diğer herhangi bir Type için null döndürün. Uygulamayı yayımladıktan sonra yeni bir Type ile özel bir eleman eklerseniz, yayımlanan sürümün kullanıcıları onun yedeğini görür.

Resolver şu gereksinimlere sahiptir:

  • Ağ verileri ve oynatıcılar: Ağ verilerini ve oynatıcıları resolver’da değil, native view state’inde tutun. SDK, ekran açıkken resolver’ı defalarca çağırır. Resolver içindeki kod her çağrıda yeniden çalışır; bu nedenle ağ istekleri tekrarlanır ve oynatıcılar başa döner. SDK bu çağrılar arasında native view’ı yeniden oluşturmaz; dolayısıyla veriler bir kez yüklenir ve oynatıcılar çalmaya devam eder. Oynatıcıları, oturumları ve ağ isteklerini native view içinde oluşturun:

    • Composable: Oynatıcıları ve oturumları remember içinde, ağ isteklerini ise LaunchedEffect içinde oluşturun.
    • Android View: Oynatıcıları, oturumları ve ağ isteklerini onAttachedToWindow içinde oluşturun.
  • Her özel öğe için tek bir native view: Bazı native view’lar ekran açıkken değişir; örneğin verileri yüklendiğinde veya kullanıcı bunlara dokunduğunda. Bu mantığı resolver’da değil, native view’ın kendisinde uygulayın. Resolver, aynı özel öğe için farklı bir composable döndürürse Compose, view’ın state’ini sıfırlar.

  • Her görünüm için yeni bir View: factory’nin her çağrısında yeni bir View oluşturun. SDK, ekran açıldığında, kullanıcı ekrana geri döndüğünde veya döndürme işleminin ardından gibi özel öğe her göründüğünde factory’yi çağırır.

  • Uygulama verileri: Günlük seri gibi verileri tutan nesneyi (örneğin StateFlow veya LiveData) resolver’ın bir özelliğinde saklayın. Nesneyi native view’a aktarın ve orada gözlemleyin:

    • Composable: StateFlow’u collectAsState ile, LiveData’yı ise observeAsState ile toplayın/gözlemleyin.
    • Android View: Nesneyi onAttachedToWindow içinde gözlemlemeye başlayın, onDetachedFromWindow içinde durdurun.

    Çözümleyiciye kopyaladığınız bir değer (örneğin seri numarası), çözümleyiciyi oluşturduğunuzda ne idiyse öyle kalır.

Yedek içerik için koşulları ayarlayın

Kullanıcılara boş bir özel element yerine yedek içeriği göstermek için, aşağıdaki durumlarda görünüm döndürmeyin:

  • Görselleştirilecek bir şey yok — gerekli animasyon dosyası veya veri dosyası eksik.
  • İşlenecek bir şey yok — kullanıcı bir quiz sorusunu atladı ve veri eksik.
  • Erişim engellendi — reddedilen bir izin, görünümün bir kaynağa erişmesini engelliyor.

Örneğin, resolver animasyon dosyası eksik olduğunda görünüm döndürmez.

Bir izin için, yalnızca kullanıcı ekran açılmadan önce reddetmişse null döndürün. ContextCompat.checkSelfPermission, iki durumda aynı değeri (PERMISSION_DENIED) döndürür: uygulamanız kullanıcıdan ilk kez izin istemeden önce ve kullanıcı isteği reddettikten sonra. Bu iki durumu birbirinden ayırt etmek için izin isteğinin sonucunu kaydedin ve kaydedilen sonucu resolver içinde okuyun. Uygulamanız henüz izin istemediyse null yerine native view’ı döndürün ve izni view içinde isteyin. Örneğin, bir harita view’ı göründüğünde konum erişimi isteyin ve kullanıcı erişim izni verir vermez haritayı gösterin. null döndürürseniz ve kullanıcı daha sonra izin verirse, kullanıcı yine de yedek içeriği görür. Bir izin değişikliği, SDK’nın resolver’ı yeniden çağırmasını sağlamaz. Native view, yalnızca SDK resolver’ı tekrar çağırdığında görünür; örneğin kullanıcı ekrana geri döndüğünde.

Resolver’ı SDK’ya Aktarın

Uygulama genelinde geçerli bir resolver ile başlayın. SDK, kendi resolver’ı olmayan her flow’da bunu çağırır. Kullanıcılar, uygulama yayınlamadan yeni flow’larda ve A/B testlerinde yerel görünümlerinizi görür. Bu görünümler, verilerinizi uygulamanızdan okuduğu için her kullanıcıya günlük seri gibi kendi verilerini göstermeye devam eder.

Bir flow yalnızca o flow açıldığında sahip olduğunuz verilere ihtiyaç duyduğunda, o flow’a bir resolver ekleyin. Örneğin, bir paywall kullanıcının önceki bir flow’da girdiği ağırlığı gösteriyor ya da kullanıcının dışa aktarmak istediği belgeyi önizliyor olabilir. Ayrıca bir flow’daki belirli bir Type için farklı bir görünüm göstermek amacıyla da o flow’a resolver ekleyebilirsiniz.

Her flow’da görünümleri görüntüleme

Her flow’da resolver’ı kullanmak için AdaptyUI.setCustomElementsResolver metodunu bir kez çağırın; örneğin Application sınıfınızın onCreate metodunda:

Tip

Bir Type’ın her özel öğesinde aynı görünümü göstermek için AdaptyCustomElementsResolver.of’a Type’lar ve görünümlerin bir map’ini geçin. Map, bir resolver sınıfına kıyasla daha az kod gerektirir; ancak yedek içerik için koşul belirleyemezsiniz.

val appWideViews = mapOf(
    "confetti" to AdaptyCustomElementContent.compose { LottieElement("confetti.json") },
)
AdaptyUI.setCustomElementsResolver(AdaptyCustomElementsResolver.of(appWideViews))

Tek bir flow için veri gösterme, örneğin dışa aktarılacak bir belge

Bir flow view’una ilettiğiniz resolver, o flow view’undaki uygulama genelindeki resolver’ın yerini alır.

Bu flow’da uygulama genelindeki view’ları korumak için, uygulama genelindeki resolver’ı bu resolver’a iletin ve diğer Type’lar ile ID’ler için uygulama genelindeki resolver’ı çağırın. Aşağıdaki resolver, kullanıcının dışa aktarmak istediği belgeyi önizler ve diğer tüm özel öğeler için uygulama genelindeki resolver’ı çağırır:

Resolver’ı AdaptyUI.getFlowView fonksiyonunun customElementsResolver parametresine iletin:

AdaptyFlowView’yi kendiniz oluşturuyorsanız, resolver’ı showFlow metoduna geçirin. Java’da showFlow, getFlowView ile aynı argümanları alır; activity hariç. Jetpack Compose’da resolver’ı AdaptyFlowScreen’e geçirin. Her çağrıya ilişkin örnek için Flow ve paywall’ları gösterme sayfasını okuyun.

AdaptyCustomElementsResolver.of yerine resolver sınıfları kullanıyorsanız, uygulama genelindeki view’ların haritasını bu flow için oluşturulan haritayla birleştirin: AdaptyCustomElementsResolver.of(appWideViews + flowViews). Sonucu flow view’ına geçirin. Her iki haritada da aynı Type varsa, bu kod o flow’a ait view’ı korur.

Cihazda test etme

Flow & Paywall Builder, uygulama kodunuzu çalıştıramaz; bu nedenle tuval yalnızca yedek içeriği gösterir. Native görünümdeki bir hata uygulamayı çökertebilir. Uygulamayı yayınlamadan önce, özel element içeren her ekranı bir cihazda test edin:

  1. Her flow’un önbelleğe alınmış sürümü yerine en son yayınlanan sürümünü görmek için cihazı test cihazı olarak kaydedin.

  2. Adapty SDK uyarılarını Logcat’te görmek için log seviyesini AdaptyLogLevel.WARN veya daha ayrıntılı bir seviyeye ayarlayın. Varsayılan seviye olan AdaptyLogLevel.NONE ile SDK hiçbir şey kaydetmez.

  3. Cihazda, resolver’ı içeren bir build çalıştırın. Özel eleman içeren her ekranı açın ve yerel görünümün göründüğünü ve özel elemana uyduğunu doğrulayın. Görünüm kaydırılıyorsa veya sürükleme hareketlerine yanıt veriyorsa bu hareketleri de test edin.

  4. Yerel görünüm yerine yedek görünüyorsa Logcat’te şu uyarıyı bulun: custom element <type>:<id> is not served by a resolver. Ardından şunları doğrulayın:

    • Uyarıdaki Type ve ID, kodunuzdakilerle harfi harfine eşleşiyor.
    • Uygulamanızın, görünümün ihtiyaç duyduğu dosya, veri veya izne sahip olduğu.
    • Uygulamanızın uygulama genelindeki resolver’ı ayarladığı.
    • Bu flow için bir resolver geçiriyorsanız, söz konusu resolver’ın Type ve ID için bir görünüm döndürdüğü.

    Uyarı görünmüyorsa, uygulamanın Adapty Android SDK 4.4 veya sonraki bir sürümü kullandığını doğrulayın.

  5. Özel element boş kalıyorsa, Logcat’te şu uyarılardan birini arayın:

    • custom element <type>:<id> is not served by a resolver: Özel elementin yedek içeriği yok ve hiçbir resolver bunun için bir görünüm döndürmüyor. 4. adımdaki her öğeyi doğrulayın.
    • content does not report its size: Composable’ın kendi yüksekliği yok. Özel elemente Fixed yükseklik verin.

    SDK yalnızca composable’lar için boyut uyarısını kaydeder. Bir Android View uyarı olmadan boş kalıyorsa, özel öğeye de Fixed yüksekliği verin.

  6. Yedek paywall’ı önizlemek için Type değeri olarak null döndürün ve ekranı yeniden açın.

Örnekler

Her tarif, builder’daki kurulumu ve uygulamanız için gereken kodu gösterir: