Adapty Kotlin Multiplatform SDK'yı v4.0'a Geçirin

Adapty Kotlin Multiplatform SDK 4.0 (beta), flow’ları tanıtır ve paywall API’lerini buna göre yeniden adlandırır. Yeni API’ler hem yeni Flow Builder hem de mevcut Paywall Builder ile çalışır — Adapty Kontrol Paneli tarafında herhangi bir kurulum değişikliği gerekmez.

Hızlı referans

v3	v4
`Adapty.getPaywall(placementId, locale)`	`Adapty.getFlow(placementId)`
`Adapty.getPaywallForDefaultAudience(placementId, locale)`	`Adapty.getFlowForDefaultAudience(placementId)`
`Adapty.getPaywallProducts(paywall)`	`Adapty.getPaywallProducts(flow)`
`Adapty.logShowPaywall(paywall)`	`Adapty.logShowFlow(flow)`
`AdaptyPaywall`	`AdaptyFlow`
`AdaptyUI.createPaywallView(paywall, ...)`	`AdaptyUI.createFlowView(flow, ...)`
`AdaptyUI.createNativePaywallView(...)` → `AdaptyNativePaywallView`	`AdaptyUI.createNativeFlowView(...)` → `AdaptyNativeFlowView`
`AdaptyUIPaywallView`	`AdaptyUIFlowView`
`AdaptyUI.presentPaywallView(view)` / `dismissPaywallView(view)`	`AdaptyUI.presentFlowView(view)` / `dismissFlowView(view)`
`AdaptyUI.setPaywallsEventsObserver(observer)`	`AdaptyUI.setFlowsEventsObserver(observer)`
`AdaptyUI.registerPaywallEventsListener` / `unregisterPaywallEventsListener`	`AdaptyUI.registerFlowEventsListener` / `unregisterFlowEventsListener`
`AdaptyUIPaywallsEventsObserver`	`AdaptyUIFlowsEventsObserver`
`AdaptyUIPaywallPlatformView(paywall, ...)`	`AdaptyUIFlowPlatformView(flow, ...)`
`paywallViewDidPerformAction`, `paywallViewDidAppear` ve diğer `paywallView...` callback’leri	`flowViewDidPerformAction`, `flowViewDidAppear` ve diğer `flowView...` callback’leri
`paywallViewDidFailRendering`	`flowViewDidReceiveError`

AdaptyPaywallProduct adını korur — ürünler hâlâ bir flow’a aittir ve getPaywallProducts da adını korur, artık bir AdaptyFlow alır. getFlow ve getFlowForDefaultAudience metotları artık locale parametresi almaz — bunun yerine createFlowView metoduna iletin. Satın alma ve profil API’leri (makePurchase, restorePurchases, getProfile, identify, updateProfile) ile setFallback aynı imzaları korur; ancak yedek dosyanın kendisini yeniden indirmeniz gerekir — bkz. Yedek dosyalar. Onboarding metotları hâlâ çalışır ancak kullanımdan kaldırılmıştır — bkz. Onboarding API kullanım dışı bırakma. Bazı varsayılan davranışlar değişti — bkz. Varsayılan davranış değişiklikleri.

Kurulum

v4.0 bir ön sürüm olduğundan, tam sürümü sabitleyin — Gradle dinamik aralıklarla ön sürümleri seçmez:

[versions]
adapty-kmp = "4.0.1-beta.1"

[libraries]
adapty-kmp = { module = "io.adapty:adapty-kmp", version.ref = "adapty-kmp" }
adapty-kmp-ui = { module = "io.adapty:adapty-kmp-ui", version.ref = "adapty-kmp" }

adapty-kmp-ui modülü yalnızca flow’ları ve paywallları Compose Multiplatform katmanıyla (view.present()) render ediyorsanız gereklidir. Tam kurulum için Adapty SDK’yı Yükle sayfasına bakın.

Altta yatan yerel Adapty SDK’ları her iki platformda da 4.x sürümlerine güncellendi ve otomatik olarak çözümleniyor — herhangi bir derleme değişikliğine gerek yok. iOS deployment target bu sürümle değişmeden 15.0 olarak kalmaktadır.

Flow’ları Getirme

getPaywall → getFlow

Döndürülen tür AdaptyPaywall yerine AdaptyFlow olarak değişir ve locale parametresi, fetch çağrısından createFlowView’a taşınır; özel paywalllar için tüm locale’ler flow.remoteConfigs içinde döndürülür:

- Adapty.getPaywall("YOUR_PLACEMENT_ID", locale = "en")
-     .onSuccess { paywall ->
-         // use the paywall
+ Adapty.getFlow("YOUR_PLACEMENT_ID")
+     .onSuccess { flow ->
+         AdaptyUI.createFlowView(flow = flow, locale = "en")
      }
      .onError { error ->
          // handle the error
      }

locale, createFlowView üzerinde isteğe bağlı olmaya devam eder: bunu atlarsanız görünüm en dilinde ya da flow’un en yerelleştirmesi yoksa flow’un varsayılan yerelleştirmesinde gösterilir. Bkz. Yerelleştirmeler ve yerel ayar kodları.

getPaywallForDefaultAudience aynı şekilde yeniden adlandırılmıştır:

- Adapty.getPaywallForDefaultAudience("YOUR_PLACEMENT_ID", locale = "en")
+ Adapty.getFlowForDefaultAudience("YOUR_PLACEMENT_ID")

getPaywallProducts(paywall) → getPaywallProducts(flow)

getPaywallProducts adını korur ancak artık bir AdaptyFlow alır:

- Adapty.getPaywallProducts(paywall)
+ Adapty.getPaywallProducts(flow)
      .onSuccess { products ->
          // use the products
      }

Yedek dosyalar

Yedek dosya formatı SDK v4’te değişti. Yeni dosyayı Placements > Fallbacks bölümünden indirip uygulamanıza ekleyin.

Veri modeli

getFlow, AdaptyPaywall yerine AdaptyFlow döndürür ve nesne yapısı değişti:

v3 `AdaptyPaywall` özelliği	v4 `AdaptyFlow` özelliği	İşlem
`remoteConfig: AdaptyRemoteConfig?` (tek)	`remoteConfigs: List<AdaptyRemoteConfig>`	Bir flow, yapılandırılmış dil başına bir remote config taşır. Kullanıcıyla eşleşeni okuyun: `flow.remoteConfigs.firstOrNull { it.locale == "en" }`.
(yeni)	`paywalls: List<AdaptyFlowPaywall>`	Her giriş, flow içindeki bir paywall varyasyonudur; kendi `name`, `variationId` ve `productIdentifiers` değerlerine sahiptir. Web paywall yöntemleri bir `AdaptyFlowPaywall` alır — bkz. Web paywall yöntemleri.
`productIdentifiers`	taşındı	Ürün tanımlayıcıları artık her varyasyonda bulunur: `flow.paywalls[i].productIdentifiers`. Ürünleri getirmek için `getPaywallProducts(flow)` çağırmaya devam edin.
`hasViewConfiguration`	kaldırıldı	Kodunuzdan tüm `hasViewConfiguration` kontrollerini kaldırın — bunun yerine `createFlowView` bir hata döndürür (bkz. Flow’ları görüntüleme).

hasViewConfiguration özelliği AdaptyOnboarding üzerinde kalmaya devam eder — yalnızca flow modeli bunu kaldırır.

Web paywall metodları

openWebPaywall ve createWebPaywallUrl isimlerini korur, ancak paywall parametresi, flow.paywalls içindeki varyantlardan biri olan AdaptyFlowPaywall alan bir flowPaywall parametresiyle değiştirilir. Yine de AdaptyPaywallProduct geçirebilirsiniz:

- Adapty.openWebPaywall(paywall = paywall)
+ flow.paywalls.firstOrNull()?.let { flowPaywall ->
+     Adapty.openWebPaywall(flowPaywall = flowPaywall)
+ }

Flow görüntülemelerini takip etme

logShowPaywall → logShowFlow

logShowPaywall, logShowFlow olarak yeniden adlandırıldı ve artık bir AdaptyFlow alıyor. Etkinlik yine aynı varyasyon üzerinden kaydedilir; bu nedenle mevcut dönüşüm hunisi ve A/B testi metrikleri kontrol panelinde herhangi bir değişiklik yapılmadan çalışmaya devam eder.

- Adapty.logShowPaywall(paywall)
+ Adapty.logShowFlow(flow)

v3’te olduğu gibi, Flow Builder veya Paywall Builder tarafından oluşturulan flow’ları ya da paywall’ları görüntülerken bu metodu çağırmanıza gerek yoktur — Adapty bu görüntülemeleri otomatik olarak takip eder.

Flow’ları görüntüleme

createPaywallView → createFlowView

Factory metodunu yeniden adlandırın ve AdaptyFlow nesnesi geçirin. Dönen görünüm tipi AdaptyUIPaywallView’dan AdaptyUIFlowView’a yeniden adlandırıldı; ancak metodları (present, dismiss) ve isteğe bağlı parametreleri (loadTimeout, preloadProducts, customTags, customTimers, customAssets, productPurchaseParams) değişmedi. Yeni bir isteğe bağlı parametre eklendi: locale. Bu parametre, daha önce getPaywall metoduna geçirdiğiniz locale parametresinin yerini alıyor — bkz. Flow’ları getirme.

- AdaptyUI.createPaywallView(paywall)
+ AdaptyUI.createFlowView(flow)
      .onSuccess { view ->
          view.present()
      }
      .onError { error ->
          // handle the error
      }

Compose Multiplatform kullanmıyorsanız, native factory metodu da aynı şekilde yeniden adlandırıldı:

- AdaptyUI.createNativePaywallView(paywall)
+ AdaptyUI.createNativeFlowView(flow)

createFlowView, flow’da görünüm yapılandırması yoksa AdaptyResult.Error döndürür — bu, v3’teki hasViewConfiguration kontrolünün yerini alır:

- if (paywall.hasViewConfiguration) {
-     AdaptyUI.createPaywallView(paywall)
-         .onSuccess { view -> view.present() }
- }
+ AdaptyUI.createFlowView(flow)
+     .onSuccess { view -> view.present() }
+     .onError { error ->
+         // the flow has no view configured, or view creation failed
+     }

Flow view tek kullanımlıktır: dismiss() çağrısının ardından view yok edilir, bu nedenle flow’u tekrar göstermek için createFlowView fonksiyonunu yeniden çağırmanız gerekir.

Olayları işleme

Olaylar gözlemcisi AdaptyUIPaywallsEventsObserver yerine AdaptyUIFlowsEventsObserver olarak yeniden adlandırıldı; callback’lerin paywallView ön eki de flowView olarak değişti. Mevcut handler gövdelerinde kod değişikliği yapmanıza gerek yok — sadece tür adını ve override’ları yeniden adlandırın:

- AdaptyUI.setPaywallsEventsObserver(object : AdaptyUIPaywallsEventsObserver {
-     override fun paywallViewDidFinishPurchase(
-         view: AdaptyUIPaywallView,
+ AdaptyUI.setFlowsEventsObserver(object : AdaptyUIFlowsEventsObserver {
+     override fun flowViewDidFinishPurchase(
+         view: AdaptyUIFlowView,
          product: AdaptyPaywallProduct,
          purchaseResult: AdaptyPurchaseResult
      ) {
          // custom logic after purchase
      }
  })

Bir callback de yeniden adlandırıldı: paywallViewDidFailRendering, flowViewDidReceiveError oldu. Önceki rendering hatalarının yanı sıra diğer satın alma dışı çalışma zamanı hatalarında da tetiklenir:

- override fun paywallViewDidFailRendering(view: AdaptyUIPaywallView, error: AdaptyError) {}
+ override fun flowViewDidReceiveError(view: AdaptyUIFlowView, error: AdaptyError) {}

Callback’lerin tam listesi için Flow ve paywall olaylarını yönetme bölümüne bakın.

Compose platform görünümü

Compose Multiplatform composable ile görünüm gömmek istiyorsanız, AdaptyUIPaywallPlatformView(paywall, ...) bileşeni AdaptyUIFlowPlatformView(flow, ...) olarak yeniden adlandırıldı. Olay geri çağrıları onDid... adlarını korur; yalnızca onDidFailRendering, onDidReceiveError olarak değişti:

- AdaptyUIPaywallPlatformView(
-     paywall = paywall,
+ AdaptyUIFlowPlatformView(
+     flow = flow,
      onDidFinishPurchase = { view, product, result -> /* ... */ },
  )

v3’te olduğu gibi, burada ilettiğiniz callback’ler (ve registerFlowEventsListener aracılığıyla kaydedilen tüm observer’lar) global observer’ın yerine değil, ona ek olarak çalışır — callback’iniz bir olayı gözlemler; global varsayılanın yerini almaz. Değişen varsayılanları aklınızda bulundurun: örneğin, global varsayılan artık satın alma işleminin ardından görünümü kapatmaz.

Yeni API’lar

AdaptyUI.setObserverModeResolver(...) ile bir AdaptyUIObserverModeResolver — SDK Observer mode’da çalışırken flow’lardan başlatılan satın almaları ve geri yüklemeleri yönetin. Önceden bu yalnızca yerel iOS ve Android SDK’larında mevcuttu. Bkz. Flow’ları Observer mode’da sunma.
AdaptyUI.setSystemRequestsHandler(...) ile bir AdaptyUISystemRequestsHandler — bir flow’dan gelen sistem istekleri için ayrılmıştır (işletim sistemi izin istemleri ve uygulama değerlendirme istekleri). Flow’lar henüz bu istekleri tetiklemediğinden bir işleyici kaydetmenize gerek yoktur.
Yeni isteğe bağlı flowViewDidReceiveAnalyticEvent callback’i, bir flow’dan gelen özel analiz olayları için ayrılmıştır. Flow’lar henüz bu olayları kodunuza iletmediğinden bunu uygulamanıza gerek yoktur.
AdaptyUI.openWebUrl(url, openIn) ve AdaptyUI.requestAppReview() — bunlar varsayılan OpenUrlAction işlemesini ve varsayılan handleAppReviewRequest’i destekler; dolayısıyla URL’ler ve uygulama değerlendirme istemleri kutudan çıktığı gibi yerel olarak işlenir. Bunları yalnızca söz konusu varsayılanları geçersiz kılıyorsanız doğrudan çağırın.
AdaptyUIFlowView.locale — görünümün hangi yerelleştirmeyle oluşturulduğunu bildirir; böylece kullanıcının gerçekte hangisini gördüğünü anlayabilirsiniz. SDK 4.0.1-beta.1 veya sonrasını gerektirir.
AdaptyConfig.ServerCluster.CN — uygulamanızı Adapty’nin Çin sunucularına bağlamak için DEFAULT ve EU’nun yanında yeni bir sunucu kümesi seçeneği.

Varsayılan davranış değişiklikleri

Bu değişiklikler derleme hatası oluşturmaz; bu nedenle çalışma zamanında test edin:

Satın alma tamamlama: v3’te, varsayılan paywallViewDidFinishPurchase, AdaptyPurchaseResult.UserCanceled dışındaki her satın alma sonucunda görünümü kapatıyordu. v4’te, varsayılan flowViewDidFinishPurchase hiçbir şey yapmaz; yani satın alma tamamlandıktan sonra flow, siz kapatana kadar açık kalır — bu iOS davranışıyla örtüşür. Otomatik kapanmaya güveniyorsanız, satın alma tamamlandığında view.dismiss() çağrısını kendiniz yapın.
Android sistem geri tuşu: v3’te, varsayılan paywallViewDidPerformAction hem CloseAction hem de AndroidSystemBackAction üzerinde görünümü kapatıyordu. v4’te, varsayılan yalnızca CloseAction ile ilgilenir — sistem geri tuşu artık flow’u tek başına kapatmaz; bu, bir flow’un sistem hareketiyle kapatılamadığı iOS davranışıyla örtüşür. Kullanıcılara açık bir çıkış yolu sunun (bir Kapat düğmesi veya on_device_back eylemi) ya da flowViewDidPerformAction içinde görünümü kendiniz kapatın.
Görünüm hataları: v3’te, varsayılan paywallViewDidFailRendering hiçbir şey yapmıyordu. v4’te, varsayılan flowViewDidReceiveError görünümü kapatır — görünümü açık tutmak veya hatayı farklı ele almak istiyorsanız bu davranışı geçersiz kılın.
Görünümler tek kullanımlıktır: dismiss() çağrısından sonra görünüm yok edilir. Flow’u tekrar göstermek için createFlowView metodunu yeniden çağırın.

Onboarding API’sinin Kullanımdan Kaldırılması

Eski onboarding API’si, v4.0’da Flow Builder lehine kullanımdan kaldırılmıştır. Hâlâ çalışmaktadır, ancak gelecekteki bir sürümde kaldırılacaktır; bu nedenle onboarding’lerinizi Flow Builder’a taşımayı planlayın.

Kullanımdan kaldırılan semboller: getOnboarding, getOnboardingForDefaultAudience, AdaptyUI.createOnboardingView, AdaptyUI.createNativeOnboardingView ve AdaptyUIOnboardingsEventsObserver.