Миграция Adapty Unity SDK на v4.1

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 опциональным, добавляет обязательный метод слушателя и изменяет формат файла резервного пейвола.

Note

Переходите с бета-версии 4.0? Замените закреплённый бета-тег на установку версии 4.1.0, и вас касаются только четыре раздела: новый метод listener, переименованные 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 перемещается в параметры представления флоу (AdaptyUICreateFlowViewParameters.SetLocale) — см. Точное совпадение локали; для кастомных пейволов все локали возвращаются в 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) => { /* ... */ });

Сопоставление локали происходит точно

Warning

В v3 сервер Adapty подбирал локализацию и использовал запасную по языку: запрос pt-br получал локализацию pt, если на пейволе не было pt-br. В v4 SDK подбирает локализацию на устройстве и использует только точное совпадение. Если код не совпадает ни с одной локализацией, флоу отображается в локализации по умолчанию — без ошибки и без предупреждения.

Перед обновлением проверьте коды локали, которые передаёт ваше приложение:

Для каждого регионального кода, который вы передаёте, добавьте локализацию с этим кодом — например, pt-br рядом с pt — или сопоставьте код с тем, что есть во флоу.
Передавайте коды точно так, как они отображаются в дашборде — строчные подтеги, разделённые дефисами. Не передавайте системный идентификатор локали напрямую: CultureInfo.CurrentCulture.Name возвращает pt-BR, который не соответствует ни одной локализации.

См. Локализации и коды локалей.

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:

Note

CustomTimers по-прежнему существует, но влияет только на пейволы, созданные в Legacy Paywall Builder. Таймер обратного отсчёта во флоу работает по настройкам, заданным в Flow & Paywall Builder, поэтому флоу игнорирует всё, что вы передаёте здесь.

- 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 */ });
+ });

Note

Флоу-вью одноразовое: после вызова 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) { }

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

Новый обязательный метод: 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 отключена по умолчанию

Warning

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

В более ранних версиях 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, даже если вы уже скачивали их для более ранней версии.

Warning

Этот шаг не вызывает ошибок компиляции. Если его пропустить, SetFallback вернёт DecodingFailed (adapty_code: 2006), и все плейсменты потеряют резервный пейвол.

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

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

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

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

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

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