Adapty Flutter SDK'yı v4.0'a Geçirme
Adapty Flutter SDK 4.0, flow’ları tanıtır ve paywall API’larını buna göre yeniden adlandırır. Yeni API’lar flow’larla çalışır ve eski builder’daki paywalllarla da çalışmaya devam eder — Adapty Kontrol Paneli tarafında herhangi bir kurulum değişikliği gerekmez.
Bu kılavuz 3.x → 4.0 geçişini kapsamaktadır. SDK 4.1, bunların üzerine birkaç API daha değiştiriyor — Adapty Attribution opt-in hale geliyor, harici attribution metodları yeniden adlandırılıyor ve yedek paywall dosya formatı tekrar değişiyor. Buradaki adımları tamamladıktan sonra, v4.1’e Geçiş bölümüne bakın.
Hızlı başvuru
| v3 | v4 |
|---|---|
Adapty().getPaywall(placementId: id) | Adapty().getFlow(placementId: id) |
Adapty().getPaywallForDefaultAudience(placementId: id) | Adapty().getFlowForDefaultAudience(placementId: id) |
Adapty().getPaywallProducts(paywall: paywall) | Adapty().getPaywallProducts(flow: flow) |
Adapty().logShowPaywall(paywall: paywall) | Adapty().logShowFlow(flow: flow) |
AdaptyPaywall (tür) | AdaptyFlow |
AdaptyPaywallFetchPolicy (tür) | AdaptyFlowFetchPolicy |
AdaptyUI().createPaywallView(paywall: paywall) | AdaptyUI().createFlowView(flow: flow) |
AdaptyUIPaywallView (tür) | AdaptyUIFlowView |
AdaptyUIPaywallPlatformView (widget) | AdaptyUIFlowPlatformView |
AdaptyUI().presentPaywallView(view) / dismissPaywallView(view) | AdaptyUI().presentFlowView(view) / dismissFlowView(view) |
AdaptyUIPaywallsEventsObserver | AdaptyUIFlowsEventsObserver |
AdaptyUI().setPaywallsEventsObserver(observer) | AdaptyUI().setFlowsEventsObserver(observer) |
paywallViewDid* callback’leri | flowViewDid* callback’leri |
paywallViewDidFailRendering | flowViewDidReceiveError |
AdaptyPaywallProduct adını korur — ürünler hâlâ bir flow’a aittir ve getPaywallProducts artık bir AdaptyFlow alır. Bir flow çekerken artık locale geçirmenize gerek yoktur. Satın alma ve profil API’leri (makePurchase, restorePurchases, getProfile, identify vb.) değişmeden kalmıştır; present, dismiss ve showDialog view metodları da aynı şekilde. Bazı varsayılan davranışlar değişti — bkz. Varsayılan davranış değişiklikleri.
Minimum sürümler
Adapty Flutter SDK 4.0, minimum gereksinimleri yükseltiyor:
- iOS 15.0 — minimum iOS deployment target, iOS 13.0’dan yükseltildi.
- Xcode 26 veya daha yenisi — yerel iOS SDK’sı Swift tools 6.2 kullanıyor.
- Flutter 3.32.0 (Dart 3.8.0) veya daha yenisi.
Kurulum
Paketi güncelleyin
Hangi paketi yükleyeceğiniz, uygulamanızın Kids Mode kullanıp kullanmadığına bağlıdır.
Çoğu uygulama için pubspec.yaml dosyanızda adapty_flutter paketini v4.0’a güncelleyin:
dependencies:
adapty_flutter: 4.0.3
Uygulamanız Kids Mode kullanıyorsa bunun yerine adapty_flutter_kids belirtin:
dependencies:
adapty_flutter_kids: 4.0.3
Bu bağımsız paket, App Store gereksinimlerine uymak için IDFA ve reklam takip kodlarını kaldırır. Dart import yolunu package:adapty_flutter_kids/adapty_flutter.dart olarak güncelleyin. Bunun dışında, migration işlemi normal paketle tamamen aynıdır.
Kids Mode ayrıca Adapty Kontrol Paneli’nde IP adresi toplamanın devre dışı bırakılmasını gerektirir — tam kurulum için Kids Mode sayfasına bakın.
iOS: yerel SDK’lar artık Swift Package Manager üzerinden geliyor
CocoaPods’ın spec deposu Aralık 2026’da salt okunur hale geliyor, bu nedenle v4 itibarıyla yerel iOS SDK’sı artık CocoaPods üzerinden dağıtılmıyor — eklenti bunu yalnızca Swift Package Manager aracılığıyla çekiyor.
Flutter 3.32–3.43 kullanıyorsanız, Swift Package Manager desteğini bir kez etkinleştirin:
flutter config --enable-swift-package-manager
Flutter 3.44 ve sonrası Swift Package Manager’ı varsayılan olarak etkinleştiriyor, dolayısıyla bu sürümlerde herhangi bir işlem yapmanıza gerek yok.
Flow’ları getirme
getPaywall → getFlow
Döndürülen tür AdaptyPaywall’dan AdaptyFlow’a değişir ve locale parametresi fetch çağrısından createFlowView’a taşınır (Flutter SDK 4.0.3 ve sonrası; önceki 4.0.x sürümlerinde yerelleştirme seçme imkânı yoktur) — bkz. Yerel ayar eşleşmesi birebir yapılır; özel paywaller için tüm yapılandırılmış yerel ayarlar flow.remoteConfigs içinde döndürülür:
- final paywall = await Adapty().getPaywall(placementId: 'YOUR_PLACEMENT_ID', locale: 'en');
+ final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');
getPaywallForDefaultAudience aynı şekilde yeniden adlandırılır:
- final paywall = await Adapty().getPaywallForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID', locale: 'en');
+ final flow = await Adapty().getFlowForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');
Fetch policy türü AdaptyPaywallFetchPolicy yerine AdaptyFlowFetchPolicy olarak yeniden adlandırılır; seçenekleri (reloadRevalidatingCacheData, returnCacheDataElseLoad, returnCacheDataIfNotExpiredElseLoad) değişmez.
Yerel ayar eşleşmesi tam eşleşmeye dayalıdır
v3’te Adapty sunucusu yerelleştirmeyi seçer ve dile geri dönerdi: paywall’ın pt-br yerelleştirmesi yoksa pt isteği pt yerelleştirmesini alırdı. v4’te SDK, yerelleştirmeyi cihaz üzerinde seçer ve yalnızca tam eşleşme kullanır. Hiçbir yerelleştirmeyle eşleşmeyen bir kod, flow’u varsayılan yerelleştirmesiyle hatasız ve uyarısız olarak render eder.
Yükseltme yapmadan önce, uygulamanızın ilettiği yerel ayar kodlarını kontrol edin:
- Her bölgesel kod için, o koda sahip bir yerelleştirme ekleyin — örneğin
ptyanınapt-br— ya da kodu flow’un sahip olduğu bir kodla eşleştirin. - Kodları kontrol panelinde göründüğü şekilde geçirin — küçük harfli, kısa çizgiyle ayrılmış alt etiketler. Sistem locale tanımlayıcısını olduğu gibi geçirmeyin:
Platform.localeNamept_BRdöndürür ve bu hiçbir yerelleştirmeyle eşleşmez.
Bkz. Yerelleştirmeler ve locale kodları.
getPaywallProducts(paywall) → getPaywallProducts(flow)
getPaywallProducts adını korur ancak artık flow parametresi aracılığıyla bir AdaptyFlow alır:
- final products = await Adapty().getPaywallProducts(paywall: paywall);
+ final products = await Adapty().getPaywallProducts(flow: flow);
Yedek dosyalar
Yedek dosya formatı SDK v4 ile değişti. Yeni dosyayı Placements > Fallbacks bölümünden indirip uygulamanıza ekleyin.
Veri modeli
getFlow, AdaptyPaywall yerine bir AdaptyFlow döndürür ve nesne yapısı değişti:
v3 AdaptyPaywall üyesi | v4 AdaptyFlow üyesi | İşlem |
|---|---|---|
remoteConfig (tekil, nullable) | remoteConfigs (liste) | Bir flow, yapılandırılmış her dil için bir remote config taşır. remoteConfig getter’ı hâlâ mevcuttur ve ilk girişi döndürür; belirli bir dil seçmek için remoteConfigs içinde locale değerine göre arama yapın. |
productIdentifiers | productIdentifiers | Korundu, ancak artık flow’un tüm paywall varyasyonlarından derleniyor. Varyasyon bazındaki tanımlayıcılar flow.paywalls[i].productIdentifiers üzerinde bulunur. |
hasViewConfiguration | hasViewConfiguration | Değişmedi. |
placementId (kullanımdan kalktı) | kaldırıldı | flow.placement.id kullanın. |
revision (kullanımdan kalktı) | kaldırıldı | flow.placement.revision kullanın. |
vendorProductIds (kullanımdan kalktı) | kaldırıldı | productIdentifiers kullanın. |
| (yeni) | paywalls (AdaptyFlowPaywall listesi) | Her giriş, flow içindeki bir paywall varyasyonunu temsil eder ve kendine ait name, variationId ve productIdentifiers değerlerine sahiptir. |
AdaptyPaywallViewConfiguration artık açık değil — görünüm yapılandırması artık opak. Bu türe yapılan tüm referansları kaldırın.
Web paywall metodları
openWebPaywall ve createWebPaywallUrl isimlerini korur, ancak paywall parametresi artık AdaptyPaywall yerine AdaptyFlowPaywall (bir flow varyasyonu) alır. Yine de bunun yerine AdaptyPaywallProduct geçirebilirsiniz.
final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');
- await Adapty().openWebPaywall(paywall: paywall);
+ if (flow.paywalls.isNotEmpty) {
+ await Adapty().openWebPaywall(paywall: flow.paywalls[0]);
+ }
Flow görüntülemelerini takip etme
logShowPaywall → logShowFlow
logShowPaywall, logShowFlow olarak yeniden adlandırıldı ve artık bir AdaptyFlow alıyor. Olay hâlâ aynı varyanta karşı kaydedildiğinden, mevcut huni ve A/B testi metrikleri kontrol panelinde herhangi bir değişiklik yapılmadan çalışmaya devam eder.
- await Adapty().logShowPaywall(paywall: paywall);
+ await Adapty().logShowFlow(flow: flow);
v3’te olduğu gibi, Adapty tarafından render edilen flow’ları veya 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
Metodu yeniden adlandırın ve AdaptyFlow’u flow parametresi aracılığıyla geçirin. Diğer parametreler (loadTimeout, preloadProducts, customTags, customTimers, customAssets, productPurchaseParams) ile present, dismiss ve showDialog view metodları değişmeden kalır:
customTimers hâlâ mevcut, ancak yalnızca eski Paywall Builder paywalllarını etkiliyor. Bir flow’un geri sayım zamanlayıcısı, Flow & Paywall Builder’da ayarlanan davranışa göre çalışır; dolayısıyla bir flow, buraya geçirdiğiniz değerleri yok sayar.
- final view = await AdaptyUI().createPaywallView(paywall: paywall);
+ final view = await AdaptyUI().createFlowView(flow: flow);
await view.present();
AdaptyUIPaywallView → AdaptyUIFlowView
Görünüm türü yeniden adlandırıldı. Kullanımdan kaldırılmış paywallVariationId özelliği kaldırıldı — bunun yerine variationId kullanın:
- void flowViewDidAppear(AdaptyUIPaywallView view) {
+ void flowViewDidAppear(AdaptyUIFlowView view) {
AdaptyUIPaywallPlatformView → AdaptyUIFlowPlatformView
Görünümü widget ağacınıza widget olarak gömmek istiyorsanız, adını değiştirin ve flow parametresini geçin. Olay callback’leri (onDidAppear, onDidFinishPurchase vb.) aynı isimlerini korur:
- AdaptyUIPaywallPlatformView(
- paywall: paywall,
+ AdaptyUIFlowPlatformView(
+ flow: flow,
onDidFinishPurchase: (view, product, purchaseResult) { /* … */ },
)
createFlowView ile oluşturulan bir flow görünümü tek kullanımlıktır: dismiss() çağrıldıktan sonra görünüm bellekten serbest bırakılır ve bir daha gösterilemez — flow’u tekrar göstermek için createFlowView’ı yeniden çağırın.
Olayları Yönetme
Observer sınıfı AdaptyUIPaywallsEventsObserver’dan AdaptyUIFlowsEventsObserver’a, kayıt metodu setPaywallsEventsObserver’dan setFlowsEventsObserver’a ve tüm paywallViewDid* callback’leri flowViewDid*’e yeniden adlandırıldı:
- class MyObserver extends AdaptyUIPaywallsEventsObserver {
+ class MyObserver extends AdaptyUIFlowsEventsObserver {
@override
- void paywallViewDidPerformAction(AdaptyUIPaywallView view, AdaptyUIAction action) {
+ void flowViewDidPerformAction(AdaptyUIFlowView view, AdaptyUIAction action) {
// …
}
}
- AdaptyUI().setPaywallsEventsObserver(this);
+ AdaptyUI().setFlowsEventsObserver(this);
Artık üç callback zorunludur — bunlar olmadan observer’ınız derlenmez:
flowViewDidFinishPurchase: v3’te isteğe bağlıydı; varsayılan davranış satın alma sonrasında görünümü kapatıyordu. Artık ne olacağına siz karar veriyorsunuz: flow’a devam edin ya daview.dismiss()çağırın.flowViewDidFinishRestore: v3’te olduğu gibi zorunludur.flowViewDidReceiveError:paywallViewDidFailRenderingyerine gelir ve artık diğer görünüm hatalarını da alır.
İki küçük değişiklik daha:
setFlowsEventsObserver(vesetOnboardingsEventsObserver) artık önceden ayarlanmış bir observer’ı kaldırmak içinnulldeğerini kabul eder; böylece SDK onu artık tutmaz.- Yeni isteğe bağlı
flowViewDidReceiveAnalyticEventcallback’i, bir flow’dan analiz olaylarını raporlar; kullanıcının her açtığı ekran için ekran görüntüleme olayıyla başlar. Bkz. Flow ekran görüntülemelerini takip etme.
v4 ayrıca isteğe bağlı olarak kullanabileceğiniz yeni özellikler de ekler:
AdaptyUI().setObserverModeResolver(...)ile birlikteAdaptyUIObserverModeResolver— SDK Observer mode olarak çalışırken flow’lardan başlatılan satın alma ve geri yüklemeleri yönetir. Daha önce bu yalnızca native iOS ve Android SDK’larında kullanılabiliyordu. Bkz. Flow’ları Observer mode’da sunma.AdaptyUI().setSystemRequestsHandler(...)ile birlikteAdaptyUISystemRequestsHandler— bir flow’dan gelen sistem istekleri (işletim sistemi izin istemleri ve App Store inceleme istekleri) için ayrılmıştır. Flow’lar henüz bu istekleri tetiklemediğinden bir handler kaydetmeniz gerekmez.
Kaldırılan API’lar
Bu semboller 3.x sürümünde kullanımdan kaldırılmıştı ve v4’te tamamen kaldırılmıştır:
setFallbackPaywalls → setFallback
- await Adapty().setFallbackPaywalls(assetId);
+ await Adapty().setFallback(assetId);
withIdfaCollectionDisabled → withAppleIdfaCollectionDisabled
configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
- ..withIdfaCollectionDisabled(true),
+ ..withAppleIdfaCollectionDisabled(true),
Kaldırılan diğer üyeler
AdaptyPurchaseResultSuccess.jwsTransaction:appleJwsTransactionkullanın.AdaptyUIFlowView.paywallVariationId:variationIdkullanın.AdaptyUIObserverveAdaptyUI().setObserver(...):AdaptyUIFlowsEventsObservervesetFlowsEventsObserver(...)kullanın.
Varsayılan davranış değişiklikleri
Bu değişiklikler derleme hatası oluşturmaz, bu nedenle çalışma zamanında test edin:
- Flow yerelleştirme: Bölgesel bir yerel ayar kodu artık kendi diline geri dönmez —
pt-br,ptyerelleştirmesini almaz. Tam eşleşme olmayan bir kod, flow’u varsayılan yerelleştirmesiyle gösterir. Bkz. Yerel ayar eşleşmesi tamdır. - Başarılı satın alma: v3’te varsayılan
paywallViewDidFinishPurchasegörünümü kapatıyordu. v4’teflowViewDidFinishPurchasezorunludur ve varsayılanı yoktur — bu davranışı istiyorsanız görünümü kendiniz kapatın. - Android sistem geri tuşu: Artık varsayılan olarak bir flow’u kapatmaz. Eylem,
flowViewDidPerformAction’aAndroidSystemBackActionolarak iletilir — geri tuşunun flow’u kapatmasını istiyorsanız bunu orada ele alın. - URL açma: Varsayılan
flowViewDidPerformActionartıkOpenUrlAction’ı URL’yi yerel olarak açarak işler (kontrol panelindeki uygulama içi veya harici tarayıcı ayarına uygun şekilde);CloseActionile de görünümü kapatır. URL’leri kendiniz ele almak için callback’i geçersiz kılın. - Görünüm hataları:
flowViewDidReceiveErrorzorunludur ve kapatma işlemi sizin uygulamanıza bağlıdır. v3 entegrasyonunuz görünümü oluşturma hatalarında otomatik olarak kapatmaya dayanıyorsa, bu callback’teview.dismiss()çağrısı yapın. - Görünüm yaşam döngüsü: Bir flow veya onboarding görünümünü kapatmak onu bellekten siler. Kapatılan bir görünüm artık yeniden gösterilemez — bunun yerine yeni bir tane oluşturun.
Onboarding API kullanımdan kaldırma
Eski onboarding API’si, v4.0’da Flow & Paywall Builder lehine kullanımdan kaldırılmıştır. Hâlâ çalışmaya devam etmektedir; IDE’niz, kullanımdan kaldırılan sembolleri @Deprecated notasyonları aracılığıyla işaretler — çalışma zamanında herhangi bir uyarı gösterilmez. Bu semboller gelecekteki bir sürümde kaldırılacağından, onboarding’lerinizi Flow & Paywall Builder’a taşımayı planlayın.
Kullanımdan kaldırılan semboller: getOnboarding, getOnboardingForDefaultAudience, createOnboardingView, presentOnboardingView, dismissOnboardingView, setOnboardingsEventsObserver, AdaptyOnboarding, AdaptyUIOnboardingView, AdaptyUIOnboardingPlatformView, AdaptyUIOnboardingsEventsObserver ve onboarding durum, girdi ile analitik modelleri.