SDK Adapty включает два ключевых модуля для интеграции в ваше приложение на Capacitor:

• Core Adapty: Этот модуль необходим для корректной работы Adapty в вашем приложении.
• AdaptyUI: Этот модуль нужен, если вы используете Adapty Paywall Builder — удобный инструмент без кода для создания кросс-платформенных пейволов. AdaptyUI активируется автоматически вместе с основным модулем.

Требования

Adapty Capacitor SDK имеет следующие требования к версиям:

Версия Adapty SDK	Версия Capacitor	Версия iOS
3.16.0+	8	15.0+
3.15	7	14.0+

Capacitor версии 6 и ниже не поддерживается. Для сборки под iOS с Adapty SDK v4 (beta) требуется Xcode 26 или новее — нативный iOS SDK использует Swift tools 6.2. Требования к iOS 15.0+, Capacitor 8 и Android minSdk 24 такие же, как для SDK 3.16+.

Установка Adapty SDK

Установите Adapty SDK:

npm install @adapty/capacitor
npx cap sync

Adapty SDK 4.0 (beta)

Capacitor SDK 4.0 — который добавляет поддержку Flow Builder — является предрелизной версией. Установите точную версию (npm не разрешает предрелизы через диапазоны с ^/~), затем выполните синхронизацию:

npm install @adapty/capacitor@4.0.0-beta.2

npx cap sync

На iOS v4 подтягивает нативные SDK Adapty через Swift Package Manager — podspec для CocoaPods был удалён (репозиторий спецификаций CocoaPods станет доступен только для чтения в декабре 2026 года). iOS-проект вашего приложения должен использовать SPM-интеграцию Capacitor:

• Для новых приложений добавьте платформу iOS с менеджером пакетов SPM:

  npx cap add ios --packagemanager SPM

• Для существующих приложений перенесите iOS-проект с CocoaPods на SPM, следуя руководству Capacitor по использованию SPM в существующем проекте.

Полный список изменений API в v4 см. в разделе Миграция Adapty Capacitor SDK на v4.

Активация модуля Adapty в SDK Adapty

Чтобы получить Public SDK Key:

1. Откройте дашборд Adapty и перейдите в App settings → General.
2. В разделе Api keys скопируйте Public SDK Key (НЕ Secret Key).
3. Замените "YOUR_PUBLIC_SDK_KEY" в коде.

Или получите его программно с помощью Adapty CLI:

npm install -g adapty
adapty auth login
adapty apps list

Или напрямую:

npx adapty auth login
adapty apps list

• Убедитесь, что для инициализации Adapty вы используете Public SDK key — Secret key предназначен только для серверного API.
• SDK-ключи уникальны для каждого приложения, поэтому если у вас несколько приложений, выберите нужный ключ.

Скопируйте следующий код в любой файл приложения для активации Adapty:

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);
}

Теперь настройте пейволы в своём приложении:

• Если вы используете Adapty Paywall Builder, следуйте быстрому старту с Paywall Builder.
• Если вы создаёте собственный UI пейвола, смотрите быстрый старт для кастомных пейволов.

Активация модуля AdaptyUI

Если вы планируете использовать Paywall Builder, вам понадобится модуль AdaptyUI. Он активируется автоматически при активации основного модуля — дополнительных действий не требуется.

Опциональная настройка

Логирование

Настройка системы логирования

Adapty записывает ошибки и другую важную информацию, чтобы вы понимали, что происходит. Доступны следующие уровни логирования:

Level	Description
error	Будут записываться только ошибки
warn	Будут записываться ошибки и сообщения от SDK, которые не вызывают критических ошибок, но заслуживают внимания
info	Будут записываться ошибки, предупреждения и различные информационные сообщения
verbose	Будет записываться любая дополнительная информация, которая может быть полезна при отладке: вызовы функций, запросы к API и т. д.
Вы можете установить уровень логирования в приложении до или во время конфигурации Adapty:

// 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',
  }
});

Политики обработки данных

Adapty не хранит персональные данные ваших пользователей, если вы явно их не передаёте, но вы можете настроить дополнительные политики безопасности данных в соответствии с требованиями стора или законодательства конкретной страны.

Отключение сбора и передачи IP-адресов

При активации модуля Adapty установите ipAddressCollectionDisabled в значение true, чтобы отключить сбор и передачу IP-адресов пользователей. Значение по умолчанию — false. Используйте этот параметр для защиты конфиденциальности пользователей, соблюдения региональных требований по защите данных (например, GDPR или CCPA) или уменьшения объёма собираемых данных, если функции на основе IP-адреса не нужны вашему приложению.

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

Отключение сбора и передачи рекламного идентификатора

При активации модуля Adapty установите ios.idfaCollectionDisabled (iOS) или android.adIdCollectionDisabled (Android) в значение true, чтобы отключить сбор рекламных идентификаторов. По умолчанию используется значение false.

Используйте этот параметр для соответствия политикам App Store/Play Store, чтобы не вызывать запрос App Tracking Transparency, или если ваше приложение не использует рекламную атрибуцию или аналитику на основе рекламных идентификаторов.

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

Настройка конфигурации кэша медиа для AdaptyUI

По умолчанию AdaptyUI кэширует медиафайлы (изображения и видео) для повышения производительности и снижения нагрузки на сеть. Вы можете настроить параметры кэша, предоставив собственную конфигурацию.

Используйте mediaCache для переопределения настроек кэша по умолчанию:

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
    },
  }
});

Параметр	Обязательный	Описание
memoryStorageTotalCostLimit	нет	Общий размер кэша в памяти в байтах. По умолчанию используется платформенное значение.
memoryStorageCountLimit	нет	Максимальное количество элементов в памяти. По умолчанию используется платформенное значение.
diskStorageSizeLimit	нет	Максимальный размер файла на диске в байтах. По умолчанию используется платформенное значение.

Включение локальных уровней доступа (Android)

По умолчанию локальные уровни доступа включены на iOS и отключены на Android. Чтобы включить их и на Android, установите localAccessLevelAllowed в true:

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

Очистка данных при восстановлении из резервной копии

Если для clearDataOnBackup установлено значение true, SDK определяет, что приложение было восстановлено из резервной копии iCloud, и удаляет все локально сохранённые данные SDK, включая кэшированную информацию профиля, сведения о продуктах и пейволах. После этого SDK инициализируется с чистого состояния. Значение по умолчанию — false.

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

Советы по среде разработки

Устранение ошибок активации SDK при live-reload в Capacitor

При разработке с Adapty SDK в Capacitor вы можете столкнуться с ошибкой: Adapty can only be activated once. Ensure that the SDK activation call is not made more than once.

Она возникает из-за того, что функция live-reload в Capacitor инициирует несколько вызовов активации в процессе разработки. Чтобы этого избежать, используйте опцию __ignoreActivationOnFastRefresh, установив её в флаг режима разработки Capacitor — он будет отличаться в зависимости от используемого бандла.

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
}

Устранение неполадок

Ошибка минимальной версии iOS

Если при использовании SDK 3.x возникает ошибка минимальной версии iOS, обновите Podfile:

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

Правила резервного копирования Android (настройка Auto Backup)

Некоторые SDK (включая Adapty) поставляются с собственной конфигурацией Android Auto Backup. Если вы используете несколько SDK, каждый из которых определяет правила резервного копирования, слияние манифестов Android может завершиться ошибкой, связанной с android:fullBackupContent, android:dataExtractionRules или android:allowBackup.

Типичные симптомы ошибки: 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)

Чтобы решить проблему, необходимо:

• Указать механизму слияния манифестов использовать значения вашего приложения для атрибутов, связанных с резервным копированием.

• Создать файлы правил резервного копирования, объединяющие правила Adapty с правилами других SDK.

1. Добавьте пространство имён tools в манифест

В файле AndroidManifest.xml убедитесь, что корневой тег <manifest> включает tools:

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

    ...
</manifest>

2. Переопределите атрибуты резервного копирования в <application>

В том же файле AndroidManifest.xml обновите тег <application>, чтобы ваше приложение предоставляло итоговые значения и указывало механизму слияния манифестов заменять значения библиотек:

<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>

Если какой-либо SDK также задаёт android:allowBackup, включите его в tools:replace:

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

3. Создайте объединённые файлы правил резервного копирования

Создайте XML-файлы в директории res/xml/ вашего Android-проекта, объединяющие правила Adapty с правилами других SDK. Android использует разные форматы правил резервного копирования в зависимости от версии ОС, поэтому создание обоих файлов обеспечивает совместимость со всеми версиями Android, которые поддерживает ваше приложение.

Для Android 12 и выше (используется новый формат правил извлечения данных):

<?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 и ниже (используется устаревший формат полного резервного копирования):

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

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

    

Покупки завершаются с ошибкой после возврата из другого приложения на Android

Если Activity, запускающий флоу покупки, использует нестандартный launchMode, Android может некорректно пересоздать или повторно использовать его при возврате пользователя из Google Play, банковского приложения или браузера. Это может привести к тому, что результат покупки будет потерян или воспринят как отмена. Чтобы покупки работали корректно, используйте только режимы запуска standard или singleTop для Activity, из которой запускается флоу покупки, и избегайте любых других режимов.

В файле AndroidManifest.xml убедитесь, что для Activity, запускающей флоу покупки, задан режим standard или singleTop:

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

Ошибки сборки Swift 6, вызванные переопределением SWIFT_VERSION в Podfile

При сборке Capacitor-приложения для iOS вы можете столкнуться с ошибками компиляции Swift 6 в pod-таргетах Adapty. Типичные симптомы: несоответствия @Sendable в AdaptyUIBuilderLogic, отсутствие соответствия Sendable у типов Adapty или ошибки изоляции акторов. Поды Adapty объявляют s.swift_version = '6.0' и требуют Swift 6 для сборки. Ваш собственный код приложения может оставаться на Swift 5 — только целевые поды Adapty (Adapty, AdaptyUI, AdaptyUIBuilder, AdaptyLogger, AdaptyPlugin) должны собираться с Swift 6.

Наиболее распространённая причина — хук post_install в ios/App/Podfile, который перезаписывает SWIFT_VERSION для каждого пода:

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

Исправление: Исключите pod-таргеты Adapty из переопределения:

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

Затем выполните npx cap sync ios и пересоберите проект.

Чтобы проверить результат, откройте ios/App/Pods/Pods.xcodeproj, выберите таргет пода Adapty → Build Settings → Swift Language Version. Там должно быть указано Swift 6.