Adapty Unity SDK 4.1 — первый стабильный релиз ветки 4.x: версия 4.0 вышла только как бета, поэтому если вы на 3.x, мигрируйте сразу на 4.1. В этом гайде описана вся миграция: флоу, появившиеся в 4.0, и изменения версии 4.1 поверх них.

Версия 4.x вводит флоу и переименовывает API пейволов соответствующим образом. Новые API работают с флоу и по-прежнему совместимы с пейволами из старого билдера — никаких изменений на стороне дашборда Adapty не требуется. Помимо этого, версия 4.1 переименовывает API внешней атрибуции, делает Adapty Attribution опциональным, добавляет обязательный метод слушателя и изменяет формат файла резервного пейвола.

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

v3	v4.1
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, с новым обязательным методом OnReceivePromotedPurchase
AdaptyOnboardingsEventsListener	IAdaptyOnboardingsEventsListener
PaywallViewDidPerformAction, PaywallViewDidAppear и другие колбэки PaywallView...	FlowViewDidPerformAction, FlowViewDidAppear и другие колбэки FlowView...
PaywallViewDidFailRendering	FlowViewDidReceiveError
Adapty.UpdateAttribution(data, source, ...) со строковым source	Adapty.UpdateExternalAttribution(jsonString, provider, ...) с AdaptyExternalAttributionProvider
AdaptyProfile.AppliedAttributionSources как IReadOnlyList<string>	AdaptyProfile.AppliedExternalAttributionProviders как IReadOnlyList<AdaptyExternalAttributionProvider>
Атрибуция Adapty включена автоматически	отключена по умолчанию — активируйте через Builder.SetAdaptyAttributionEnabled(true)
Резервный файл загружен для версии 3.x	новый формат резервного файла — скачайте файл заново
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 сохраняет свою сигнатуру, но файл, который он читает, необходимо скачать заново — см. Резервные файлы. Методы онбординга по-прежнему работают, но устарели — см. Устаревание API онбординга. Некоторые поведения по умолчанию изменились — см. Изменения поведения по умолчанию.

Установка

Чтобы установить SDK 4.1 через Unity Package Manager, добавьте тег версии к Git URL:

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

Если вы устанавливаете через Unity-пакет, скачайте adapty-unity-plugin-4.1.0.unitypackage из релиза 4.1.0. Подробную инструкцию по настройке см. в разделе Установка Adapty SDK.

С версией 4.x появились два изменения в настройке сборки:

• Зависимости iOS переходят на Swift Package Manager. Нативный Adapty iOS SDK теперь подключается как удалённый Swift-пакет вместо CocoaPods pod. Обновите External Dependency Manager до версии 1.2.188 или выше — более ранние версии не поддерживают зависимости Swift Package Manager. Шаги с CocoaPods (iOS Resolver -> Install Cocoapods, открытие Unity-iPhone.xcworkspace) больше не применяются. Для сборки под iOS теперь требуется Xcode 26 или выше, так как Swift-пакет собирается с инструментами Swift 6.2.
• Минимальная версия 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, вызывать этот метод при отображении флоу или пейволов, отрисовываемых Adapty, не нужно — 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 */ });
+ });

Отступы безопасной зоны 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) { }

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

Новый обязательный метод: OnReceivePromotedPurchase

Начиная с версии SDK 4.1, интерфейс IAdaptyEventListener включает ещё один метод, поэтому все классы, реализующие его, перестанут компилироваться, пока вы не добавите:

public void OnReceivePromotedPurchase(AdaptyPromotedProduct product) {
    // The user tapped one of your in-app purchases on your App Store product page.
    // Complete the purchase through Adapty:
    Adapty.MakePromotedPurchase(product, (result, error) => { /* ... */ });
}

Этот метод предназначен для продвигаемых встроенных покупок App Store и никогда не вызывается на Android. Не оставляйте тело метода пустым: на iOS 16.4 и выше SDK передаёт покупку сюда и ожидает её завершения, поэтому пустое тело приведёт к потере покупки, уже инициированной пользователем. На более ранних версиях такие покупки завершались автоматически. См. Продвигаемые встроенные покупки App Store.

Новые API

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

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

Начиная с версии SDK 4.1, API для передачи данных атрибуции от внешнего провайдера (Adjust, AppsFlyer, Branch, Tenjin или другого) переименованы в соответствии с нативными SDK, а тип провайдера изменён со строки на тип. Устаревших псевдонимов нет, поэтому существующие вызовы перестанут компилироваться до тех пор, пока вы их не обновите:

До 4.1	4.1
Adapty.UpdateAttribution(data, source, ...)	Adapty.UpdateExternalAttribution(jsonString, provider, ...)
source как string	provider как AdaptyExternalAttributionProvider
AdaptyProfile.AppliedAttributionSources как IReadOnlyList<string>	AdaptyProfile.AppliedExternalAttributionProviders как IReadOnlyList<AdaptyExternalAttributionProvider>

Переименования метода недостаточно — замените аргумент provider в том же изменении:

- Adapty.UpdateAttribution(attributionJsonString, "adjust", (error) => { /* ... */ });
+ Adapty.UpdateExternalAttribution(attributionJsonString, AdaptyExternalAttributionProvider.Adjust, (error) => { /* ... */ });

AdaptyExternalAttributionProvider содержит идентификатор, по которому бэкенд распознаёт провайдера. Доступны шесть готовых экземпляров: AppleAds (apple_search_ads), Adjust, Appsflyer, Branch, Tenjin и Custom. Если Adapty добавит нового провайдера после выхода этой версии SDK, создайте экземпляр вручную, передав его идентификатор: new AdaptyExternalAttributionProvider("your_provider") — он будет передан на бэкенд без изменений. Пробельные символы по краям обрезаются автоматически.

Данные атрибуции передаются в виде сериализованной JSON-строки. Если у вас есть словарь, сначала сериализуйте его:

var attributionJsonString = Newtonsoft.Json.JsonConvert.SerializeObject(attribution);

На стороне профиля читайте применённые провайдеры через новый тип:

- if (profile.AppliedAttributionSources.Contains("apple_search_ads")) {
+ if (profile.AppliedExternalAttributionProviders.Contains(AdaptyExternalAttributionProvider.AppleAds)) {
      // Apple Ads attribution has been applied
  }

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

В более ранних версиях SDK регистрировал установки для атрибуции Adapty автоматически. Начиная с SDK версии 4.1, эта функция отключена по умолчанию: SDK не регистрирует установки, коллбэки OnInstallationDetailsSuccess и OnInstallationDetailsFail никогда не срабатывают, а GetCurrentInstallationStatus возвращает статус NotAvailable.

Если вы используете Adapty Attribution, включите его при активации SDK:

var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetAdaptyAttributionEnabled(true);

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

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

Формат резервного файла изменился в SDK 4.1. Заново скачайте резервные файлы для iOS и Android в разделе Placements > Fallbacks и замените те, что находятся в Assets/StreamingAssets, даже если вы уже скачивали их для более ранней версии.

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

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

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

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

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

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