Миграция Adapty React Native SDK на v4.0

Adapty React Native SDK 4.0 вводит флоу и переименовывает 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` — передавайте его в `createFlowView`. Методы представления `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.2
# or
yarn add react-native-adapty@4.0.2

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",
            "buildReactNativeFromSource": true
          }
        }
      ]
    ]
  }
}

buildReactNativeFromSource необходимо указывать на Expo SDK 57 и выше. Expo SDK 57 поставляется с предсобранным фреймворком React Native, заголовки которого недоступны другим пакетам при динамических фреймворках — из-за этого iOS-сборка падает с ошибками вида 'React/RCTBridge.h' file not found в expo-updates или @expo/ui. Сборка React Native из исходников решает эту проблему, но увеличивает время iOS-сборки. На Expo SDK 56 и ниже этот параметр можно не указывать.

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

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.

Warning

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

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

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

getPaywall → getFlow

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

- const paywall = await adapty.getPaywall('YOUR_PLACEMENT_ID', 'en');
+ const flow = await adapty.getFlow('YOUR_PLACEMENT_ID');
+ const view = await createFlowView(flow, { locale: 'en' });

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

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);

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

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

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

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`	удалено	Удалите все проверки `hasViewConfiguration` из кода.
`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} /* … */ />

Note

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

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

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

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

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

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

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

Note

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.