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

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

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

v3	v4
`Adapty.GetPaywall(placementId, locale, ...)`	`Adapty.GetFlow(placementId, ...)`
`Adapty.GetPaywallForDefaultAudience(placementId, locale, ...)`	`Adapty.GetFlowForDefaultAudience(placementId, ...)`
`Adapty.GetPaywallProducts(paywall, ...)`	`Adapty.GetPaywallProducts(flow, ...)`
`Adapty.LogShowPaywall(paywall, ...)`	`Adapty.LogShowFlow(flow, ...)`
`AdaptyPaywall`	`AdaptyFlow`
`AdaptyUI.CreatePaywallView(paywall, ...)`	`AdaptyUI.CreateFlowView(flow, ...)`
`AdaptyUICreatePaywallViewParameters`	`AdaptyUICreateFlowViewParameters`
`AdaptyUIPaywallView`	`AdaptyUIFlowView`
`AdaptyUI.PresentPaywallView(view, ...)` / `DismissPaywallView(view, ...)`	`AdaptyUI.PresentFlowView(view, ...)` / `DismissFlowView(view, ...)`
`Adapty.SetPaywallsEventsListener(listener)`	`Adapty.SetFlowsEventsListener(listener)`
`AdaptyPaywallsEventsListener`	`IAdaptyFlowsEventsListener`
`AdaptyEventListener`	`IAdaptyEventListener`
`AdaptyOnboardingsEventsListener`	`IAdaptyOnboardingsEventsListener`
`PaywallViewDidPerformAction`, `PaywallViewDidAppear` и другие колбэки `PaywallView...`	`FlowViewDidPerformAction`, `FlowViewDidAppear` и другие колбэки `FlowView...`
`PaywallViewDidFailRendering`	`FlowViewDidReceiveError`
`Adapty.SetFallbackPaywalls(...)` (устарело в v3)	удалено — используйте `Adapty.SetFallback(fileName, ...)`
`Builder.SetIDFACollectionDisabled(...)` (устарело в v3)	удалено — используйте `Builder.SetAppleIDFACollectionDisabled(...)`
`paywall.Products` (список `AdaptyProductReference`)	удалено — используйте `ProductIdentifiers` или `VendorProductIds`, либо вызовите `GetPaywallProducts(flow)` для получения полных продуктов
`AdaptyProductReference`	удалено как публичный тип — см. Модель данных
`paywall.RemoteConfigString`	удалено — используйте `flow.RemoteConfig?.Data`

AdaptyPaywallProduct сохраняет своё название — продукты по-прежнему принадлежат флоу, и GetPaywallProducts тоже сохраняет название, теперь принимая AdaptyFlow. Методы GetFlow и GetFlowForDefaultAudience больше не принимают параметр locale. API покупок и профиля (MakePurchase, RestorePurchases, GetProfile, Identify, UpdateProfile), а также резервные пейволы через SetFallback остаются без изменений. Методы онбординга по-прежнему работают, но считаются устаревшими — см. Устаревание Onboarding API. Некоторые поведения по умолчанию изменились — см. Изменения поведения по умолчанию.

Установка

v4.0 — это пре-релиз, поэтому указывайте точный бета-тег. Чтобы установить через Unity Package Manager, добавьте тег к Git URL:

https://github.com/adaptyteam/AdaptySDK-Unity.git?path=/Packages/com.adapty.unity-sdk#4.0.0-beta.1

Если вы устанавливаете через Unity-пакет, скачайте adapty-unity-plugin-4.0.0-beta.1.unitypackage из релиза 4.0.0-beta.1. Полная инструкция по настройке — в разделе Установка Adapty SDK.

В v4 появились два изменения в настройке сборки:

iOS-зависимости переходят на Swift Package Manager. Нативный Adapty iOS SDK 4.0 объявляется как удалённый Swift-пакет вместо CocoaPods pod. Обновите External Dependency Manager до версии 1.2.188 или выше — более ранние версии не поддерживают зависимости Swift Package Manager. Шаги с CocoaPods (iOS Resolver -> Install Cocoapods, открытие Unity-iPhone.xcworkspace) больше не применяются.
Минимальная версия iOS deployment target должна быть 15.0 или выше. Новый валидатор сборки в Unity Editor прерывает iOS-сборку, если указана более низкая версия.

Базовые нативные SDK Adapty обновлены до версии 4.x на обеих платформах и подтягиваются автоматически — никаких дополнительных изменений в сборке не требуется.

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

GetPaywall → GetFlow

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

- Adapty.GetPaywall("YOUR_PLACEMENT_ID", "en", (paywall, error) => {
+ Adapty.GetFlow("YOUR_PLACEMENT_ID", (flow, error) => {
      if (error != null) {
          // handle the error
          return;
      }
-     // use the paywall
+     // use the flow
  });

GetPaywallForDefaultAudience переименован аналогично:

- Adapty.GetPaywallForDefaultAudience("YOUR_PLACEMENT_ID", "en", (paywall, error) => { /* ... */ });
+ Adapty.GetFlowForDefaultAudience("YOUR_PLACEMENT_ID", (flow, error) => { /* ... */ });

GetPaywallProducts(paywall) → GetPaywallProducts(flow)

GetPaywallProducts сохраняет своё имя, но теперь принимает AdaptyFlow:

- Adapty.GetPaywallProducts(paywall, (products, error) => {
+ Adapty.GetPaywallProducts(flow, (products, error) => {
      if (error != null) {
          // handle the error
          return;
      }
      // use the products
  });

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

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

Свойство `AdaptyPaywall` в v3	Свойство `AdaptyFlow` в v4	Действие
`RemoteConfig` (одиночный, nullable)	`RemoteConfigs` (список)	Флоу содержит по одному Remote Config на каждый настроенный язык. Читайте тот, что соответствует пользователю, из `flow.RemoteConfigs`. Шорткат `flow.RemoteConfig` возвращает первую запись.
(новое)	`Paywalls` (список `AdaptyFlowPaywall`)	Каждая запись — один вариант пейвола во флоу со своими `Name`, `VariationId` и `ProductIdentifiers`. Методы веб-пейвола принимают `AdaptyFlowPaywall` — см. Методы веб-пейвола.
`ProductIdentifiers`, `VendorProductIds`	сохранены	В `AdaptyFlow` эти поля агрегируют продукты по всем вариантам пейвола. Каждый вариант также предоставляет собственные `ProductIdentifiers` и `VendorProductIds`. Для получения продуктов продолжайте вызывать `GetPaywallProducts(flow)`.
`HasViewConfiguration`	удалено	Удалите все проверки `HasViewConfiguration` из кода — вместо этого `CreateFlowView` вернёт ошибку (см. Отображение флоу).
`Products` (список `AdaptyProductReference`)	удалено	`AdaptyProductReference` больше не является публичным, вместе с ним недоступны значения `PromotionalOfferId`, `WinBackOfferId` и `AndroidOfferId`. Используйте `ProductIdentifiers` — список `AdaptyProductIdentifier` с `VendorProductId` и Android-только `BasePlanId` (аналог `AndroidBasePlanId` из v3) — или вызывайте `GetPaywallProducts(flow)`, когда нужны полные объекты `AdaptyPaywallProduct` с ценами и офферами.
`RemoteConfigString`	удалено	Читайте строку напрямую из Remote Config: `flow.RemoteConfig?.Data` или соответствующую запись в `flow.RemoteConfigs`.
(новое)	`FlowVersionId` (nullable)	Идентификатор версии флоу или `null`, если он недоступен.

AdaptyPaywallProduct получает одно новое поле: FlowProductId — идентификатор продукта внутри флоу, который равен null для продуктов, не принадлежащих флоу.

Методы Web Paywall

OpenWebPaywall и CreateWebPaywallUrl сохраняют свои названия, но аргумент paywall теперь принимает AdaptyFlowPaywall — один из вариантов в flow.Paywalls. По-прежнему можно передать AdaptyPaywallProduct:

- Adapty.OpenWebPaywall(paywall, AdaptyWebPresentation.ExternalBrowser, (error) => { /* ... */ });
+ var flowPaywall = flow.Paywalls.FirstOrDefault();
+ if (flowPaywall != null) {
+     Adapty.OpenWebPaywall(flowPaywall, AdaptyWebPresentation.ExternalBrowser, (error) => { /* ... */ });
+ }

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

LogShowPaywall → LogShowFlow

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

- Adapty.LogShowPaywall(paywall, (error) => { /* ... */ });
+ Adapty.LogShowFlow(flow, (error) => { /* ... */ });

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

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

CreatePaywallView → CreateFlowView

Переименуйте фабричный метод и передайте AdaptyFlow. Тип возвращаемого представления переименован с AdaptyUIPaywallView на AdaptyUIFlowView, однако его методы (Present, Dismiss) остались прежними, а объект необязательных параметров сохраняет те же поля (LoadTimeout, PreloadProducts, CustomTags, CustomTimers, CustomAssets, ProductPurchaseParameters) под новым именем AdaptyUICreateFlowViewParameters, плюс два новых — Locale и EnableSafeAreaPaddings:

- AdaptyUI.CreatePaywallView(paywall, parameters, (view, error) => {
+ AdaptyUI.CreateFlowView(flow, parameters, (view, error) => {
      if (error != null) {
          // handle the error
          return;
      }
      view.Present((error) => { /* handle the error */ });
  });

CreateFlowView возвращает ошибку, если у флоу не настроено представление — это заменяет проверку HasViewConfiguration из v3:

- if (paywall.HasViewConfiguration) {
-     AdaptyUI.CreatePaywallView(paywall, null, (view, error) => { /* ... */ });
- }
+ AdaptyUI.CreateFlowView(flow, (view, error) => {
+     if (error != null) {
+         // the flow has no view configured, or view creation failed
+         return;
+     }
+     view.Present((error) => { /* handle the error */ });
+ });

Представление флоу одноразовое: после вызова Dismiss оно уничтожается, поэтому для повторного отображения флоу вызовите CreateFlowView ещё раз.

Отступы безопасной зоны Android

AdaptyUICreateFlowViewParameters добавляет EnableSafeAreaPaddings, который управляет отступами безопасной зоны Android во время выполнения. На iOS игнорируется и по умолчанию равен true:

var parameters = new AdaptyUICreateFlowViewParameters()
    .SetEnableSafeAreaPaddings(false);

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

Интерфейсы слушателей теперь следуют соглашению об именовании C# с префиксом I, и устаревшие псевдонимы не сохраняются — переименуйте AdaptyEventListener в IAdaptyEventListener, а AdaptyOnboardingsEventsListener в IAdaptyOnboardingsEventsListener везде, где вы их реализуете.

Слушатель событий флоу переименован с AdaptyPaywallsEventsListener на IAdaptyFlowsEventsListener, метод его регистрации — с SetPaywallsEventsListener на SetFlowsEventsListener, а в колбэках префикс PaywallView заменён на FlowView. Тела существующих обработчиков менять не нужно — достаточно переименовать интерфейс и методы:

- public class MyListener : MonoBehaviour, AdaptyPaywallsEventsListener {
-     public void PaywallViewDidFinishPurchase(
-         AdaptyUIPaywallView view,
+ public class MyListener : MonoBehaviour, IAdaptyFlowsEventsListener {
+     public void FlowViewDidFinishPurchase(
+         AdaptyUIFlowView view,
          AdaptyPaywallProduct product,
          AdaptyPurchaseResult purchasedResult
      ) {
          // custom logic after purchase
      }
      // ...
  }

- Adapty.SetPaywallsEventsListener(myListener);
+ Adapty.SetFlowsEventsListener(myListener);

Один коллбэк переименован: PaywallViewDidFailRendering становится FlowViewDidReceiveError. Он срабатывает для тех же ошибок рендеринга, что и раньше, плюс для других ошибок времени выполнения, не связанных с покупками:

- public void PaywallViewDidFailRendering(AdaptyUIPaywallView view, AdaptyError error) { }
+ public void FlowViewDidReceiveError(AdaptyUIFlowView view, AdaptyError error) { }

Полный список коллбэков см. в разделе Обработка событий флоу и пейвола.

Новые API

Adapty.SetObserverModeResolver(...) с IAdaptyUIObserverModeResolver — управляет покупками и восстановлениями, инициированными из флоу, когда SDK работает в режиме Observer. Ранее это было доступно только в нативных SDK для iOS и Android. См. Показ флоу в режиме Observer.
Adapty.SetSystemRequestsHandler(...) с IAdaptyUISystemRequestsHandler — зарезервирован для системных запросов из флоу: запросов разрешений ОС (FlowViewDidAskPermission) и запросов оценки приложения (FlowViewDidRequestAppReview). Флоу пока не инициируют такие запросы, поэтому регистрировать обработчик не нужно.
AdaptyUICreateFlowViewParameters.Locale (задаётся через SetLocale) — рендерит флоу или пейвол с определённой локализацией Builder вместо той, которую Adapty определяет по устройству. Флоу локализуется при создании представления, поэтому это единственное место для выбора локализации; созданное представление сообщает о применённой локализации в view.Locale. См. Использование локализаций и кодов локалей.
Новый колбэк FlowViewDidReceiveAnalyticEvent в IAdaptyFlowsEventsListener зарезервирован для пользовательских аналитических событий из флоу. Флоу пока не отправляют такие события в ваш код, поэтому реализуйте его с пустым телом.
AdaptyUI.OpenUrl(url, openIn, ...) и AdaptyUI.RequestAppReview(...) — нативная обработка действий open_url и запросов оценки приложения. Вызывайте OpenUrl из FlowViewDidPerformAction, чтобы сохранить стандартное поведение при открытии URL; RequestAppReview обеспечивает стандартный запрос оценки приложения, который флоу пока не инициируют.

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

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

Завершение покупки: В v3 окно закрывалось автоматически после успешной покупки. В v4 флоу остаётся открытым после покупки или ошибки, пока вы сами его не закроете — SDK не применяет никакого поведения по умолчанию. Вызывайте view.Dismiss(...) самостоятельно в FlowViewDidFinishPurchase, когда пользователь получил доступ.
Системная кнопка «Назад» на Android: Нажатие системной кнопки «Назад» (или жест возврата) передаётся в FlowViewDidPerformAction как действие SystemBack и больше не закрывает флоу самостоятельно — аналогично iOS, где флоу нельзя закрыть системным жестом. Дайте пользователям явный способ выйти (кнопка Close или действие on_device_back), либо закрывайте вью самостоятельно при обработке этого действия.
Вью одноразовые: После Dismiss вью уничтожается. Чтобы снова показать флоу, вызовите CreateFlowView заново.
Транзакции в режиме Observer: ReportTransaction больше не возвращает ошибку декодирования при успехе — в v3 ответ об успехе парсился некорректно, поэтому успешный репорт всегда завершался с ошибкой.

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

Устаревший API онбординга объявлен устаревшим в v4.0 в пользу Flow Builder. Он по-прежнему работает, но будет удалён в одном из следующих релизов, поэтому запланируйте перенос ваших онбордингов во Flow Builder.

Устаревшие символы: GetOnboarding, GetOnboardingForDefaultAudience, AdaptyUI.CreateOnboardingView, AdaptyUI.PresentOnboardingView, AdaptyUI.DismissOnboardingView и Adapty.SetOnboardingsEventsListener.