Adapty Capacitor SDK 4.1.1 — это текущий стабильный релиз ветки 4.x. Версия 4.0 вышла только в бета, поэтому если вы используете 3.x, переходите сразу на 4.1.1. Этот гайд охватывает полную миграцию: флоу, появившиеся в 4.0, и изменения, добавленные в 4.1.1.

Версия 4.x вводит флоу и соответствующим образом переименовывает API пейволов. Новые API работают с флоу и по-прежнему работают с пейволами из старого билдера — никаких изменений в настройках дашборда Adapty не требуется. Помимо этого, версия 4.1.1 переводит Adapty Attribution в режим opt-in, переименовывает метод внешней атрибуции, изменяет формат резервного файла и добавляет поддержку продвигаемых встроенных покупок в App Store.

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

v3	v4.1.1
Adapty Attribution включена автоматически	отключена по умолчанию — включите с помощью adaptyAttributionEnabled: true
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 + AdaptyFlowPaywall
createPaywallView(paywall, params?)	createFlowView(flow, params?)
PaywallViewController	FlowViewController
EventHandlers (тип)	FlowEventHandlers
CreatePaywallViewParamsInput	CreateFlowViewParamsInput
onRenderingFailed	onError
adapty.updateAttribution({ attribution, source })	adapty.updateExternalAttribution({ attribution, provider })
AdaptyProfile.appliedAttributionSources	AdaptyProfile.appliedExternalAttributionProviders
AttributionSource	AdaptyExternalAttributionProvider
Файл резервного пейвола для версии 3.x	новый формат файла резервного пейвола — скачайте файл заново
Встроенные покупки через промо завершались автоматически без возможности перехватить	событие 'onPromotedPurchaseReceived' и adapty.makePromotedPurchase({ product }) передают управление завершением в ваше приложение

AdaptyPaywallProduct сохраняет своё название — продукты по-прежнему принадлежат флоу, и getPaywallProducts тоже сохраняет название, теперь принимая AdaptyFlow. Методы getFlow и getFlowForDefaultAudience больше не принимают параметр locale — передавайте его в createFlowView. API покупок и профилей (makePurchase, restorePurchases, getProfile, identify, updateProfile) и setFallback сохраняют прежние сигнатуры, однако сам файл резервного пейвола нужно скачать заново — см. Резервные файлы. Методы представления present, dismiss, setEventHandlers, clearEventHandlers и showDialog, а также обработчики событий onCloseButtonPress, onUrlPress, onCustomAction, onProductSelected, onPurchaseStarted, onPurchaseCompleted, onPurchaseFailed, onRestoreStarted, onRestoreCompleted, onRestoreFailed, onLoadingProductsFailed, onWebPaymentNavigationFinished и onAndroidSystemBack сохраняют те же названия, что и в v3. Методы онбординга по-прежнему работают, но считаются устаревшими — см. Устаревание Onboarding API. Некоторые поведения по умолчанию изменились — см. Изменения поведения по умолчанию.

Минимальные версии

Требования к среде выполнения не изменились по сравнению с v3.16+: iOS 15.0, Android minSdk 24 и Capacitor 8. Изменения deployment target не требуются.

Появилось одно новое требование к сборке: Xcode 26 или новее — нативный iOS SDK Adapty, входящий в этот релиз, использует Swift tools 6.2.

Установка

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

npm install @adapty/capacitor@latest

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

npx cap sync

iOS: только Swift Package Manager

Репозиторий спецификаций CocoaPods станет доступен только для чтения в декабре 2026 года, поэтому начиная с v4 файл AdaptyCapacitor.podspec удалён, и SDK устанавливается на iOS только через Swift Package Manager (SPM). iOS-проект вашего приложения должен использовать интеграцию Capacitor с SPM:

• Новые приложения: добавьте iOS-платформу с менеджером пакетов SPM:

npx cap add ios --packagemanager SPM

• Для существующих приложений на базе CocoaPods: перенесите iOS-проект, следуя руководству Capacitor по использованию SPM в существующем проекте.

Подробнее об установке см. в Установке Adapty SDK.

⚠️ Атрибуция Adapty отключена по умолчанию

В более ранних версиях SDK автоматически регистрировал установки для Атрибуции Adapty. Начиная с версии SDK 4.1.1, это отключено по умолчанию: SDK не регистрирует установки, события 'onInstallationDetailsSuccess' и 'onInstallationDetailsFail' не срабатывают, а getCurrentInstallationStatus возвращает статус not_available.

Если вы используете Атрибуцию Adapty, включите её при активации SDK:

  await adapty.activate({
    apiKey: 'YOUR_PUBLIC_SDK_KEY',
    params: {
+     adaptyAttributionEnabled: true,
    },
  });

Если вы не используете атрибуцию Adapty, никаких изменений не требуется.

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

getPaywall → getFlow

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

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

locale остаётся необязательным в createFlowView: если его не указать, представление отрисуется на en, или на языке по умолчанию флоу, если en в нём нет. Из-за этой логики фолбэка представление может отрисоваться на другой локализации, чем вы запрашивали, — новое свойство FlowViewController.locale сообщает, какая именно была использована. См. Локализации и коды локалей.

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

- const paywall = await adapty.getPaywallForDefaultAudience({ placementId: 'YOUR_PLACEMENT_ID', locale: 'en' });
+ const flow = await adapty.getFlowForDefaultAudience({ placementId: 'YOUR_PLACEMENT_ID' });

getPaywallProducts(paywall) → getPaywallProducts(flow)

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

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

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

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

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

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

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

requestLocale остаётся в AdaptyOnboarding — из модели флоу он убран.

Идентификаторы продуктов перенесены из флоу в каждый вариант:

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

Если ваш код ещё читает paywall.products — это свойство было помечено устаревшим в v3 и теперь удалено — перейдите на productIdentifiers или вызовите getPaywallProducts(flow), если нужны полные данные о продуктах, а не только идентификаторы.

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

openWebPaywall и createWebPaywallUrl сохраняют свои названия, но опция paywallOrProduct теперь принимает AdaptyFlowPaywall (вариант флоу) вместо AdaptyPaywall. По-прежнему можно передать AdaptyPaywallProduct. Перед обращением к первому элементу убедитесь, что flow.paywalls не пустой:

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

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

logShowPaywall → logShowFlow

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

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

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

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

createPaywallView → createFlowView

Переименуйте фабричную функцию и передайте AdaptyFlow. Возвращаемый контроллер переименован с PaywallViewController на FlowViewController, но его методы (present, dismiss, setEventHandlers, clearEventHandlers и showDialog) остались прежними. Тип параметров переименован с CreatePaywallViewParamsInput на CreateFlowViewParamsInput:

- import { createPaywallView } from '@adapty/capacitor';
+ import { createFlowView } from '@adapty/capacitor';

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

Новые параметры

CreateFlowViewParamsInput сохраняет все параметры v3 (prefetchProducts, loadTimeoutMs, customTags, customTimers, customAssets, productPurchaseParams) и добавляет три новых:

Параметр	Описание
locale	Локализация, с которой будет отображаться флоу. Параметр перенесён сюда из getPaywall — см. getPaywall → getFlow.
customLayoutId	Пользовательский ID лейаута в конфигурации лейаутов флоу. Передайте его, чтобы отобразить конкретный лейаут вместо того, который SDK выбирает автоматически на основе типа устройства и размера экрана. Если лейаут с указанным ID не найден, вызов завершится ошибкой отсутствия конфигурации представления. Flow & Paywall Builder пока не назначает пользовательские ID лейаутов, поэтому оставьте этот параметр пустым.
android.enableSafeArea	Управляет отступами безопасной зоны на Android в режиме выполнения. Находится внутри ключа android, по умолчанию равно true.

const view = await createFlowView(flow, {
  locale: 'en',
  customLayoutId: 'tablet_landscape',
  android: { enableSafeArea: true },
});

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

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

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

Все остальные обработчики событий сохраняют свои имена. У одного изменилась сигнатура: onAppeared теперь принимает (view) вместо (), где view — это FlowEventView, описывающий появившееся представление, включая локализацию, с которой оно было построено. Существующие обработчики продолжат работать, так как игнорируют новый аргумент. Полный список см. в разделе Обработка событий флоу и пейвола.

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

• adapty.openWebUrl({ url, openIn }) и adapty.requestAppReview() — эти методы обеспечивают работу стандартных обработчиков onUrlPress и onRequestAppReview, поэтому URL-адреса и запросы на оценку приложения обрабатываются нативно из коробки. Вызывайте их напрямую только если переопределяете эти обработчики.
• Обработка покупок в режиме Observer внутри флоу с помощью новых обработчиков onObserverPurchaseInitiated / onObserverRestoreInitiated. См. Показ флоу в режиме Observer.
• onAnalytics: (name, params) — аналитические события, которые генерирует флоу, начиная с просмотра экрана для каждого открытого пользователем экрана. См. Отслеживание просмотров экранов флоу.
• onRequestPermission: (permission, customArgs) — зарезервировано для запросов системных разрешений (например, push-уведомления или доступ к камере) из флоу. Флоу пока не инициируют запросы разрешений, поэтому реализовывать этот обработчик не нужно.

Отдельно отметим: в версии 4.1.1 добавлено событие на уровне SDK, а не обработчик флоу — 'onPromotedPurchaseReceived', доставляемое через adapty.addListener. Если слушатель не зарегистрирован, SDK завершает promoted-покупку самостоятельно; если зарегистрирован — управление передаётся вашему приложению. См. App Store promoted in-app purchases.

Переименованные внешние API атрибуции

Начиная с версии SDK 4.1.1, API для передачи данных атрибуции от внешнего провайдера (Adjust, AppsFlyer, Branch, Tenjin или кастомного) переименованы в соответствии с нативными SDK. Устаревших алиасов нет, поэтому существующие вызовы перестанут работать, пока вы их не переименуете:

До 4.1.1	4.1.1
adapty.updateAttribution({ attribution, source })	adapty.updateExternalAttribution({ attribution, provider })
AttributionSource	AdaptyExternalAttributionProvider
AdaptyProfile.appliedAttributionSources	AdaptyProfile.appliedExternalAttributionProviders

updateAttribution → updateExternalAttribution

Метод переименован, а его опция source стала provider. Данные атрибуции по-прежнему передаются в виде обычного объекта:

- await adapty.updateAttribution({ attribution, source: 'adjust' });
+ await adapty.updateExternalAttribution({ attribution, provider: 'adjust' });

AttributionSource → AdaptyExternalAttributionProvider

Тип провайдера переименован. Он остаётся открытым объединением — предопределённые значения: 'apple_search_ads', 'adjust', 'appsflyer', 'branch' и 'tenjin'; любая другая строка также принимается, поэтому провайдер, добавленный Adapty позже, будет работать без обновления SDK:

- import type { AttributionSource } from '@adapty/capacitor';
+ import type { AdaptyExternalAttributionProvider } from '@adapty/capacitor';

AdaptyProfile.appliedAttributionSources → appliedExternalAttributionProviders

Свойство профиля, которое перечисляет провайдеры атрибуции, применённые к профилю, переименовано, и тип его элементов изменился соответственно:

- if (profile.appliedAttributionSources?.includes('apple_search_ads')) {
+ if (profile.appliedExternalAttributionProviders?.includes('apple_search_ads')) {
      // Apple Ads attribution has been applied
  }

Код, который читает это свойство, нужно обновить — см. Показ пейвола с таргетингом Apple Ads.

Promoted in-app purchases в App Store

До версии 4.1.1 встроенная покупка, продвигаемая на странице продукта в App Store, завершалась самостоятельно и Adapty фиксировал транзакцию, но у приложения не было возможности перехватить её. В версии 4.1.1 добавлен соответствующий хук — это новая возможность, а не шаг миграции: без собственного кода SDK по-прежнему самостоятельно завершает продвигаемые покупки.

Напишите собственный код для обработки промо-покупки — например, чтобы сначала показать экран. Зарегистрируйте обработчик события 'onPromotedPurchaseReceived' и завершите покупку через adapty.makePromotedPurchase. Пока этот обработчик зарегистрирован, SDK не будет автоматически завершать промо-покупки.

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

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

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

Удалённые API

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

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

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

activate: lockMethodsUntilReady

lockMethodsUntilReady (уже устаревший no-op в v3) удалён. Уберите его из вызова activate — с ним код больше не компилируется:

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

makePurchase: параметры Android

Устаревший плоский Android-формат MakePurchaseParamsInput удалён — теперь используется только вложенная форма. Перенесите все параметры Android-покупки в params: { android: { ... } }. Полный пример см. в разделе Совершение покупок.

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

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

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