Adapty SDK, Capacitor uygulamanıza sorunsuz entegrasyon için iki temel modül içerir:

• Core Adapty: Bu modül, Adapty’nin uygulamanızda düzgün çalışması için gereklidir.
• AdaptyUI: Bu modül, eski builder paywalllarına ek olarak flow’ları da render eder. AdaptyUI, core modülüyle birlikte otomatik olarak etkinleştirilir.

Gereksinimler

Adapty Capacitor SDK aşağıdaki sürüm gereksinimlerine sahiptir:

Adapty SDK Sürümü	Capacitor Sürümü	iOS Sürümü
4.1+	8	15.0+
3.16.0+	8	15.0+
3.15	7	14.0+

Capacitor 6 ve altı sürümler desteklenmemektedir.

iOS için derleme yapmak üzere Xcode 26 veya daha yeni bir sürüm gereklidir — yerel iOS SDK’sı Swift tools 6.2 ile derlenmiştir. Android’de minimum SDK sürümü 24’tür.

Adapty SDK’yı Yükleme

Adapty SDK’yı yükleyin:

npm install @adapty/capacitor
npx cap sync

iOS’ta Adapty SDK, yerel Adapty SDK’larını yalnızca Swift Package Manager aracılığıyla çeker — CocoaPods podspec kaldırıldı (CocoaPods’un spec repo’su Aralık 2026’da salt okunur hale geliyor). 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 uygulamalar için, iOS projesini CocoaPods’tan SPM’e taşımak amacıyla Capacitor’ın mevcut bir projede SPM kullanma kılavuzunu takip edin.

v3’ten yükseltme mi yapıyorsunuz? Tüm API değişiklikleri için Adapty Capacitor SDK’yı v4.1’e taşıma belgesine bakın.

Adapty SDK’nın Adapty modülünü etkinleştirin

Public SDK Key’inizi almak için:

1. Adapty Kontrol Paneli’ne gidin ve App settings → General sayfasına gidin.
2. Api keys bölümünden Public SDK Key’i kopyalayın (Secret Key’i değil).
3. Koddaki "YOUR_PUBLIC_SDK_KEY" ifadesini değiştirin.

Ya da Adapty CLI kullanarak programatik olarak alın:

npm install -g adapty
adapty auth login
adapty apps list

Ya da doğrudan:

npx adapty auth login
adapty apps list

• Adapty başlatma işlemi için Public SDK key kullandığınızdan emin olun; Secret key yalnızca sunucu taraflı API için kullanılmalıdır.
• SDK key’leri her uygulama için benzersizdir, bu nedenle birden fazla uygulamanız varsa doğru olanı seçtiğinizden emin olun.

Adapty’yi etkinleştirmek için aşağıdaki kodu herhangi bir uygulama dosyasına kopyalayın:

try {
  await adapty.activate({
    apiKey: 'YOUR_PUBLIC_SDK_KEY',
    params: {
      // verbose logging is recommended for the development purposes and for the first production release
        logLevel: 'verbose',
      // in the development environment, use this variable to avoid multiple activation errors. Set it to your development environment variable
      __ignoreActivationOnFastRefresh: true,
    }
  });
  console.log('Adapty activated successfully!');
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
}

Şimdi uygulamanızda paywallları ayarlayın:

• Flow & Paywall Builder kullanıyorsanız hızlı başlangıç kılavuzunu takip edin.
• Kendi paywall arayüzünüzü oluşturuyorsanız özel paywalllar için hızlı başlangıç kılavuzuna bakın.

Adapty SDK’nın AdaptyUI modülünü etkinleştirme

Flow & Paywall Builder kullanmayı planlıyorsanız AdaptyUI modülüne ihtiyacınız var. Bu işlem, core modülü etkinleştirdiğinizde otomatik olarak gerçekleşir; başka bir şey yapmanıza gerek yoktur.

İsteğe bağlı kurulum

Günlükleme

Günlük sistemini yapılandırın

Adapty, neler olduğunu anlamanıza yardımcı olmak için hataları ve diğer önemli bilgileri günlüğe kaydeder. Aşağıdaki seviyeler kullanılabilir:

Level	Description
error	Yalnızca hatalar loglanır
warn	Kritik hatalara yol açmayan ancak dikkat edilmesi gereken hatalar ve SDK mesajları loglanır
info	Hatalar, uyarılar ve çeşitli bilgi mesajları loglanır
verbose	Hata ayıklama sırasında işe yarayabilecek her türlü ek bilgi (fonksiyon çağrıları, API sorguları vb.) loglanır

Adapty yapılandırmasından önce veya yapılandırma sırasında uygulamanızda log seviyesini ayarlayabilirsiniz:

// Set log level before activation
adapty.setLogLevel({ logLevel: 'verbose' });

// Or set it during configuration
await adapty.activate({
  apiKey: 'YOUR_PUBLIC_SDK_KEY',
  params: {
    logLevel: 'verbose',
  }
});

Veri politikaları

Adapty, kullanıcılarınızın kişisel verilerini siz açıkça göndermediğiniz sürece saklamaz; ancak mağaza veya ülke yönergelerine uymak için ek veri güvenlik politikaları uygulayabilirsiniz.

IP adresi toplama ve paylaşımını devre dışı bırakma

Adapty modülünü etkinleştirirken, kullanıcı IP adresi toplama ve paylaşımını devre dışı bırakmak için ipAddressCollectionDisabled değerini true olarak ayarlayın. Varsayılan değer false’tur.

Bu parametreyi, kullanıcı gizliliğini artırmak, bölgesel veri koruma düzenlemelerine (GDPR veya CCPA gibi) uymak ya da IP tabanlı özellikler uygulamanız için gerekli değilse gereksiz veri toplamayı azaltmak amacıyla kullanabilirsiniz.

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

Reklam kimliği toplama ve paylaşımını devre dışı bırakma

Adapty modülünü etkinleştirirken, reklam tanımlayıcılarının toplanmasını devre dışı bırakmak için ios.idfaCollectionDisabled (iOS) veya android.adIdCollectionDisabled (Android) değerini true olarak ayarlayın. Varsayılan değer false’tur.

Bu parametreyi; App Store/Play Store politikalarına uymak, App Tracking Transparency istemini tetiklemekten kaçınmak veya uygulamanız reklam kimliklerine dayalı attribution ya da analitik gerektirmiyorsa kullanın.

await adapty.activate({
  apiKey: 'YOUR_PUBLIC_SDK_KEY',
  params: {
    ios: {
      idfaCollectionDisabled: true,
    },
    android: {
      adIdCollectionDisabled: true,
    },
  }
});

AdaptyUI için medya önbellek yapılandırmasını ayarlama

AdaptyUI, performansı artırmak ve ağ kullanımını azaltmak için medyayı (resimler ve videolar gibi) varsayılan olarak önbelleğe alır. Özel bir yapılandırma sağlayarak önbellek ayarlarını özelleştirebilirsiniz.

Varsayılan önbellek ayarlarını geçersiz kılmak için mediaCache kullanın:

await adapty.activate({
  apiKey: 'YOUR_PUBLIC_SDK_KEY',
  params: {
    mediaCache: {
      memoryStorageTotalCostLimit: 200 * 1024 * 1024, // Optional: memory cache size in bytes
      memoryStorageCountLimit: 2147483647,            // Optional: max number of items in memory
      diskStorageSizeLimit: 200 * 1024 * 1024,       // Optional: disk cache size in bytes
    },
  }
});

Parametre	Zorunlu	Açıklama
memoryStorageTotalCostLimit	isteğe bağlı	Bellekteki toplam önbellek boyutu (bayt cinsinden). Platform’a özgü varsayılan değer kullanılır.
memoryStorageCountLimit	isteğe bağlı	Bellek deposundaki öğe sayısı sınırı. Platform’a özgü varsayılan değer kullanılır.
diskStorageSizeLimit	isteğe bağlı	Diskteki dosya boyutu sınırı (bayt cinsinden). Platform’a özgü varsayılan değer kullanılır.

Yerel access level’ları etkinleştirin (Android)

Varsayılan olarak yerel access level’lar iOS’ta etkin, Android’de devre dışıdır. Android’de de etkinleştirmek için localAccessLevelAllowed değerini true olarak ayarlayın:

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

Yedekten geri yüklemede veriyi temizleme

clearDataOnBackup true olarak ayarlandığında, SDK uygulamanın iCloud yedeğinden geri yüklendiğini algılar ve önbelleğe alınmış profil bilgileri, ürün ayrıntıları ve paywaller dahil olmak üzere yerel olarak depolanan tüm SDK verilerini siler. Ardından SDK temiz bir durumla başlatılır. Varsayılan değer false’tur.

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

Adapty Attribution’ı Etkinleştirin

Adapty Attribution kullanıyorsanız, SDK’yı etkinleştirirken adaptyAttributionEnabled değerini true olarak ayarlayın. Varsayılan değer false’tur: bu parametre olmadan SDK, kurulumları kaydetmez veya kurulum ayrıntılarını uygulamanıza iletmez. SDK’nın 4.1’den önceki sürümlerinde Adapty Attribution otomatik olarak etkinleştirilir.

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

Geliştirme ortamı ipuçları

Capacitor’ın canlı yenileme özelliğinde SDK etkinleştirme hatalarını giderme

Capacitor’da Adapty SDK ile geliştirme yaparken şu hatayla karşılaşabilirsiniz: Adapty can only be activated once. Ensure that the SDK activation call is not made more than once.

Bu hata, Capacitor’ın canlı yenileme özelliğinin geliştirme sırasında birden fazla etkinleştirme çağrısını tetiklemesinden kaynaklanır. Bunu önlemek için __ignoreActivationOnFastRefresh seçeneğini Capacitor’ın geliştirme modu bayrağına ayarlayın; kullandığınız pakete göre bu bayrak farklılık gösterebilir.

try {
  await adapty.activate({
    apiKey: 'YOUR_PUBLIC_SDK_KEY',
    params: {
        // Set your development environment variable
      __ignoreActivationOnFastRefresh: true,
    }
  });
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
  // Handle the error appropriately for your app
}

Sorun Giderme

Minimum iOS sürümü hatası

SDK 3.x’te minimum iOS sürümü hatası alıyorsanız Podfile’ınızı güncelleyin:

-platform :ios, min_ios_version_supported
+platform :ios, '15.0'

Android yedekleme kuralları (Auto Backup yapılandırması)

Bazı SDK’lar (Adapty dahil) kendi Android Auto Backup yapılandırmalarıyla birlikte gelir. Yedekleme kuralları tanımlayan birden fazla SDK kullanıyorsanız, Android manifest birleştirici android:fullBackupContent, android:dataExtractionRules veya android:allowBackup ile ilgili bir hata vererek başarısız olabilir.

Tipik hata belirtisi: Manifest merger failed: Attribute application@dataExtractionRules value=(@xml/your_data_extraction_rules) is also present at [com.other.sdk:library:1.0.0] value=(@xml/other_sdk_data_extraction_rules)

Bu sorunu çözmek için şunları yapmanız gerekir:

• Manifest birleştiriciye, yedeklemeyle ilgili öznitelikler için uygulamanızın değerlerini kullanmasını söyleyin.

• Adapty’nin kurallarını diğer SDK’ların kurallarıyla birleştiren yedekleme kuralı dosyaları oluşturun.

1. Manifest dosyanıza tools ad alanını ekleyin

AndroidManifest.xml dosyanızda kök <manifest> etiketinin tools içerdiğinden emin olun:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.example.app">

    ...
</manifest>

2. <application> içindeki yedekleme özniteliklerini geçersiz kılın

Aynı AndroidManifest.xml dosyasında, <application> etiketini, uygulamanızın nihai değerleri sağlayacak ve manifest birleştiriciye kütüphane değerlerini değiştirmesini söyleyecek şekilde güncelleyin:

<application
android:name=".App"
android:allowBackup="true"
android:fullBackupContent="@xml/sample_backup_rules"           
android:dataExtractionRules="@xml/sample_data_extraction_rules"
tools:replace="android:fullBackupContent,android:dataExtractionRules">

    ...
</application>

Herhangi bir SDK android:allowBackup da ayarlıyorsa, bunu da tools:replace içine ekleyin:

tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules"

3. Birleştirilmiş yedekleme kuralı dosyaları oluşturun

Android projenizin res/xml/ dizininde, Adapty’nin kurallarını diğer SDK’ların kurallarıyla birleştiren XML dosyaları oluşturun. Android, işletim sistemi sürümüne bağlı olarak farklı yedekleme kuralı formatları kullandığından, her iki dosyayı da oluşturmak uygulamanızın desteklediği tüm Android sürümleriyle uyumluluğu garanti eder.

Android 12 ve üzeri için (yeni veri ayıklama kuralları formatını kullanır):

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </cloud-backup>

    <device-transfer>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </device-transfer>
</data-extraction-rules>

Android 11 ve altı için (eski tam yedekleme içeriği formatını kullanır):

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    
    <exclude domain="sharedpref" path="appsflyer-data"/>

    
    <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>

    

Android’de başka bir uygulamadan döndükten sonra satın almalar başarısız oluyor

Satın alma akışını başlatan Activity, varsayılan olmayan bir launchMode kullanıyorsa Android, kullanıcı Google Play’den, bir bankacılık uygulamasından veya tarayıcıdan döndüğünde bu Activity’yi yanlış şekilde yeniden oluşturabilir veya yeniden kullanabilir. Bu durum, satın alma sonucunun kaybolmasına ya da iptal edilmiş olarak değerlendirilmesine yol açabilir.

Satın alma işlemlerinin doğru çalışması için, satın alma akışını başlatan Activity’de yalnızca standard veya singleTop başlatma modlarını kullanın; diğer modlardan kaçının.

AndroidManifest.xml dosyanızda, satın alma akışını başlatan Activity’nin standard veya singleTop olarak ayarlandığından emin olun:

<activity
    android:name=".MainActivity"
    android:launchMode="standard" />

Podfile SWIFT_VERSION geçersiz kılmasından kaynaklanan Swift 6 derleme hataları

Capacitor uygulamanızı iOS için derlerken Adapty pod hedeflerinde Swift 6 derleme hataları görebilirsiniz. Tipik belirtiler arasında AdaptyUIBuilderLogic içinde @Sendable uyumsuzlukları, Adapty türlerinde eksik Sendable uyumu veya actor izolasyon hataları yer alır.

Adapty pod’ları s.swift_version = '6.0' olarak tanımlıdır ve derleme için Swift 6 gerektirir. Kendi uygulama kodunuz Swift 5’te kalabilir — yalnızca Adapty pod hedeflerinin (Adapty, AdaptyUI, AdaptyUIBuilder, AdaptyLogger, AdaptyPlugin) Swift 6 ile derlenmesi gerekir.

En yaygın neden, ios/App/Podfile dosyasındaki her pod hedefi için SWIFT_VERSION değerini yeniden yazan bir post_install hook’udur:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_VERSION'] = '5.9'
    end
  end
end

Düzeltme: Adapty pod hedeflerini bu geçersiz kılmanın dışında tutun:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    next if %w[Adapty AdaptyUI AdaptyUIBuilder AdaptyLogger AdaptyPlugin].include?(target.name)
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_VERSION'] = '5.9'
    end
  end
end

Ardından npx cap sync ios komutunu çalıştırın ve yeniden derleyin.

Doğrulamak için ios/App/Pods/Pods.xcodeproj dosyasını açın, Adapty pod hedefini seçin → Build Settings → Swift Language Version. Değerin Swift 6 olması gerekir.