Миграция Adapty Flutter SDK на версию 4.0

Adapty Flutter SDK 4.0 вводит флоу и соответственно переименовывает paywall API. Новые API работают как с новым Flow Builder, так и с существующим Paywall Builder — никаких изменений в настройках дашборда Adapty не требуется.

Краткий справочник

v3	v4
`Adapty().getPaywall(placementId: id)`	`Adapty().getFlow(placementId: id)`
`Adapty().getPaywallForDefaultAudience(placementId: id)`	`Adapty().getFlowForDefaultAudience(placementId: id)`
`Adapty().getPaywallProducts(paywall: paywall)`	`Adapty().getPaywallProducts(flow: flow)`
`Adapty().logShowPaywall(paywall: paywall)`	`Adapty().logShowFlow(flow: flow)`
`AdaptyPaywall` (тип)	`AdaptyFlow`
`AdaptyPaywallFetchPolicy` (тип)	`AdaptyFlowFetchPolicy`
`AdaptyUI().createPaywallView(paywall: paywall)`	`AdaptyUI().createFlowView(flow: flow)`
`AdaptyUIPaywallView` (тип)	`AdaptyUIFlowView`
`AdaptyUIPaywallPlatformView` (виджет)	`AdaptyUIFlowPlatformView`
`AdaptyUI().presentPaywallView(view)` / `dismissPaywallView(view)`	`AdaptyUI().presentFlowView(view)` / `dismissFlowView(view)`
`AdaptyUIPaywallsEventsObserver`	`AdaptyUIFlowsEventsObserver`
`AdaptyUI().setPaywallsEventsObserver(observer)`	`AdaptyUI().setFlowsEventsObserver(observer)`
Колбэки `paywallViewDid*`	Колбэки `flowViewDid*`
`paywallViewDidFailRendering`	`flowViewDidReceiveError`
`AdaptyPaywallProduct` сохраняет своё название — продукты по-прежнему принадлежат флоу, а `getPaywallProducts` теперь принимает `AdaptyFlow`. При получении флоу больше не нужно передавать `locale`. API для покупок и профиля (`makePurchase`, `restorePurchases`, `getProfile`, `identify` и т. д.) остался без изменений, как и методы работы с представлениями `present`, `dismiss` и `showDialog`. Часть поведения по умолчанию изменилась — см. Изменения поведения по умолчанию.

Минимальные требования

Adapty Flutter SDK 4.0 повышает минимальные требования:

iOS 15.0 — минимальная цель развёртывания iOS, повышена с iOS 13.0.
Xcode 26 или новее — нативный iOS SDK использует Swift tools 6.2.
Flutter 3.32.0 (Dart 3.8.0) или новее.

Установка

Обновите пакет

Какой пакет устанавливать, зависит от того, используется ли в вашем приложении Kids Mode.

Для большинства приложений обновите adapty_flutter до версии 4.0 в файле pubspec.yaml:

dependencies:
  adapty_flutter: 4.0.0

Если ваше приложение использует Kids Mode, укажите вместо него adapty_flutter_kids:

dependencies:
  adapty_flutter_kids: 4.0.0

Этот автономный пакет удаляет IDFA и код отслеживания рекламы для соответствия требованиям App Store. Обновите путь импорта Dart на package:adapty_flutter_kids/adapty_flutter.dart. В остальном миграция полностью идентична обычному пакету.

Kids Mode также требует отключения сбора IP-адресов в дашборде Adapty — полную инструкцию по настройке см. в разделе Kids Mode.

iOS: нативные SDK теперь поставляются через Swift Package Manager

Репозиторий спецификаций CocoaPods становится доступным только для чтения в декабре 2026 года, поэтому начиная с v4 нативный iOS SDK больше не распространяется через CocoaPods — плагин получает его только через Swift Package Manager.

Если вы используете Flutter 3.32–3.43, один раз включите поддержку Swift Package Manager:

flutter config --enable-swift-package-manager

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

Получение флоу

getPaywall → getFlow

Возвращаемый тип меняется с AdaptyPaywall на AdaptyFlow, и теперь не нужно передавать locale — при отображении флоу локализация определяется автоматически; для кастомных пейволов все настроенные локали возвращаются в flow.remoteConfigs:

- final paywall = await Adapty().getPaywall(placementId: 'YOUR_PLACEMENT_ID', locale: 'en');
+ final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');

getPaywallForDefaultAudience переименовывается аналогично:

- final paywall = await Adapty().getPaywallForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID', locale: 'en');
+ final flow = await Adapty().getFlowForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');

Тип политики загрузки переименован с AdaptyPaywallFetchPolicy на AdaptyFlowFetchPolicy; его варианты (reloadRevalidatingCacheData, returnCacheDataElseLoad, returnCacheDataIfNotExpiredElseLoad) остались без изменений.

getPaywallProducts(paywall) → getPaywallProducts(flow)

getPaywallProducts сохраняет своё название, но теперь принимает AdaptyFlow через параметр flow:

- final products = await Adapty().getPaywallProducts(paywall: paywall);
+ final products = await Adapty().getPaywallProducts(flow: flow);

Модель данных

getFlow возвращает AdaptyFlow вместо AdaptyPaywall, и структура объекта изменилась:

Член `AdaptyPaywall` v3	Член `AdaptyFlow` v4	Действие
`remoteConfig` (один, nullable)	`remoteConfigs` (список)	Флоу хранит один Remote Config на каждый настроенный язык. Геттер `remoteConfig` по-прежнему существует и возвращает первую запись; чтобы выбрать конкретный язык, найдите нужную запись в `remoteConfigs` по полю `locale`.
`productIdentifiers`	`productIdentifiers`	Сохранён, но теперь объединяет идентификаторы из всех вариаций пейволов флоу. Идентификаторы для каждой вариации доступны через `flow.paywalls[i].productIdentifiers`.
`hasViewConfiguration`	`hasViewConfiguration`	Без изменений.
`placementId` (устарело)	удалён	Используйте `flow.placement.id`.
`revision` (устарело)	удалён	Используйте `flow.placement.revision`.
`vendorProductIds` (устарело)	удалён	Используйте `productIdentifiers`.
(новое)	`paywalls` (список `AdaptyFlowPaywall`)	Каждый элемент — одна вариация пейвола во флоу со своими `name`, `variationId` и `productIdentifiers`.
`AdaptyPaywallViewConfiguration` больше не предоставляется публично — конфигурация представления теперь непрозрачна. Удалите все ссылки на этот тип.

Методы веб-пейвола

openWebPaywall и createWebPaywallUrl сохраняют свои названия, но параметр paywall теперь принимает AdaptyFlowPaywall (вариант флоу) вместо AdaptyPaywall. По-прежнему можно передать AdaptyPaywallProduct.

  final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');
- await Adapty().openWebPaywall(paywall: paywall);
+ if (flow.paywalls.isNotEmpty) {
+   await Adapty().openWebPaywall(paywall: flow.paywalls[0]);
+ }

Отслеживание просмотров флоу

logShowPaywall → logShowFlow

logShowPaywall переименован в logShowFlow и теперь принимает AdaptyFlow. Событие по-прежнему фиксируется для той же вариации, поэтому существующие метрики воронки и A/B-тестов продолжают работать без изменений в дашборде.

- await Adapty().logShowPaywall(paywall: paywall);
+ await Adapty().logShowFlow(flow: flow);

Как и в v3, вызывать этот метод при отображении флоу или пейволов, отрисованных с помощью Flow Builder или Paywall Builder, не нужно — Adapty отслеживает эти просмотры автоматически.

Отображение флоу

createPaywallView → createFlowView

Переименуйте метод и передайте AdaptyFlow через параметр flow. Остальные параметры (loadTimeout, preloadProducts, customTags, customTimers, customAssets, productPurchaseParams) остаются без изменений, как и методы представления present, dismiss и showDialog:

- final view = await AdaptyUI().createPaywallView(paywall: paywall);
+ final view = await AdaptyUI().createFlowView(flow: flow);
  await view.present();

AdaptyUIPaywallView → AdaptyUIFlowView

Тип представления переименован. Устаревшее свойство paywallVariationId удалено — используйте variationId:

- void flowViewDidAppear(AdaptyUIPaywallView view) {
+ void flowViewDidAppear(AdaptyUIFlowView view) {

AdaptyUIPaywallPlatformView → AdaptyUIFlowPlatformView

Если вы встраиваете представление как виджет в дерево виджетов, переименуйте его и передайте параметр flow. Колбэки событий (onDidAppear, onDidFinishPurchase и так далее) сохраняют свои названия:

- AdaptyUIPaywallPlatformView(
-   paywall: paywall,
+ AdaptyUIFlowPlatformView(
+   flow: flow,
    onDidFinishPurchase: (view, product, purchaseResult) { /* … */ },
  )

Представление флоу, созданное с помощью createFlowView, одноразовое: после вызова dismiss() оно освобождается из памяти и не может быть показано повторно — вызовите createFlowView снова, чтобы отобразить флоу ещё раз.

Обработка событий

Класс-наблюдатель переименован с AdaptyUIPaywallsEventsObserver на AdaptyUIFlowsEventsObserver, метод его регистрации — с setPaywallsEventsObserver на setFlowsEventsObserver, а все колбэки paywallViewDid* — на flowViewDid*:

- class MyObserver extends AdaptyUIPaywallsEventsObserver {
+ class MyObserver extends AdaptyUIFlowsEventsObserver {
    @override
-   void paywallViewDidPerformAction(AdaptyUIPaywallView view, AdaptyUIAction action) {
+   void flowViewDidPerformAction(AdaptyUIFlowView view, AdaptyUIAction action) {
      // …
    }
  }

- AdaptyUI().setPaywallsEventsObserver(this);
+ AdaptyUI().setFlowsEventsObserver(this);

Три коллбэка теперь обязательны — без них наблюдатель не скомпилируется:

flowViewDidFinishPurchase: В v3 был опциональным — по умолчанию закрывал вью после покупки. Теперь вы сами решаете, что произойдёт: продолжить флоу или вызвать view.dismiss().
flowViewDidFinishRestore: Обязательный, как и в v3.
flowViewDidReceiveError: Заменяет paywallViewDidFailRendering и теперь также получает другие ошибки вью.

Два небольших изменения:

setFlowsEventsObserver (и setOnboardingsEventsObserver) теперь принимают null, чтобы отвязать ранее установленный наблюдатель — SDK больше не удерживает его.
Новый необязательный коллбэк flowViewDidReceiveAnalyticEvent зарезервирован для пользовательских аналитических событий из флоу. Флоу пока не отправляют их в ваш код, поэтому реализовывать его не нужно.

В v4 также появились возможности, которые можно подключить по желанию:

AdaptyUI().setObserverModeResolver(...) с AdaptyUIObserverModeResolver — управляет покупками и восстановлениями, инициированными из флоу, когда SDK работает в режиме Observer. Ранее это было доступно только в нативных SDK для iOS и Android. См. Показ флоу в режиме Observer.
AdaptyUI().setSystemRequestsHandler(...) с AdaptyUISystemRequestsHandler — зарезервировано для системных запросов из флоу (запросы разрешений ОС и запросы на отзыв в App Store). Флоу пока не инициируют такие запросы, поэтому регистрировать обработчик не нужно.

Удалённые API

Эти символы были помечены как устаревшие в версии 3.x и удалены в v4:

setFallbackPaywalls → setFallback

- await Adapty().setFallbackPaywalls(assetId);
+ await Adapty().setFallback(assetId);

withIdfaCollectionDisabled → withAppleIdfaCollectionDisabled

  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
-   ..withIdfaCollectionDisabled(true),
+   ..withAppleIdfaCollectionDisabled(true),

Другие удалённые элементы

AdaptyPurchaseResultSuccess.jwsTransaction: Используйте appleJwsTransaction.
AdaptyUIFlowView.paywallVariationId: Используйте variationId.
AdaptyUIObserver и AdaptyUI().setObserver(...): Используйте AdaptyUIFlowsEventsObserver и setFlowsEventsObserver(...).

Изменения поведения по умолчанию

Эти изменения не вызывают ошибок компиляции, поэтому проверяйте их во время выполнения:

Успешная покупка: В v3 дефолтный paywallViewDidFinishPurchase закрывал экран. В v4 flowViewDidFinishPurchase обязателен и не имеет реализации по умолчанию — закрывайте экран самостоятельно, если хотите такого поведения.
Системная кнопка «Назад» на Android: Она больше не закрывает флоу по умолчанию. Действие передаётся в flowViewDidPerformAction как AndroidSystemBackAction — обработайте его там, если хотите, чтобы кнопка «Назад» закрывала флоу.
Открытие URL: Дефолтный flowViewDidPerformAction теперь обрабатывает OpenUrlAction, открывая URL нативно (с учётом настройки встроенного или внешнего браузера из дашборда), а также закрывает экран по CloseAction. Переопределите коллбэк, чтобы обрабатывать URL самостоятельно.
Ошибки экрана: flowViewDidReceiveError обязателен, и закрытие экрана зависит от вашей реализации. Если в v3 ваша интеграция рассчитывала на автоматическое закрытие при ошибках рендеринга, вызывайте view.dismiss() в этом коллбэке.
Жизненный цикл экрана: Закрытие флоу или онбординга освобождает его из памяти. Закрытый экран нельзя показать повторно — создайте новый.

Устаревший API онбординга

Устаревший API онбординга объявлен устаревшим в v4.0 в пользу Flow Builder. Он по-прежнему работает, а IDE помечает устаревшие символы через аннотации @Deprecated — никаких предупреждений во время выполнения нет. Эти символы будут удалены в одном из следующих релизов, поэтому планируйте переход ваших онбордингов на Flow Builder. Устаревшие символы: getOnboarding, getOnboardingForDefaultAudience, createOnboardingView, presentOnboardingView, dismissOnboardingView, setOnboardingsEventsObserver, AdaptyOnboarding, AdaptyUIOnboardingView, AdaptyUIOnboardingPlatformView, AdaptyUIOnboardingsEventsObserver, а также модели состояния, ввода и аналитики онбординга.