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

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

Требования

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

Установка Adapty SDK

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

   dependencies: 
     adapty_flutter: ^<the latest SDK version>

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

   flutter pub get

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

   import 'package:adapty_flutter/adapty_flutter.dart';

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

Активируйте 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, вам также нужно активировать AdaptyUI:

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

Дополнительная настройка

Логирование

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

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

Уровень	Описание
AdaptyLogLevel.none	Ничего не логируется. Значение по умолчанию
AdaptyLogLevel.error	Логируются только ошибки
AdaptyLogLevel.warn	Логируются ошибки и сообщения от SDK, которые не вызывают критических ошибок, но заслуживают внимания.
AdaptyLogLevel.info	Логируются ошибки, предупреждения и различные информационные сообщения.
AdaptyLogLevel.verbose	Логируется любая дополнительная информация, которая может быть полезна при отладке: вызовы функций, запросы к API и т. д.
Вы можете задать уровень логирования в вашем приложении до настройки 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),
);

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

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

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withClearDataOnBackup(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 в 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/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, выберите pod-таргет Adapty → Build Settings → Swift Language Version. Там должно быть указано Swift 6.