Переход на Adapty Flutter SDK v4.1

Adapty Flutter SDK 4.1 изменяет способ включения Adapty Attribution, переименовывает API внешней атрибуции и меняет формат резервного файла. Кроме того, он передаёт продвигаемые встроенные покупки App Store вашему приложению и добавляет возможность сохранять флоу-экран активным после закрытия.

Если вы ещё на 3.x, начните с Миграции на v4.0, а затем следуйте этому руководству.

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

API покупок, профилей и отображения флоу не претерпели изменений.

Установка

Обновите adapty_flutter до v4.1 в вашем pubspec.yaml:

dependencies:
  adapty_flutter: 4.1.0

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

dependencies:
  adapty_flutter_kids: 4.1.0

Требования не изменились по сравнению с 4.0: Flutter 3.32.0 (Dart 3.8.0) и iOS 15.0. Подробную информацию об установке см. в разделе Установка Adapty SDK.

4.1 фиксирует версию нативного iOS SDK на 4.1.3, а нативного Android SDK — на 4.1.1. В iOS-релизе также исправлена передача числовых параметров в аналитических событиях флоу: ранее каждое значение 0 и 1 приходило в flowViewDidReceiveAnalyticEvent как false и true.

⚠️ Атрибуция Adapty отключена по умолчанию

Начиная с версии 4.0 и ранее, SDK автоматически регистрировал установки для Атрибуции Adapty. Начиная с версии 4.1, это отключено по умолчанию: SDK не регистрирует установки, onUpdateInstallationDetailsSuccessStream и onUpdateInstallationDetailsFailStream никогда не генерируют события, а getCurrentInstallationStatus возвращает AdaptyInstallationStatusNotAvailable.

Если вы используете атрибуцию Adapty, включите её при настройке SDK:

  await Adapty().activate(
-   configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY'),
+   configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
+     ..withAdaptyAttributionEnabled(true),
  );

Если вы не используете Adapty Attribution, никаких изменений не требуется.

Переименованные внешние API атрибуции

API, передающие данные атрибуции от внешнего провайдера (Adjust, AppsFlyer, Branch, Tenjin или другого), переименованы в соответствии с нативными SDK.

updateAttribution → updateExternalAttribution

Метод переименован, а его параметр source переименован в provider. Теперь параметр принимает AdaptyExternalAttributionProvider вместо строки, данные атрибуции по-прежнему передаются в виде map:

- await Adapty().updateAttribution(attribution, source: 'adjust');
+ await Adapty().updateExternalAttribution(attribution, provider: AdaptyExternalAttributionProvider.adjust);

AdaptyAttributionSource → AdaptyExternalAttributionProvider

Тип провайдера переименован. Он по-прежнему является открытой обёрткой над строкой — предустановленные значения: appleAds, adjust, appsflyer, branch, tenjin, а также новое custom для провайдеров, с которыми Adapty не интегрируется напрямую. Можно создать значение из любой произвольной строки, поэтому провайдер, добавленный в Adapty позже, будет работать без обновления SDK:

final provider = AdaptyExternalAttributionProvider('my_provider');

AdaptyProfile.appliedAttributionSources → appliedExternalAttributionProviders

Свойство профиля, перечисляющее провайдеров атрибуции, применённых к профилю, переименовано, и тип его элементов изменён соответствующим образом:

- if (profile.appliedAttributionSources.contains(AdaptyAttributionSource.appleAds)) {
+ if (profile.appliedExternalAttributionProviders.contains(AdaptyExternalAttributionProvider.appleAds)) {
      // Apple Ads attribution has been applied
  }

Сериализованное поле профиля по-прежнему называется applied_attribution_sources, поэтому бэкенду, читающему сырой профиль, изменения не нужны. Код, читающий это свойство, придётся обновить — подробнее см. Показ пейвола с таргетингом Apple Ads.

Резервные файлы

Формат резервного файла изменился в SDK 4.1. Скачайте файл повторно из Placements > Fallbacks и добавьте его в приложение, даже если вы уже скачивали его для версии 4.0.

⚠️ Продвигаемые встроенные покупки теперь ждут вашего приложения

В версии 4.0 Adapty записывал продвигаемую покупку как обычную транзакцию, и ваше приложение не могло её перехватить. В версии 4.1 управление передаётся приложению, и вместе с ним — ответственность за завершение покупки.

Подпишитесь на didReceivePromotedPurchaseStream и передайте продукт в makePromotedPurchase:

Adapty().didReceivePromotedPurchaseStream.listen((product) async {
  try {
    final result = await Adapty().makePromotedPurchase(product: product);
    // process the purchase result
  } on AdaptyError catch (e) {
    // handle the error
  }
});

Подпишитесь на события до того, как может поступить продвигаемая покупка — при запуске приложения, сразу после activate. Это широковещательный поток без воспроизведения: продукт, доставленный, когда никто не слушает, будет потерян вместе с покупкой.

makePromotedPurchase не принимает параметры покупки, поскольку продвигаемый продукт поступает из App Store, а не с пейвола, и не несёт контекста пейвола. Возвращает тот же AdaptyPurchaseResult, что и makePurchase.

Если продвигаемый продукт содержит предложение по подписке, SDK применяет его при покупке автоматически. Предложение считывается из намерения о покупке App Store, которое доступно на iOS 18.0 и выше. На iOS 16.4–17.x покупка совершается по базовой цене.

Сохранение флоу-вью после закрытия

AdaptyUI().dismissFlowView и AdaptyUIFlowView.dismiss принимают флаг destroy:

await AdaptyUI().dismissFlowView(view, destroy: false);

По умолчанию он равен true, что освобождает вью как прежде. При destroy: false вью остаётся в памяти, поэтому вы можете показать его снова — пользователь вернётся к тому экрану, на котором остановился, с тем состоянием, которое флоу успел накопить.

Вью, сохранённое таким образом, удерживается до тех пор, пока вы не закроете его с destroy: true. Попытка показать уже освобождённое вью завершится ошибкой — чтобы снова показать этот флоу, вызовите createFlowView заново.

hasViewConfiguration

AdaptyFlow.hasViewConfiguration теперь также требует, чтобы флоу содержал UI-схему, поэтому возвращает true только для флоу, который AdaptyUI может отрисовать. Флоу, достигший вашего приложения без схемы, теперь возвращает false там, где версия 4.0 возвращала true. См. Получение конфигурации представления.