--- title: "Установка и настройка Flutter SDK" description: "Пошаговый гайд по установке Adapty SDK на Flutter для приложений с подписками." --- Adapty SDK включает два ключевых модуля для интеграции в ваше Flutter-приложение: - **Core Adapty**: основной SDK, необходимый для работы Adapty в вашем приложении. - **AdaptyUI**: опциональный модуль, который нужен, если вы используете [Adapty Paywall Builder](adapty-paywall-builder) — удобный no-code инструмент для создания кроссплатформенных пейволов. :::tip Хотите посмотреть, как Adapty SDK интегрируется в реальное мобильное приложение? Загляните в наш [пример приложения](https://github.com/adaptyteam/AdaptySDK-Flutter/tree/master/example) — он демонстрирует полную настройку: отображение пейволов, совершение покупок и другие базовые функции. ::: ## Требования \{#requirements\} Adapty SDK поддерживает iOS 13.0+, но для корректной работы с пейволами, созданными в Paywall Builder, требуется iOS 15.0+. :::info Adapty совместим с Google Play Billing Library версий до 8.x включительно. По умолчанию Adapty работает с Google Play Billing Library v.7.0.0, но если вам нужна более поздняя версия, вы можете вручную [добавить зависимость](https://developer.android.com/google/play/billing/integrate#dependency). ::: --- no_index: true --- import Callout from '../../../components/Callout.astro'; Установка SDK — это шаг 5 настройки Adapty. Прежде чем покупки заработают в вашем приложении, вам также нужно подключить приложение к сторам, а затем создать продукты, пейвол и плейсмент в дашборде Adapty. [Гайд по быстрому старту](quickstart) описывает все необходимые шаги. ## Установка Adapty SDK \{#install-adapty-sdk\} [![Release](https://img.shields.io/github/v/release/adaptyteam/AdaptySDK-Flutter.svg?style=flat&logo=flutter)](https://github.com/adaptyteam/AdaptySDK-Flutter/releases) 1. Добавьте Adapty в файл `pubspec.yaml`: ```yaml showLineNumbers title="pubspec.yaml" dependencies: adapty_flutter: ^ ``` 2. Выполните команду для установки зависимостей: ```bash showLineNumbers title="Terminal" flutter pub get ``` 3. Импортируйте Adapty SDK в ваше приложение: ```dart showLineNumbers title="main.dart" import 'package:adapty_flutter/adapty_flutter.dart'; ``` ## Активация модуля Adapty \{#activate-adapty-module-of-adapty-sdk\} Активируйте Adapty SDK в коде вашего приложения. :::note Adapty SDK нужно активировать только один раз. ::: Чтобы получить **Public SDK Key**: 1. Откройте дашборд Adapty и перейдите в [**App settings → General**](https://app.adapty.io/settings/general). 2. В разделе **Api keys** скопируйте **Public SDK Key** (не Secret Key). 3. Замените `"YOUR_PUBLIC_SDK_KEY"` в коде на скопированный ключ. :::important - Используйте **Public SDK key** для инициализации Adapty. **Secret key** предназначен только для [серверного API](getting-started-with-server-side-api). - **SDK keys** уникальны для каждого приложения, поэтому при наличии нескольких приложений убедитесь, что выбрали правильный ключ. ::: ```dart showLineNumbers title="main.dart" void main() { runApp(MyApp()); } class MyApp extends StatefulWidget { @override _MyAppState createState() => _MyAppState(); } class _MyAppState extends State { @override void initState() { _initializeAdapty(); super.initState(); } Future _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](adapty-paywall-builder), сначала [активируйте модуль AdaptyUI](#activate-adaptyui-module-of-adapty-sdk) ниже, затем следуйте [быстрому старту с Paywall Builder](flutter-quickstart-paywalls). - Если вы создаёте собственный UI для пейвола, смотрите [быстрый старт для кастомных пейволов](flutter-quickstart-manual). ## Активация модуля AdaptyUI в Adapty SDK \{#activate-adaptyui-module-of-adapty-sdk\} Если вы планируете использовать [Paywall Builder](adapty-paywall-builder) и уже [установили модуль AdaptyUI](sdk-installation-flutter#install-adapty-sdk), вам также нужно активировать AdaptyUI: :::note Зависимости AdaptyUI подключаются к вашему приложению независимо от того, активирован AdaptyUI или нет. ::: :::important В коде необходимо активировать основной модуль Adapty раньше, чем AdaptyUI. ::: ```dart showLineNumbers title="main.dart" await Adapty().activate( configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY') ..withActivateUI(true), // This automatically activates AdaptyUI ); ``` ## Дополнительная настройка \{#optional-setup\} ### Логирование \{#logging\} #### Настройка системы логирования \{#set-up-the-logging-system\} Adapty записывает ошибки и другую важную информацию в лог, чтобы вы могли понять, что происходит в приложении. Доступны следующие уровни логирования: | Уровень | Описание | | :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | | `AdaptyLogLevel.none` | Ничего не логируется. Значение по умолчанию | | `AdaptyLogLevel.error` | Логируются только ошибки | | `AdaptyLogLevel.warn` | Логируются ошибки и сообщения SDK, которые не вызывают критических сбоев, но заслуживают внимания | | `AdaptyLogLevel.info` | Логируются ошибки, предупреждения и различные информационные сообщения | | `AdaptyLogLevel.verbose` | Логируется любая дополнительная информация, которая может быть полезна при отладке: вызовы функций, API-запросы и т. д. | Уровень логирования можно задать в приложении до настройки Adapty: ```dart showLineNumbers title="main.dart" // 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), ); ``` ### Политики работы с данными \{#data-policies\} Adapty не хранит личные данные пользователей, если вы явно их не передаёте, однако вы можете добавить дополнительные политики безопасности данных для соответствия требованиям стора или законодательства конкретной страны. #### Отключение сбора и передачи IP-адреса \{#disable-ip-address-collection-and-sharing\} При активации модуля Adapty установите `ipAddressCollectionDisabled` в `true`, чтобы отключить сбор и передачу IP-адреса пользователя. Значение по умолчанию — `false`. Используйте этот параметр для повышения конфиденциальности пользователей, соответствия региональным нормам защиты данных (например, GDPR или CCPA) или чтобы сократить сбор ненужных данных, если функции на основе IP вашему приложению не нужны. ```dart showLineNumbers title="main.dart" await Adapty().activate( configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY') ..withIpAddressCollectionDisabled(true), ); ``` #### Отключение сбора и передачи рекламного идентификатора \{#disable-advertising-id-collection-and-sharing\} При активации модуля Adapty установите `appleIdfaCollectionDisabled` (iOS) или `googleAdvertisingIdCollectionDisabled` (Android) в `true`, чтобы отключить сбор рекламных идентификаторов. Значение по умолчанию — `false`. Используйте этот параметр для соответствия политикам App Store/Play Store, чтобы избежать показа запроса App Tracking Transparency или если вашему приложению не нужна рекламная атрибуция и аналитика на основе рекламных идентификаторов. ```dart showLineNumbers title="main.dart" await Adapty().activate( configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY') ..withAppleIdfaCollectionDisabled(true) // iOS ..withGoogleAdvertisingIdCollectionDisabled(true), // Android ); ``` #### Настройка кэша медиа для AdaptyUI \{#set-up-media-cache-configuration-for-adaptyui\} Модуль активируется автоматически вместе с Adapty SDK. Если вы не используете Paywall Builder и хотите отключить модуль AdaptyUI, передайте `withActivateUI(false)` при активации. По умолчанию AdaptyUI кэширует медиафайлы (изображения и видео) для повышения производительности и снижения сетевой нагрузки. Вы можете настроить параметры кэша, передав собственную конфигурацию. Используйте `withMediaCacheConfiguration`, чтобы переопределить размер кэша и срок хранения. Это необязательно — если вы не вызываете этот метод, используются значения по умолчанию (100 МБ на диске, без ограничения по количеству элементов в памяти). Однако если вы передаёте конфигурацию, все параметры должны быть указаны. ```dart showLineNumbers title="main.dart" 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) \{#enable-local-access-levels-android\} По умолчанию [локальные уровни доступа](local-access-levels) включены на iOS и отключены на Android. Чтобы включить их и на Android, установите `withGoogleLocalAccessLevelAllowed` в `true`: ```dart showLineNumbers title="main.dart" await Adapty().activate( configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY') ..withGoogleLocalAccessLevelAllowed(true), ); ``` ### Очистка данных при восстановлении из резервной копии \{#clear-data-on-backup-restore\} Если `clearDataOnBackup` установлен в `true`, SDK определяет, что приложение восстановлено из резервной копии iCloud, и удаляет все локально сохранённые данные SDK: кэш профиля, информацию о продуктах и пейволы. После этого SDK инициализируется с чистого состояния. Значение по умолчанию — `false`. :::note Удаляется только локальный кэш SDK. История транзакций у Apple и данные пользователя на серверах Adapty остаются без изменений. ::: ```dart showLineNumbers title="main.dart" await Adapty().activate( configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY') ..withClearDataOnBackup(true) // default – false ); ``` ## Устранение неполадок \{#troubleshooting\} #### Правила резервного копирования Android (настройка Auto Backup) \{#android-backup-rules-auto-backup-configuration\} Некоторые 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)` :::note Эти изменения нужно вносить в директорию Android-платформы (обычно находится в папке `android/` вашего проекта). ::: Чтобы решить проблему, необходимо: - Указать механизму слияния манифестов использовать значения вашего приложения для атрибутов, связанных с резервным копированием. - Создать файлы правил резервного копирования, объединяющие правила Adapty с правилами других SDK. #### 1. Добавьте пространство имён `tools` в манифест В файле `AndroidManifest.xml` убедитесь, что корневой тег `` включает tools: ```xml ... ``` #### 2. Переопределите атрибуты резервного копирования в `` В том же файле `AndroidManifest.xml` обновите тег ``, чтобы ваше приложение предоставляло итоговые значения и указывало механизму слияния манифестов заменять значения библиотек: ```xml ... ``` Если какой-либо SDK также задаёт `android:allowBackup`, включите его в `tools:replace`: ```xml tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules" ``` #### 3. Создайте объединённые файлы правил резервного копирования Создайте XML-файлы в директории `res/xml/` вашего Android-проекта, объединяющие правила Adapty с правилами других SDK. Android использует разные форматы правил резервного копирования в зависимости от версии ОС, поэтому создание обоих файлов обеспечивает совместимость со всеми версиями Android, которые поддерживает ваше приложение. :::note В примерах ниже в качестве стороннего SDK используется AppsFlyer. Замените или добавьте правила для других SDK, которые используются в вашем приложении. ::: **Для Android 12 и выше** (используется новый формат правил извлечения данных): ```xml title="sample_data_extraction_rules.xml" ``` **Для Android 11 и ниже** (используется устаревший формат полного резервного копирования): ```xml title="sample_backup_rules.xml" #### Покупки прерываются после возврата из другого приложения на Android \{#purchases-fail-after-returning-from-another-app-in-android\} Если Activity, запускающий процесс покупки, использует нестандартный `launchMode`, Android может некорректно пересоздать или повторно использовать его при возврате пользователя из Google Play, банковского приложения или браузера. Это может привести к тому, что результат покупки будет утерян или расценён как отменённый. Чтобы покупки работали корректно, используйте только режимы запуска `standard` или `singleTop` для Activity, запускающего процесс покупки, и избегайте любых других режимов. В файле `AndroidManifest.xml` убедитесь, что Activity, которая запускает процесс покупки, имеет режим `standard` или `singleTop`: ```xml ``` #### Ошибки сборки Swift 6, вызванные переопределением SWIFT_VERSION в Podfile \{#swift-6-build-errors-caused-by-podfile-swift-version-override\} При сборке 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` для каждого пода: ```ruby showLineNumbers title="ios/Podfile" 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 из переопределения: ```ruby showLineNumbers title="ios/Podfile" 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**.