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

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

Требования

Adapty SDK поддерживает iOS 13.0+, но для корректной работы пейволов, созданных в Paywall Builder, требуется iOS 15.0+.

Adapty Flutter SDK 4.0 — с поддержкой Flow Builder — повышает минимальные требования до iOS 15.0+, Xcode 26+ и Flutter 3.32.0+ (Dart 3.8.0+). Подробности об установке см. в разделе Adapty SDK 4.0 ниже.

Установка Adapty SDK

1. Добавьте Adapty в файл pubspec.yaml:

   dependencies: 
     adapty_flutter: ^<the latest SDK version>

2. Выполните следующую команду для установки зависимостей:

   flutter pub get

3. Импортируйте Adapty SDK в своё приложение:

   import 'package:adapty_flutter/adapty_flutter.dart';

Adapty SDK 4.0: Swift Package Manager

Добавьте Adapty Flutter SDK 4.0 — который добавляет поддержку Flow Builder — в ваш pubspec.yaml:

dependencies:
  adapty_flutter: 4.0.0

Начиная с v4, нативный iOS SDK больше не распространяется через CocoaPods — плагин подключает его только через Swift Package Manager (репозиторий спецификаций CocoaPods переходит в режим только для чтения в декабре 2026 года). Если вы используете Flutter 3.32–3.43, включите поддержку Swift Package Manager один раз:

flutter config --enable-swift-package-manager

Flutter 3.44 и более поздние версии включают Swift Package Manager по умолчанию, поэтому никаких дополнительных действий не требуется.

Об изменениях API в v4 читайте в руководстве по миграции.

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

Активируйте Adapty SDK в коде вашего приложения.

Чтобы получить 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-ключи уникальны для каждого приложения, поэтому если у вас несколько приложений, выберите нужный ключ.

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    _initializeAdapty();

    super.initState();
  }

  Future<void> _initializeAdapty() async {
    try {
      await Adapty().activate(
        configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY'),
      );
    } catch (e) {
      // handle the error
    }
  }

  Widget build(BuildContext context) {
    return Text("Hello");
  }
}

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

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

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

Если вы планируете использовать Paywall Builder и уже установили модуль AdaptyUI, его также необходимо активировать:

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withActivateUI(true), // This automatically activates AdaptyUI
);

Необязательная настройка

Логирование

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

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

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

// Set log level before activation. 
// 'verbose' is recommended for development and the first production release
await Adapty().setLogLevel(AdaptyLogLevel.verbose);

// Or set it during configuration
await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withLogLevel(AdaptyLogLevel.verbose),
);

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

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

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

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

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withIpAddressCollectionDisabled(true),
);

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

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

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

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withAppleIdfaCollectionDisabled(true)      // iOS
    ..withGoogleAdvertisingIdCollectionDisabled(true), // Android
);

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

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

Используйте withMediaCacheConfiguration, чтобы переопределить ограничения кэша по умолчанию. Это необязательно — если вы не вызываете этот метод, будут применяться значения по умолчанию (100 МБ на диске, неограниченное количество объектов в памяти). Однако если вы создаёте объект конфигурации, все его параметры обязательны.

final mediaCacheConfig = AdaptyUIMediaCacheConfiguration(
  memoryStorageTotalCostLimit: 200 * 1024 * 1024, // 200 MB
  memoryStorageCountLimit: 2147483647, // max int value
  diskStorageSizeLimit: 200 * 1024 * 1024, // 200 MB
);

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withMediaCacheConfiguration(mediaCacheConfig),
);

Параметры:

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

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

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

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withGoogleLocalAccessLevelAllowed(true),
);

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

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

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withAppleClearDataOnBackup(true) // default – false
);

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

Правила резервного копирования 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

При сборке Flutter-приложения для iOS могут появляться ошибки компиляции Swift 6 в целевых объектах пода 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/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

Затем выполните pod install из директории ios/ и пересоберите проект.

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