Adapty Capacitor SDK 4.1.1, 4.x serisinin mevcut kararlı sürümüdür — 4.0 yalnızca beta olarak yayınlandığından, 3.x kullanıyorsanız doğrudan 4.1.1’e geçiş yapın. Bu kılavuz, 4.0’da tanıtılan flow’ları ve bunların üzerine gelen 4.1.1 değişikliklerini kapsayan tüm geçiş sürecini ele almaktadır.

4.x serisi 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’dan gelen paywall’larla da sorunsuz çalışmaya devam eder — Adapty Kontrol Paneli tarafında herhangi bir kurulum değişikliği gerekmez. Bunların yanı sıra, 4.1.1 Adapty Attribution’ı opt-in hâle getirir, harici attribution metodunu yeniden adlandırır, yedek paywall dosya formatını değiştirir ve App Store’da tanıtılan uygulama içi satın almaları ekler.

Hızlı Başvuru

v3	v4.1.1
Adapty Attribution otomatik olarak etkinleştirilir	varsayılan olarak devre dışı — adaptyAttributionEnabled: true ile etkinleştirin
adapty.getPaywall({ placementId, locale?, params? })	adapty.getFlow({ placementId, params? })
adapty.getPaywallForDefaultAudience({ placementId, locale?, params? })	adapty.getFlowForDefaultAudience({ placementId, params? })
adapty.getPaywallProducts({ paywall })	adapty.getPaywallProducts({ flow })
adapty.logShowPaywall({ paywall })	adapty.logShowFlow({ flow })
AdaptyPaywall (tür)	AdaptyFlow + AdaptyFlowPaywall
createPaywallView(paywall, params?)	createFlowView(flow, params?)
PaywallViewController	FlowViewController
EventHandlers (tür)	FlowEventHandlers
CreatePaywallViewParamsInput	CreateFlowViewParamsInput
onRenderingFailed	onError
adapty.updateAttribution({ attribution, source })	adapty.updateExternalAttribution({ attribution, provider })
AdaptyProfile.appliedAttributionSources	AdaptyProfile.appliedExternalAttributionProviders
AttributionSource	AdaptyExternalAttributionProvider
3.x için indirilen yedek dosya	yeni yedek dosya formatı — dosyayı yeniden indirin
Tanıtılan uygulama içi satın almalar otomatik olarak tamamlanır, araya girme imkânı yoktur	'onPromotedPurchaseReceived' olayı ve adapty.makePromotedPurchase({ product }) tamamlamayı uygulamanıza bırakır

AdaptyPaywallProduct adını korur — ürünler hâlâ bir flow’a aittir ve getPaywallProducts de adını korur, artık bir AdaptyFlow alır. getFlow ve getFlowForDefaultAudience metodları artık locale parametresi almaz — bunun yerine createFlowView’a geçirin. Satın alma ve profil API’leri (makePurchase, restorePurchases, getProfile, identify, updateProfile) ve setFallback aynı imzaları korur, ancak yedek dosyanın kendisinin yeniden indirilmesi gerekir — bkz. Yedek dosyalar. present, dismiss, setEventHandlers, clearEventHandlers ve showDialog view metodları ile onCloseButtonPress, onUrlPress, onCustomAction, onProductSelected, onPurchaseStarted, onPurchaseCompleted, onPurchaseFailed, onRestoreStarted, onRestoreCompleted, onRestoreFailed, onLoadingProductsFailed, onWebPaymentNavigationFinished ve onAndroidSystemBack olay işleyicileri v3’teki ile aynı adları korur. Onboarding metodları hâlâ çalışır ancak kullanımdan kaldırılmıştır — bkz. Onboarding API’sinin kullanımdan kaldırılması. Bazı varsayılan davranışlar değişti — bkz. Varsayılan davranış değişiklikleri.

Minimum sürümler

Çalışma zamanı gereksinimleri v3.16+ sürümünden itibaren değişmedi: iOS 15.0, Android minSdk 24 ve Capacitor 8. Deployment target değişikliğine gerek yok.

Yeni bir derleme gereksinimi var: Xcode 26 veya üzeri — bu sürümle birlikte gelen yerel Adapty iOS SDK’sı Swift tools 6.2 kullanıyor.

Kurulum

Paketi güncelleyin

npm install @adapty/capacitor@latest

Ardından yerel projeleri senkronize edin:

npx cap sync

iOS: Yalnızca Swift Package Manager

CocoaPods’ın spec repo’su Aralık 2026’da salt okunur hale geliyor; bu nedenle v4 itibarıyla AdaptyCapacitor.podspec kaldırılmıştır ve SDK, iOS’ta yalnızca Swift Package Manager (SPM) üzerinden kurulmaktadır. Uygulamanızın iOS projesinin Capacitor’ın SPM entegrasyonunu kullanması gerekir:

• Yeni uygulamalar için iOS platformunu SPM paket yöneticisiyle ekleyin:

npx cap add ios --packagemanager SPM

• Mevcut CocoaPods tabanlı uygulamalar: Capacitor’ın mevcut bir projede SPM kullanma kılavuzunu izleyerek iOS projesini taşıyın.

Tam kurulum için Adapty SDK’yı Yükle sayfasına bakın.

⚠️ Adapty Attribution varsayılan olarak devre dışıdır

Önceki sürümlerde SDK, Adapty Attribution için yüklemeleri otomatik olarak kaydediyordu. SDK 4.1.1 sürümünden itibaren bu özellik varsayılan olarak kapalıdır: SDK yüklemeleri kaydetmez, 'onInstallationDetailsSuccess' ve 'onInstallationDetailsFail' olayları hiçbir zaman tetiklenmez ve getCurrentInstallationStatus fonksiyonu not_available durumunu döndürür.

Adapty Attribution kullanıyorsanız, SDK’yı etkinleştirirken bu özelliği açın:

  await adapty.activate({
    apiKey: 'YOUR_PUBLIC_SDK_KEY',
    params: {
+     adaptyAttributionEnabled: true,
    },
  });

Adapty Attribution kullanmıyorsanız herhangi bir değişiklik yapmanıza gerek yoktur.

Flow’ları Getirme

getPaywall → getFlow

Döndürülen tür AdaptyPaywall’dan AdaptyFlow’a değişiyor ve locale seçeneği fetch çağrısından createFlowView’e taşınıyor; özel paywaller için tüm locale’ler flow.remoteConfigs içinde döndürülüyor:

- const paywall = await adapty.getPaywall({ placementId: 'YOUR_PLACEMENT_ID', locale: 'en' });
+ const flow = await adapty.getFlow({ placementId: 'YOUR_PLACEMENT_ID' });
+ const view = await createFlowView(flow, { locale: 'en' });

locale, createFlowView üzerinde isteğe bağlı olmaya devam eder: belirtmezseniz görünüm en dilinde veya flow’un varsayılan yerelleştirmesinde (flow’un en dili yoksa) render edilir. Bu geri dönüş mekanizması nedeniyle görünüm, talep ettiğinizden farklı bir yerelleştirmede render edilebilir — yeni FlowViewController.locale özelliği hangisinin kullanıldığını bildirir. Bkz. Yerelleştirmeler ve locale kodları.

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

- const paywall = await adapty.getPaywallForDefaultAudience({ placementId: 'YOUR_PLACEMENT_ID', locale: 'en' });
+ const flow = await adapty.getFlowForDefaultAudience({ placementId: 'YOUR_PLACEMENT_ID' });

getPaywallProducts(paywall) → getPaywallProducts(flow)

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

- const products = await adapty.getPaywallProducts({ paywall });
+ const products = await adapty.getPaywallProducts({ flow });

Yedek dosyalar

Yedek dosya formatı 4.0’da ve yeniden 4.1.1’de değişti. Daha önce bir 4.0 beta sürümü için indirmiş olsanız bile, dosyayı Placements > Fallbacks bölümünden tekrar indirip uygulamanıza ekleyin.

Veri modeli

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

v3 AdaptyPaywall alanı	v4 AdaptyFlow alanı	İşlem
remoteConfig? (tekil)	remoteConfigs?: AdaptyRemoteConfig[] (dizi)	Bir flow, yapılandırılmış her dil için ayrı bir remote config taşır. Kullanıcıyla eşleşeni okuyun: flow.remoteConfigs?.find((c) => c.lang === 'en').
productIdentifiers	flow.paywalls[i].productIdentifiers	Ürün tanımlayıcıları artık flow’da değil, her flow varyantında yer alır.
products (v3’te kullanımdan kaldırıldı)	kaldırıldı	flow.paywalls[i].productIdentifiers kullanın ya da tam ürünler için getPaywallProducts(flow) çağrısı yapın. ProductReference artık public bir tür olarak mevcut değil.
webPurchaseUrl?	flow.paywalls[i].webPurchaseUrl	Flow’dan her paywall varyantına taşındı.
version?: number	flowVersionId?: string	Yeniden adlandırıldı ve tür number’dan string’e değiştirildi.
requestLocale	kaldırıldı	Locale artık modelin parçası değil.
(yeni)	paywalls: AdaptyFlowPaywall[]	Her giriş, flow’daki bir paywall varyantını temsil eder.
(yeni)	responseCreatedAt: number	Sunucu yanıt zaman damgası, milisaniye cinsinden.

requestLocale AdaptyOnboarding üzerinde kalmaya devam eder — yalnızca flow modeli onu kaldırır.

Ürün tanımlayıcıları flow’dan her bir varyasyona taşındı:

- const ids = paywall.productIdentifiers;
+ const ids = flow.paywalls[0].productIdentifiers;

Kodunuz hâlâ paywall.products okuyorsa — v3’te kullanımdan kaldırılmış ve artık tamamen kaldırılmıştır — productIdentifiers’a geçin ya da tanımlayıcılar yerine tam ürünlere ihtiyacınız varsa getPaywallProducts(flow) kullanın.

Web paywall yöntemleri

openWebPaywall ve createWebPaywallUrl adlarını korur, ancak paywallOrProduct seçeneği artık AdaptyPaywall yerine AdaptyFlowPaywall (bir flow varyasyonu) alır. Yine de AdaptyPaywallProduct geçirebilirsiniz. İlk girişi okumadan önce flow.paywalls öğesinin boş olmadığını kontrol edin:

  const flow = await adapty.getFlow({ placementId: 'YOUR_PLACEMENT_ID' });
- await adapty.openWebPaywall({ paywallOrProduct: paywall });
+ await adapty.openWebPaywall({ paywallOrProduct: 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, aynı varyasyon üzerinde kaydedilmeye devam ediyor; 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.

- await adapty.logShowPaywall({ paywall });
+ await adapty.logShowFlow({ flow });

v3’te olduğu gibi, Adapty tarafından oluşturulan flow’ları veya paywallları görüntülerken bu metodu çağırmanız gerekmez — Adapty bu görüntülemeleri otomatik olarak takip eder.

Flow’ları Görüntüleme

createPaywallView → createFlowView

Factory fonksiyonunu yeniden adlandırın ve AdaptyFlow’u geçirin. Döndürülen controller PaywallViewController’dan FlowViewController’a yeniden adlandırılmıştır, ancak metotları (present, dismiss, setEventHandlers, clearEventHandlers ve showDialog) değişmeden kalmıştır. Params türü CreatePaywallViewParamsInput’tan CreateFlowViewParamsInput’a yeniden adlandırılmıştır:

- import { createPaywallView } from '@adapty/capacitor';
+ import { createFlowView } from '@adapty/capacitor';

- const view = await createPaywallView(paywall);
+ const view = await createFlowView(flow);
  await view.present();

Yeni parametreler

CreateFlowViewParamsInput, v3’teki tüm parametreleri (prefetchProducts, loadTimeoutMs, customTags, customTimers, customAssets, productPurchaseParams) korur ve üç yeni parametre ekler:

Parametre	Açıklama
locale	Flow’un hangi dille görüntüleneceğini belirtir. Bu parametre getPaywall’dan buraya taşındı — bkz. getPaywall → getFlow.
customLayoutId	Flow’un layout yapılandırmasındaki bir düzene ait özel ID. Bu değeri geçerseniz SDK, cihaz türü ve ekran boyutuna göre otomatik seçmek yerine belirtilen düzeni kullanır. ID’ye uyan bir düzen bulunamazsa çağrı, no-view-configuration hatasıyla başarısız olur. Flow & Paywall Builder henüz özel layout ID’si atamıyor, bu yüzden bu değeri boş bırakın.
android.enableSafeArea	Android güvenli alan (safe-area) dolgularını çalışma zamanında denetler. android anahtarının altında yer alır ve varsayılan değeri true’dur.

const view = await createFlowView(flow, {
  locale: 'en',
  customLayoutId: 'tablet_landscape',
  android: { enableSafeArea: true },
});

Olayları yönetme

Olay işleyici arayüzü EventHandlers yerine FlowEventHandlers olarak yeniden adlandırıldı ve bir callback yeniden adlandırıldı. Mevcut işleyici gövdelerinde kod değişikliği gerekmez — sadece yeniden adlandırın:

- onRenderingFailed: (error) => { /* … */ },
+ onError: (error) => { /* … */ },

Diğer tüm event handler’lar isimlerini korur. Biri imzasını değiştirir: onAppeared artık () yerine (view) şeklindedir; burada view, ortaya çıkan görünümü açıklayan — oluşturulduğu lokalizasyon dahil — bir FlowEventView nesnesidir. Mevcut handler’lar yeni argümanı görmezden geldiği için çalışmaya devam eder. Tam liste için Flow & paywall event’lerini yönetme bölümüne bakın.

v4 ayrıca isteğe bağlı olarak kullanabileceğiniz birkaç yetenek ekler:

• adapty.openWebUrl({ url, openIn }) ve adapty.requestAppReview() metodları — bunlar varsayılan onUrlPress ve onRequestAppReview handler’larını destekler; dolayısıyla URL’ler ve uygulama değerlendirme istemleri kutudan çıktığı gibi yerel olarak işlenir. Yalnızca bu handler’ları geçersiz kılıyorsanız doğrudan çağırın.
• Flow’lar içinde Observer mode satın alma işlemi, yeni onObserverPurchaseInitiated / onObserverRestoreInitiated handler’ları aracılığıyla gerçekleştirilir. Bkz. Flow’ları Observer mode’da sunma.
• onAnalytics: (name, params) — bir flow’un yaydığı analytics olayları; kullanıcının açtığı her ekran için bir ekran görüntüleme olayıyla başlar. Bkz. Flow ekran görüntülemelerini izleme.
• onRequestPermission: (permission, customArgs) — bir flow’dan gelen sistem izni istekleri (push bildirimleri veya kamera erişimi gibi) için ayrılmıştır. Flow’lar henüz izin isteği tetiklemiyor, bu yüzden bunu uygulamanız gerekmiyor.

Ayrıca, 4.1.1 bir flow işleyicisi yerine SDK düzeyinde bir olay ekler: 'onPromotedPurchaseReceived'; bu olay adapty.addListener aracılığıyla iletilir. Herhangi bir dinleyici kayıtlı değilse SDK, tanıtılan satın almayı kendisi tamamlar; bir dinleyici kaydedilmesi ise tamamlamayı uygulamanıza bırakır. Bkz. App Store’da tanıtılan uygulama içi satın almalar.

Yeniden Adlandırılan Harici Attribution API’ları

SDK 4.1.1 sürümünden itibaren, harici bir sağlayıcıdan (Adjust, AppsFlyer, Branch, Tenjin veya özel bir sağlayıcı) attribution verisi aktarmak için kullanılan API’lar, native SDK’larla uyumlu olacak şekilde yeniden adlandırıldı. Eski adlar için herhangi bir deprecated alias bulunmamaktadır; bu nedenle mevcut çağrı noktaları, siz yeniden adlandırana kadar çalışmayı durduracaktır:

4.1.1 Öncesi	4.1.1
adapty.updateAttribution({ attribution, source })	adapty.updateExternalAttribution({ attribution, provider })
AttributionSource	AdaptyExternalAttributionProvider
AdaptyProfile.appliedAttributionSources	AdaptyProfile.appliedExternalAttributionProviders

updateAttribution → updateExternalAttribution

Metot yeniden adlandırıldı ve source seçeneği provider olarak değiştirildi. Attribution verisi hâlâ düz bir nesnedir:

- await adapty.updateAttribution({ attribution, source: 'adjust' });
+ await adapty.updateExternalAttribution({ attribution, provider: 'adjust' });

AttributionSource → AdaptyExternalAttributionProvider

Sağlayıcı türü yeniden adlandırıldı. Açık bir union olarak kalır — önceden tanımlanmış değerler 'apple_search_ads', 'adjust', 'appsflyer', 'branch' ve 'tenjin'dir; başka herhangi bir string de kabul edilir, bu sayede Adapty’nin ileride ekleyeceği bir sağlayıcı SDK güncellemesi gerektirmez:

- import type { AttributionSource } from '@adapty/capacitor';
+ import type { AdaptyExternalAttributionProvider } from '@adapty/capacitor';

AdaptyProfile.appliedAttributionSources → appliedExternalAttributionProviders

Profile’a uygulanan attribution sağlayıcılarını listeleyen profil özelliği yeniden adlandırıldı ve eleman türü de buna göre değişti:

- if (profile.appliedAttributionSources?.includes('apple_search_ads')) {
+ if (profile.appliedExternalAttributionProviders?.includes('apple_search_ads')) {
      // Apple Ads attribution has been applied
  }

Bu özelliği kullanan kodların güncellenmesi gerekiyor — bakınız Apple Ads hedefli paywall gösterme.

App Store’da öne çıkan uygulama içi satın almalar

4.1.1 öncesinde, App Store ürün sayfanızda öne çıkan uygulama içi satın almalar kendi kendine tamamlanıyor ve Adapty işlemi kaydediyordu; ancak uygulamanızın bunu yakalayacak bir yolu yoktu. 4.1.1 bu kancayı ekliyor; bu nedenle bu bir geçiş adımı değil, yeni bir özelliktir: kendi kodunuz olmadan SDK, öne çıkan satın almaları sizin adınıza tamamlamaya devam eder.

Tamamlamayı kendiniz üstlenmek için — örneğin önce bir ekran göstermek amacıyla — yalnızca kod yazın. Yeni 'onPromotedPurchaseReceived' etkinliği için bir dinleyici kaydedin ve satın almayı adapty.makePromotedPurchase ile tamamlayın. Bu dinleyici kayıtlıyken, SDK promosyon satın almalarını sizin yerinize tamamlamayı durdurur.

Varsayılan davranış değişiklikleri

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

• onAndroidSystemBack: Varsayılan davranış, görünümü kapatmaktan açık tutmaya değişti. Önceki davranışı geri yüklemek için handler’dan true döndürün.
• onPurchaseCompleted: Varsayılan davranış, satın alma iptal edilmediği sürece görünümü kapatmaktan her zaman açık tutmaya değişti. Önceki davranışı geri yüklemek için handler’dan purchaseResult.type !== 'user_cancelled' döndürün.
• onRestoreCompleted: Varsayılan davranış, başarılı bir geri yüklemenin ardından görünümü kapatmaktan açık tutmaya değişti. Önceki davranışı geri yüklemek için handler’dan true döndürün.
• onUrlPress: Varsayılan artık URL’yi yerel katman aracılığıyla açıyor; kontrol panelindeki uygulama içi veya harici tarayıcı ayarına göre davranıyor. URL’leri kendiniz açmak için handler’ı geçersiz kılın.
• Görünümler tek kullanımlıktır: dismiss() çağrıldıktan sonra görünüm yok edilir. Flow’u tekrar göstermek için createFlowView’ı yeniden çağırın.

Kaldırılan API’ler

Kaldırılan exportlar

Bu semboller artık @adapty/capacitor’dan export edilmiyor. İlgili importları kaldırın:

• AdaptyPaywall: Bunun yerine AdaptyFlow ve AdaptyFlowPaywall kullanın.
• ProductReference: Bunun yerine AdaptyProductIdentifier kullanın; flow.paywalls[i].productIdentifiers üzerinden okuyun.
• AdaptyPaywallBuilder: Kaldırıldı. Flow’lar ve paywall’lar artık native olarak render edilir.
• AdaptyAndroidSubscriptionUpdateParameters: İç içe geçmiş android satın alma parametre yapısını kullanın (aşağıya bakın).

activate: lockMethodsUntilReady

lockMethodsUntilReady (v3’te zaten kullanımdan kaldırılmış ve işlevsiz hale getirilmişti) kaldırıldı. activate çağrınızdan bu parametreyi kaldırın — aksi hâlde artık derlenmez:

- await adapty.activate({ apiKey: 'PUBLIC_SDK_KEY', params: { lockMethodsUntilReady: true } });
+ await adapty.activate({ apiKey: 'PUBLIC_SDK_KEY' });

makePurchase: Android parametreleri

MakePurchaseParamsInput’ın kullanımdan kaldırılmış düz Android yapısı kaldırıldı — yalnızca iç içe geçmiş form geçerlidir. Android satın alma parametrelerini params: { android: { ... } } içine taşıyın. Tam örnek için Satın alma yapma sayfasına bakın.

Onboarding API’sının kullanımdan kaldırılması

Eski onboarding API’sı, v4’te Flow & Paywall 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 onboardinglerınızı Flow & Paywall Builder’a taşımayı planlayın.

Kullanımdan kaldırılan semboller: getOnboarding, getOnboardingForDefaultAudience, createOnboardingView ve OnboardingViewController.