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

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

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

v3	v4
`adapty.getPaywall(placementId, locale?, params?)`	`adapty.getFlow(placementId, params?)`
`adapty.getPaywallForDefaultAudience(placementId, locale?, params?)`	`adapty.getFlowForDefaultAudience(placementId, params?)`
`adapty.getPaywallProducts(paywall)`	`adapty.getPaywallProducts(flow)`
`adapty.logShowPaywall(paywall)`	`adapty.logShowFlow(flow)`
`AdaptyPaywall` (тип)	`AdaptyFlow`
`createPaywallView(paywall)`	`createFlowView(flow)`
`AdaptyPaywallView` (компонент)	`AdaptyFlowView`
`EventHandlers` (тип)	`FlowEventHandlers`
`onPaywallShown`	`onAppeared`
`onPaywallClosed`	`onDisappeared`
`onRenderingFailed`	`onError`
`AdaptyPaywallProduct` сохраняет своё название — продукты по-прежнему принадлежат флоу, а `getPaywallProducts` теперь принимает `AdaptyFlow`. Методы `getFlow` и `getFlowForDefaultAudience` больше не принимают параметр `locale`. Методы представления `present`, `dismiss`, `setEventHandlers` и `showDialog`, а также обработчики событий `onCloseButtonPress`, `onUrlPress`, `onCustomAction`, `onProductSelected`, `onPurchaseStarted`, `onPurchaseCompleted`, `onPurchaseFailed`, `onRestoreStarted`, `onRestoreCompleted`, `onRestoreFailed`, `onLoadingProductsFailed`, `onWebPaymentNavigationFinished` и `onAndroidSystemBack` сохраняют те же названия, что и в v3. Некоторые стандартные поведения изменились — см. Изменения стандартного поведения.

Минимальная версия iOS

Adapty React Native SDK 4.0 повышает минимальную версию iOS с 13.0 до iOS 15.0. Перед обновлением установите значение deployment target не ниже 15.0.

Установка

Обновите пакет

v4.0 — это предварительный релиз, поэтому укажите точную версию — npm не выбирает предварительные версии через диапазоны с ^ или ~:

npm install react-native-adapty@4.0.0
# or
yarn add react-native-adapty@4.0.0

iOS: нативные SDK теперь подключаются через Swift Package Manager

Репозиторий спецификаций CocoaPods переходит в режим только для чтения в декабре 2026 года, поэтому начиная с v4 нативные SDK Adapty, AdaptyUI и AdaptyPlugin больше не подключаются как под-зависимости CocoaPods — podspec подтягивает их через Swift Package Manager (с помощью хелпера spm_dependency). Это требует двух вещей:

React Native 0.75 или новее — нужна для вспомогательного подспека spm_dependency. На более старой версии pod install завершится с явной ошибкой; сначала обновите React Native или оставайтесь на react-native-adapty 3.x.
Динамические фреймворки — зависимости SPM требуют динамической компоновки. Способ её включения отличается для Expo и обычного React Native.

Expo

Добавьте конфиг-плагин expo-build-properties и задайте динамическую компоновку iOS-фреймворков в app.json (или app.config.js):

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "useFrameworks": "dynamic"
          }
        }
      ]
    ]
  }
}

Затем установите плагин и пересоздайте нативный проект:

npx expo install expo-build-properties
npx expo prebuild --clean

Bare React Native

Добавьте динамические фреймворки в iOS-таргет, затем переустановите поды:

use_frameworks! :linkage => :dynamic

cd ios && pod install --repo-update

Если ранее вы подключали Adapty, AdaptyUI или AdaptyPlugin как зависимости CocoaPods, сначала удалите все явные строки pod 'Adapty', pod 'AdaptyUI' или pod 'AdaptyPlugin' из вашего Podfile.

Переход со статической компоновки по умолчанию на динамические фреймворки может конфликтовать с библиотеками, которые ещё не поддерживают модульные заголовки, и несовместим с Flipper. Если возникнут ошибки сборки, ознакомьтесь с этим материалом об интеграции Swift Package Manager с библиотеками React Native.

Полная инструкция по установке — в разделе Установка Adapty SDK.

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

getPaywall → getFlow

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

- const paywall = await adapty.getPaywall('YOUR_PLACEMENT_ID', 'en');
+ const flow = await adapty.getFlow('YOUR_PLACEMENT_ID');

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

- const paywall = await adapty.getPaywallForDefaultAudience('YOUR_PLACEMENT_ID', 'en');
+ const flow = await adapty.getFlowForDefaultAudience('YOUR_PLACEMENT_ID');

getPaywallProducts(paywall) → getPaywallProducts(flow)

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

- const products = await adapty.getPaywallProducts(paywall);
+ const products = await adapty.getPaywallProducts(flow);

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

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

поле v3 `AdaptyPaywall`	поле v4 `AdaptyFlow`	Действие
`remoteConfig?` (одно)	`remoteConfigs?: AdaptyRemoteConfig[]` (массив)	Флоу содержит один Remote Config на каждый настроенный язык. Читайте тот, который соответствует пользователю: `flow.remoteConfigs?.find((c) => c.lang === 'en')`.
`products`	`flow.paywalls[i].productIdentifiers`	Идентификаторы продуктов теперь хранятся в каждом варианте флоу, а не в самом флоу.
`webPurchaseUrl?`	`flow.paywalls[i].webPurchaseUrl`	Перенесено из флоу в каждый вариант пейвола.
`version?: number`	`flowVersionId?: string`	Переименовано, тип изменён с `number` на `string`.
`hasViewConfiguration`	удалено	Удалите все проверки `hasViewConfigura��tion` из кода.
`requestLocale`	удалено	Локаль больше не является частью модели.
(новое)	`paywalls: AdaptyFlowPaywall[]`	Каждый элемент — один вариант пейвола во флоу.
(новое)	`responseCreatedAt: number`	Временная метка ответа сервера в миллисекундах.
Product identifiers moved from the flow to each variation:

- const ids = paywall.products;
+ const ids = flow.paywalls[0].productIdentifiers;

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

openWebPaywall и createWebPaywallUrl сохраняют свои названия, но первым аргументом теперь передаётся AdaptyFlowPaywall (вариант флоу) вместо AdaptyPaywall. По-прежнему можно передать AdaptyPaywallProduct.

  const flow = await adapty.getFlow('YOUR_PLACEMENT_ID');
- await adapty.openWebPaywall(paywall);
+ await adapty.openWebPaywall(flow.paywalls[0]);

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

logShowPaywall → logShowFlow

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

- await adapty.logShowPaywall(paywall);
+ await adapty.logShowFlow(flow);

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

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

createPaywallView → createFlowView

Переименуйте фабричную функцию и передайте AdaptyFlow. Методы возвращаемого контроллера (present, dismiss, setEventHandlers, showDialog) остаются без изменений:

- import { createPaywallView } from 'react-native-adapty';
+ import { createFlowView } from 'react-native-adapty';

- const view = await createPaywallView(paywall);
+ const view = await createFlowView(flow);
  await view.present();

AdaptyPaywallView → AdaptyFlowView

Если вы используете React-компонент, переименуйте его и передайте проп flow:

- import { AdaptyPaywallView } from 'react-native-adapty';
+ import { AdaptyFlowView } from 'react-native-adapty';

- <AdaptyPaywallView paywall={paywall} /* … */ />
+ <AdaptyFlowView flow={flow} /* … */ />

Флоу-вью, созданное с помощью createFlowView, является одноразовым: после вызова dismiss() вью уничтожается, поэтому для повторного отображения флоу вызовите createFlowView снова. Встроенное AdaptyFlowView закрывается путём размонтирования — возврат true из обработчика не закрывает встроенное вью, поэтому вместо этого изменяйте собственное состояние, например в onCloseButtonPress.

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

Интерфейс обработчика событий переименован с EventHandlers на FlowEventHandlers, а три колбэка переименованы. Тела существующих обработчиков менять не нужно — просто переименуйте:

- onPaywallShown: () => { /* … */ },
+ onAppeared: () => { /* … */ },

- onPaywallClosed: () => { /* … */ },
+ onDisappeared: () => { /* … */ },

- onRenderingFailed: (error) => { /* … */ },
+ onError: (error) => { /* … */ },

Все остальные обработчики событий сохраняют свои названия. Два из них также получают второй аргумент: onPurchaseCompleted теперь принимает (purchaseResult, product), а onPurchaseFailed — (error, product), где product — это задействованный AdaptyPaywallProduct. Полный список см. в разделе Обработка событий флоу и пейвола.

onDisappeared срабатывает только для флоу, открытого модально через createFlowView().present(). Компонент AdaptyFlowView не предоставляет его как проп — чтобы скрыть встроенное представление, размонтируйте его.

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

Методы adapty.openWebUrl(url, openIn?) и adapty.requestAppReview() — обеспечивают работу стандартных обработчиков onUrlPress и onRequestAppReview, поэтому URL-адреса и запросы на отзыв об приложении обрабатываются нативно «из коробки». Вызывайте их напрямую только если переопределяете эти обработчики.
Обработка покупок в режиме Observer внутри флоу с помощью новых обработчиков onObserverPurchaseInitiated / onObserverRestoreInitiated. См. Обработка покупок в режиме Observer.

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

setFallbackPaywalls → setFallback

setFallbackPaywalls удалён. Используйте setFallback с тем же аргументом:

- await adapty.setFallbackPaywalls(fileLocation);
+ await adapty.setFallback(fileLocation);

Удалённые экспорты

Эти символы больше не экспортируются из react-native-adapty. Удалите их импорты:

AdaptyPaywall: Используйте AdaptyFlow вместо него.
ProductReference: Используйте AdaptyProductIdentifier, считываемый из flow.paywalls[i].productIdentifiers.
AdaptyPaywallBuilder: Удалён. Флоу и пейволы рендерятся нативно.
AdaptyAndroidSubscriptionUpdateParameters: Используйте вложенную форму subscriptionUpdateParams (см. ниже).

activate: lockMethodsUntilReady

lockMethodsUntilReady удалён, и теперь это поведение включено постоянно. Удалите его из вызова activate — иначе код не скомпилируется:

- await adapty.activate('PUBLIC_SDK_KEY', { lockMethodsUntilReady: true });
+ await adapty.activate('PUBLIC_SDK_KEY');

Обновление подписки на Android с помощью makePurchase

Плоская структура параметров обновления подписки на Android удалена. Перенесите oldSubVendorProductId и prorationMode в вложенный объект subscriptionUpdateParams, а isOfferPersonalized оставьте на верхнем уровне. Полный пример см. в разделе Совершение покупок.

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

Булевый ресурс Android <bool name="adapty_paywall_enable_safe_area_paddings">…</bool> удалён. Удалите его из res/values/bools.xml и управляйте отступами безопасной зоны во время выполнения через параметр enableSafeArea при создании представления флоу. По умолчанию он равен true для модального отображения и false для встроенного компонента.

Режим мок-данных

Если вы запускаете SDK в режиме мок-данных (Expo Go или веб-превью), переименуйте ключ мок-конфигурации paywalls в flows.

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

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

onAndroidSystemBack: Поведение по умолчанию изменилось: раньше представление закрывалось, теперь остаётся открытым. Чтобы вернуть прежнее поведение, возвращайте true из обработчика.
onPurchaseCompleted: Поведение по умолчанию изменилось: раньше представление закрывалось (если только пользователь не отменил покупку), теперь всегда остаётся открытым. Чтобы вернуть прежнее поведение, возвращайте purchaseResult.type !== 'user_cancelled' из обработчика.
onRestoreCompleted: Поведение по умолчанию изменилось: раньше представление закрывалось после успешного восстановления покупок, теперь остаётся открытым. Чтобы вернуть прежнее поведение, возвращайте true из обработчика.
onUrlPress: Теперь по умолчанию URL открывается через нативный слой с учётом настройки браузера (встроенный или внешний) из дашборда. Переопределите обработчик, чтобы открывать URL самостоятельно.

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

Устаревший API онбординга помечен как deprecated в v4.0 в пользу Flow Builder. Он продолжает работать, а IDE отмечает устаревшие символы через аннотации @deprecated — никаких предупреждений в рантайме нет. Эти символы будут удалены в будущих версиях, поэтому планируйте перенос ваших онбордингов во Flow Builder.

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