Миграция Adapty Kotlin Multiplatform SDK на v4.0

Adapty Kotlin Multiplatform 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, ...)`
`AdaptyUI.createNativePaywallView(...)` → `AdaptyNativePaywallView`	`AdaptyUI.createNativeFlowView(...)` → `AdaptyNativeFlowView`
`AdaptyUIPaywallView`	`AdaptyUIFlowView`
`AdaptyUI.presentPaywallView(view)` / `dismissPaywallView(view)`	`AdaptyUI.presentFlowView(view)` / `dismissFlowView(view)`
`AdaptyUI.setPaywallsEventsObserver(observer)`	`AdaptyUI.setFlowsEventsObserver(observer)`
`AdaptyUI.registerPaywallEventsListener` / `unregisterPaywallEventsListener`	`AdaptyUI.registerFlowEventsListener` / `unregisterFlowEventsListener`
`AdaptyUIPaywallsEventsObserver`	`AdaptyUIFlowsEventsObserver`
`AdaptyUIPaywallPlatformView(paywall, ...)`	`AdaptyUIFlowPlatformView(flow, ...)`
`paywallViewDidPerformAction`, `paywallViewDidAppear` и другие колбэки `paywallView...`	`flowViewDidPerformAction`, `flowViewDidAppear` и другие колбэки `flowView...`
`paywallViewDidFailRendering`	`flowViewDidReceiveError`

AdaptyPaywallProduct сохраняет своё название — продукты по-прежнему принадлежат флоу, и getPaywallProducts тоже сохраняет название, теперь принимая AdaptyFlow. Методы getFlow и getFlowForDefaultAudience больше не принимают параметр locale — передавайте его в createFlowView. API покупок и профилей (makePurchase, restorePurchases, getProfile, identify, updateProfile) и setFallback сохраняют те же сигнатуры, однако файл резервного пейвола необходимо скачать заново — см. Резервные файлы. Методы онбординга по-прежнему работают, но считаются устаревшими — см. Устаревание API онбординга. Некоторые поведения по умолчанию изменились — см. Изменения поведения по умолчанию.

Установка

v4.0 — это предрелизная версия, поэтому указывайте точный номер версии: Gradle не выбирает предрелизные версии через динамические диапазоны:

[versions]
adapty-kmp = "4.0.1-beta.1"

[libraries]
adapty-kmp = { module = "io.adapty:adapty-kmp", version.ref = "adapty-kmp" }
adapty-kmp-ui = { module = "io.adapty:adapty-kmp-ui", version.ref = "adapty-kmp" }

Модуль adapty-kmp-ui нужен только если вы отображаете флоу и пейволы через слой Compose Multiplatform (view.present()). Подробная инструкция по настройке — в разделе Установка Adapty SDK.

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

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

getPaywall → getFlow

Возвращаемый тип меняется с AdaptyPaywall на AdaptyFlow, параметр locale переносится из вызова fetch в createFlowView; для кастомных пейволов все локали возвращаются в flow.remoteConfigs:

- Adapty.getPaywall("YOUR_PLACEMENT_ID", locale = "en")
-     .onSuccess { paywall ->
-         // use the paywall
+ Adapty.getFlow("YOUR_PLACEMENT_ID")
+     .onSuccess { flow ->
+         AdaptyUI.createFlowView(flow = flow, locale = "en")
      }
      .onError { error ->
          // handle the error
      }

locale остаётся необязательным параметром в createFlowView: если его не указать, вид отобразится на en или на языке по умолчанию флоу, если в нём нет en. См. Локализации и коды языков.

getPaywallForDefaultAudience переименован аналогичным образом:

- Adapty.getPaywallForDefaultAudience("YOUR_PLACEMENT_ID", locale = "en")
+ Adapty.getFlowForDefaultAudience("YOUR_PLACEMENT_ID")

getPaywallProducts(paywall) → getPaywallProducts(flow)

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

- Adapty.getPaywallProducts(paywall)
+ Adapty.getPaywallProducts(flow)
      .onSuccess { products ->
          // use the products
      }

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

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

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

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

Свойство v3 `AdaptyPaywall`	Свойство v4 `AdaptyFlow`	Действие
`remoteConfig: AdaptyRemoteConfig?` (одиночное)	`remoteConfigs: List<AdaptyRemoteConfig>`	Флоу содержит один Remote Config на каждый настроенный язык. Читайте тот, который соответствует пользователю: `flow.remoteConfigs.firstOrNull { it.locale == "en" }`.
(новое)	`paywalls: List<AdaptyFlowPaywall>`	Каждый элемент — один вариант пейвола во флоу со своими `name`, `variationId` и `productIdentifiers`. Методы web paywall принимают `AdaptyFlowPaywall` — см. Методы web paywall.
`productIdentifiers`	перемещено	Идентификаторы продуктов теперь хранятся в каждом варианте: `flow.paywalls[i].productIdentifiers`. Для получения продуктов по-прежнему используйте `getPaywallProducts(flow)`.
`hasViewConfiguration`	удалено	Удалите все проверки `hasViewConfiguration` из кода — вместо этого `createFlowView` возвращает ошибку (см. Отображение флоу).

hasViewConfiguration остаётся в AdaptyOnboarding — только модель флоу его убирает.

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

openWebPaywall и createWebPaywallUrl сохраняют свои названия, но параметр paywall заменяется параметром flowPaywall, принимающим AdaptyFlowPaywall — одним из вариантов в flow.paywalls. Вместо него по-прежнему можно передать AdaptyPaywallProduct:

- Adapty.openWebPaywall(paywall = paywall)
+ flow.paywalls.firstOrNull()?.let { flowPaywall ->
+     Adapty.openWebPaywall(flowPaywall = flowPaywall)
+ }

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

logShowPaywall → logShowFlow

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

- Adapty.logShowPaywall(paywall)
+ Adapty.logShowFlow(flow)

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

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

createPaywallView → createFlowView

Переименуйте фабричный метод и передайте AdaptyFlow. Тип возвращаемого значения переименован с AdaptyUIPaywallView на AdaptyUIFlowView, но его методы (present, dismiss) и необязательные параметры (loadTimeout, preloadProducts, customTags, customTimers, customAssets, productPurchaseParams) остались прежними. Добавлен один новый необязательный параметр: locale — он заменяет locale, который раньше передавался в getPaywall. Подробнее см. в разделе Получение флоу.

- AdaptyUI.createPaywallView(paywall)
+ AdaptyUI.createFlowView(flow)
      .onSuccess { view ->
          view.present()
      }
      .onError { error ->
          // handle the error
      }

Если вы не используете Compose Multiplatform, нативный фабричный метод переименован аналогичным образом:

- AdaptyUI.createNativePaywallView(paywall)
+ AdaptyUI.createNativeFlowView(flow)

createFlowView возвращает AdaptyResult.Error, если у флоу не настроен view — это заменяет проверку hasViewConfiguration из v3:

- if (paywall.hasViewConfiguration) {
-     AdaptyUI.createPaywallView(paywall)
-         .onSuccess { view -> view.present() }
- }
+ AdaptyUI.createFlowView(flow)
+     .onSuccess { view -> view.present() }
+     .onError { error ->
+         // the flow has no view configured, or view creation failed
+     }

Представление флоу одноразовое: после вызова dismiss() оно уничтожается, поэтому для повторного отображения флоу вызовите createFlowView снова.

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

Наблюдатель событий переименован с AdaptyUIPaywallsEventsObserver на AdaptyUIFlowsEventsObserver, а его колбэки меняют префикс paywallView на flowView. Тела существующих обработчиков менять не нужно — достаточно переименовать тип и переопределения:

- AdaptyUI.setPaywallsEventsObserver(object : AdaptyUIPaywallsEventsObserver {
-     override fun paywallViewDidFinishPurchase(
-         view: AdaptyUIPaywallView,
+ AdaptyUI.setFlowsEventsObserver(object : AdaptyUIFlowsEventsObserver {
+     override fun flowViewDidFinishPurchase(
+         view: AdaptyUIFlowView,
          product: AdaptyPaywallProduct,
          purchaseResult: AdaptyPurchaseResult
      ) {
          // custom logic after purchase
      }
  })

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

- override fun paywallViewDidFailRendering(view: AdaptyUIPaywallView, error: AdaptyError) {}
+ override fun flowViewDidReceiveError(view: AdaptyUIFlowView, error: AdaptyError) {}

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

Compose platform view

Если вы встраиваете представления через Compose Multiplatform composable, AdaptyUIPaywallPlatformView(paywall, ...) переименовывается в AdaptyUIFlowPlatformView(flow, ...). Колбэки событий сохраняют свои имена onDid..., за исключением onDidFailRendering, который становится onDidReceiveError:

- AdaptyUIPaywallPlatformView(
-     paywall = paywall,
+ AdaptyUIFlowPlatformView(
+     flow = flow,
      onDidFinishPurchase = { view, product, result -> /* ... */ },
  )

Как и в v3, коллбэки, которые вы передаёте здесь (и любой наблюдатель, зарегистрированный через registerFlowEventsListener), выполняются в дополнение к глобальному наблюдателю, а не вместо него — ваш коллбэк наблюдает за событием, но не заменяет глобальное поведение по умолчанию. Учитывайте изменения поведения по умолчанию: например, глобальное поведение по умолчанию больше не закрывает экран после покупки.

Новые API

AdaptyUI.setObserverModeResolver(...) с AdaptyUIObserverModeResolver — управляет покупками и восстановлениями, инициированными из флоу, пока SDK работает в режиме наблюдателя. Ранее это было доступно только в нативных iOS и Android SDK. См. Отображение флоу в режиме наблюдателя.
AdaptyUI.setSystemRequestsHandler(...) с AdaptyUISystemRequestsHandler — зарезервировано для системных запросов из флоу (запросы разрешений ОС и запросы на оценку приложения). Флоу пока не инициируют такие запросы, поэтому регистрировать обработчик не нужно.
Новый необязательный коллбэк flowViewDidReceiveAnalyticEvent зарезервирован для пользовательских аналитических событий из флоу. Флоу пока не передают их в ваш код, так что реализовывать его не нужно.
AdaptyUI.openWebUrl(url, openIn) и AdaptyUI.requestAppReview() — обеспечивают стандартную обработку OpenUrlAction и стандартный handleAppReviewRequest, так что URL-адреса и запросы на оценку приложения обрабатываются нативно из коробки. Вызывайте их напрямую только если переопределяете поведение по умолчанию.
AdaptyUIFlowView.locale — возвращает локализацию, с которой было построено представление, чтобы вы могли определить, какую из них пользователь видит фактически. Требуется SDK 4.0.1-beta.1 или новее.
AdaptyConfig.ServerCluster.CN — новый вариант серверного кластера наряду с DEFAULT и EU, для подключения приложения к серверам Adapty в Китае.

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

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

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

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

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

Устаревшие символы: getOnboarding, getOnboardingForDefaultAudience, AdaptyUI.createOnboardingView, AdaptyUI.createNativeOnboardingView и AdaptyUIOnboardingsEventsObserver.