Миграция Adapty Android SDK на v. 4.0

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

Краткая справка

v3	v4
`Adapty.getPaywall(placementId, locale)`	`Adapty.getFlow(placementId)`
`Adapty.getPaywallForDefaultAudience(placementId, locale)`	`Adapty.getFlowForDefaultAudience(placementId)`
`AdaptyUI.getViewConfiguration(paywall)`	`AdaptyUI.getFlowConfiguration(flow, locale)`
`AdaptyUI.LocalizedViewConfiguration`	`AdaptyUI.FlowConfiguration`
`Adapty.getPaywallProducts(paywall)`	`Adapty.getPaywallProducts(flow)`
`Adapty.logShowPaywall(paywall)`	`Adapty.logShowFlow(flow)`
`AdaptyPaywall`	`AdaptyFlow`
`AdaptyUI.getPaywallView(...)`	`AdaptyUI.getFlowView(...)`
`AdaptyPaywallView`	`AdaptyFlowView`
`AdaptyPaywallScreen` (Compose)	`AdaptyFlowScreen`
`showPaywall(...)`	`showFlow(...)`
`AdaptyPaywallInsets`	`AdaptyFlowInsets`
`AdaptyUiEventListener`	`AdaptyFlowEventListener`
`AdaptyUiDefaultEventListener`	`AdaptyFlowDefaultEventListener`
`onPaywallShown` / `onPaywallClosed`	`onFlowShown` / `onFlowClosed`
`onRenderingError`	`onError`
`Adapty.updateAttribution(attribution, source)` (`source: String`)	`Adapty.updateAttribution(attribution, source)` (`source: AdaptyAttributionSource`)
`Adapty.setIntegrationIdentifier(key, value)`	`Adapty.setIntegrationIdentifier(AdaptyIntegrationIdentifier)`
`AdaptyPaywallProduct` сохраняет своё название — продукты по-прежнему принадлежат флоу, а `getPaywallProducts` теперь принимает `AdaptyFlow`. Остальные методы `AdaptyFlowEventListener` (`onProductSelected`, `onPurchaseStarted`, `onPurchaseFinished`, `onPurchaseFailure`, `onRestoreSuccess`, `onRestoreFailure`, `onActionPerformed`, `onAwaitingPurchaseParams`, `onLoadingProductsFailure` и т. д.) сохраняют свои названия и сигнатуры.

Установка

Укажите версию adapty-bom 4.0.0 (или новее) и синхронизируйте проект. BOM автоматически подберёт совместимые версии android-sdk и android-ui. Инструкции по добавлению зависимостей — в разделе Установка Adapty SDK.

Удалённые и устаревшие API

Adapty.makePurchase(activity, product, subscriptionUpdateParams, isOfferPersonalized, callback) — удалён. Этот перегруженный метод был помечен как устаревший в v3. Передавайте те же параметры через AdaptyPurchaseParameters:

- Adapty.makePurchase(activity, product, subscriptionUpdateParams, isOfferPersonalized) { result -> /* ... */ }
+ val params = AdaptyPurchaseParameters.Builder()
+     .withSubscriptionUpdateParams(subscriptionUpdateParams)
+     .withOfferPersonalized(isOfferPersonalized)
+     .build()
+ Adapty.makePurchase(activity, product, params) { result -> /* ... */ }

Онбординги устарели. AdaptyUI.getOnboardingView и AdaptyUI.getOnboardingConfiguration помечены как @Deprecated в версии 4.0 — переносите онбординги во флоу, созданные в Flow Builder.

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

getPaywall + getViewConfiguration → getFlow + getFlowConfiguration

Тип возвращаемого значения при получении данных изменяется с AdaptyPaywall на AdaptyFlow, а загрузчик конфигурации переименован с AdaptyUI.getViewConfiguration на AdaptyUI.getFlowConfiguration (возвращает AdaptyUI.FlowConfiguration вместо AdaptyUI.LocalizedViewConfiguration). Параметр locale перемещён из вызова получения данных в getFlowConfiguration:

- Adapty.getPaywall("YOUR_PLACEMENT_ID", locale = "en") { result ->
+ Adapty.getFlow("YOUR_PLACEMENT_ID") { result ->
      if (result is AdaptyResult.Success) {
-         val paywall = result.value
-         if (!paywall.hasViewConfiguration) return@getPaywall
-         AdaptyUI.getViewConfiguration(paywall) { configResult ->
+         val flow = result.value
+         if (!flow.hasViewConfiguration) return@getFlow
+         AdaptyUI.getFlowConfiguration(flow, locale = "en") { configResult ->
              if (configResult is AdaptyResult.Success) {
                  val flowConfiguration = configResult.value
              }
          }
      }
  }

getPaywallProducts(paywall) → getPaywallProducts(flow)

getPaywallProducts теперь принимает AdaptyFlow, возвращаемый методом Adapty.getFlow:

- Adapty.getPaywallProducts(paywall) { result -> /* products */ }
+ Adapty.getPaywallProducts(flow) { result -> /* products */ }

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

logShowPaywall → logShowFlow

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

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

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

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

getPaywallView / AdaptyPaywallView → getFlowView / AdaptyFlowView

Переименуйте фабричный метод и тип представления, а также передайте AdaptyUI.FlowConfiguration:

- val paywallView = AdaptyUI.getPaywallView(
-     activity,
-     viewConfiguration,
-     products,
-     eventListener,
- )
+ val flowView = AdaptyUI.getFlowView(
+     activity,
+     flowConfiguration,
+     products,
+     eventListener,
+ )

Если вы создаёте представление напрямую, метод показа также переименован:

- val paywallView = AdaptyPaywallView(activity)
- paywallView.showPaywall(viewConfiguration, products, eventListener)
+ val flowView = AdaptyFlowView(activity)
+ flowView.showFlow(flowConfiguration, products, eventListener)

В XML-разметке обновите тег представления:

- <com.adapty.ui.AdaptyPaywallView ... />
+ <com.adapty.ui.AdaptyFlowView ... />

Необязательный параметр personalizedOfferResolver удалён из getFlowView / showFlow / AdaptyFlowScreen. Чтобы указать персонализированную цену, задайте её для каждого продукта через onAwaitingPurchaseParams (AdaptyPurchaseParameters.Builder().withOfferPersonalized(true)). Новый необязательный параметр customAssets позволяет переопределять изображения и видео во время выполнения — подробнее см. в разделе Кастомизация ресурсов.

AdaptyPaywallScreen → AdaptyFlowScreen

В Jetpack Compose переименуйте компонуемый элемент и обновите параметр конфигурации:

- AdaptyPaywallScreen(
-     viewConfiguration,
+ AdaptyFlowScreen(
+     flowConfiguration,
      products,
      eventListener,
  )

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

Слушатель событий переименован с AdaptyUiEventListener на AdaptyFlowEventListener (а AdaptyUiDefaultEventListener — на AdaptyFlowDefaultEventListener). Большинство названий методов не изменились; переименованы только колбэки жизненного цикла и рендеринга:

- class YourListener : AdaptyUiDefaultEventListener() {
+ class YourListener : AdaptyFlowDefaultEventListener() {

-     override fun onPaywallShown(context: Context) {}
-     override fun onPaywallClosed() {}
+     override fun onFlowShown(context: Context) {}
+     override fun onFlowClosed() {}

-     override fun onRenderingError(error: AdaptyError, context: Context) {}
+     override fun onError(error: AdaptyError, context: Context) {}
  }

Тела существующих обработчиков менять не нужно — достаточно переименовать тип и переопределения. onError срабатывает для тех же ошибок рендеринга, что и onRenderingError, плюс для других ошибок времени выполнения, не связанных с покупками. Полный список коллбэков см. в разделе Обработка событий флоу и пейвола. В v4 также добавлен колбэк onBackPressed(context): Boolean, и его поведение по умолчанию изменилось. Раньше нажатие системной кнопки «Назад» (или жест «назад») передавалось вашей activity или фрагменту, что обычно закрывало пейвол. В v4 реализация по умолчанию перехватывает это нажатие, поэтому системная кнопка «Назад» больше не закрывает флоу самостоятельно — аналогично iOS, где флоу нельзя закрыть системным жестом. Предоставьте пользователям явный способ выйти (кнопку Close или действие on_device_back), либо переопределите onBackPressed и верните false, чтобы восстановить прежнее поведение. Подробнее см. в разделе Системная кнопка «Назад». Стандартный обработчик покупки также больше не закрывает экран. В v3 стандартный onPurchaseFinished закрывал пейвол после любой завершённой покупки, которая не была отменой со стороны пользователя (успешная или ожидающая покупка). В v4 он ничего не делает, поэтому флоу остаётся открытым после покупки, пока вы сами его не закроете — поведение совпадает с iOS. Если вы полагались на автоматическое закрытие, закройте экран самостоятельно после завершения покупки. Пример см. в разделе Успешная, отменённая или ожидающая покупка.

Идентификаторы атрибуции и интеграций

updateAttribution

Параметр source меняется с String на новый тип AdaptyAttributionSource, а attribution теперь является Map<String, Any> (также доступна перегрузка с String в формате JSON). Используйте один из предопределённых источников:

- Adapty.updateAttribution(attribution, "appsflyer") { error -> /* handle the error */ }
+ Adapty.updateAttribution(attribution, AdaptyAttributionSource.APPSFLYER) { error -> /* handle the error */ }

Предопределённые источники: AdaptyAttributionSource.APPLE_ADS, .ADJUST, .APPSFLYER, .BRANCH, .TENJIN. Для любого другого источника создайте его из строки: AdaptyAttributionSource("your_source").

setIntegrationIdentifier

setIntegrationIdentifier(key, value) заменён методом, который принимает одно или несколько значений AdaptyIntegrationIdentifier. Создавайте каждый идентификатор с помощью удобного метода вместо передачи строкового ключа напрямую:

- Adapty.setIntegrationIdentifier("appsflyer_id", appsFlyerId) { error -> /* handle the error */ }
+ Adapty.setIntegrationIdentifier(AdaptyIntegrationIdentifier.appsflyerId(appsFlyerId)) { error -> /* handle the error */ }

Можно задать несколько идентификаторов в одном вызове:

Adapty.setIntegrationIdentifier(
    listOf(
        AdaptyIntegrationIdentifier.appsflyerId(appsFlyerId),
        AdaptyIntegrationIdentifier.adjustDeviceId(adjustDeviceId),
    )
) { error -> /* handle the error */ }

Замените каждую старую строку ключа соответствующим удобным методом:

v3 key	v4 метод `AdaptyIntegrationIdentifier`
`"adjust_device_id"`	`adjustDeviceId(value)`
`"airbridge_device_id"`	`airbridgeDeviceId(value)`
`"amplitude_user_id"`	`amplitudeUserId(value)`
`"amplitude_device_id"`	`amplitudeDeviceId(value)`
`"appmetrica_device_id"`	`appmetricaDeviceId(value)`
`"appmetrica_profile_id"`	`appmetricaProfileId(value)`
`"appsflyer_id"`	`appsflyerId(value)`
`"branch_id"`	`branchId(value)`
`"facebook_anonymous_id"`	`facebookAnonymousId(value)`
`"firebase_app_instance_id"`	`firebaseAppInstanceId(value)`
`"mixpanel_user_id"`	`mixpanelUserId(value)`
`"one_signal_subscription_id"`	`oneSignalSubscriptionId(value)`
`"one_signal_player_id"`	`oneSignalPlayerId(value)`
`"posthog_distinct_user_id"`	`posthogDistinctUserId(value)`
`"pushwoosh_hwid"`	`pushwooshHWID(value)`
`"tenjin_analytics_installation_id"`	`tenjinAnalyticsInstallationId(value)`
Для ключа, которого нет в этом списке, создайте идентификатор напрямую из пользовательского `Key`: `AdaptyIntegrationIdentifier(AdaptyIntegrationIdentifier.Key("custom"), customValue)`.