Установка и настройка Adapty SDK в чистом React Native проекте

Adapty SDK включает два ключевых модуля для бесшовной интеграции в ваше приложение React Native:

• Core Adapty: этот модуль необходим для корректной работы Adapty в вашем приложении.
• AdaptyUI: этот модуль отображает флоу, а также пейволы старого билдера. AdaptyUI активируется автоматически вместе с основным модулем.

Требования

Зависимости

Adapty SDK работает со следующими версиями Google Play Billing Library на Android:

Установка Adapty SDK

Мы всегда рекомендуем устанавливать последнюю доступную версию SDK — в ней содержатся актуальные исправления и улучшения.

Добавьте пакет в свой проект:

# using npm
npm install react-native-adapty

# or using yarn
yarn add react-native-adapty

Настройка iOS-проекта

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

• CocoaPods (по умолчанию, SDK 4.0 и выше): Ваш iOS-проект сохраняет Podfile, а хелпер spm_dependency из React Native добавляет Swift-пакеты Adapty в Pods-проект. Swift-пакеты линкуются динамически, поэтому в Podfile нужно переключиться на динамические фреймворки.
• SPM-интеграция React Native (SDK 4.1 и выше): Ваш iOS-проект отказывается от CocoaPods, и React Native самостоятельно разрешает Swift-пакеты из манифеста Package.swift, поставляемого с Adapty. React Native добавил эту интеграцию в версии 0.87 как превью — для продакшена она пока не рекомендуется.

use_frameworks! :linkage => :dynamic

cd ios && pod install --repo-update

cd ios && npx react-native spm

Активация модуля Adapty в SDK

Чтобы получить Public SDK Key:

1. Откройте дашборд Adapty и перейдите в App settings → General.
2. В разделе Api keys скопируйте Public SDK Key (НЕ Secret Key).
3. Замените "YOUR_PUBLIC_SDK_KEY" в коде.

Или получите его программно с помощью Adapty CLI:

npm install -g adapty
adapty auth login
adapty apps list

Или напрямую:

npx adapty auth login
adapty apps list

• Убедитесь, что для инициализации Adapty вы используете Public SDK key — Secret key предназначен только для серверного API.
• SDK-ключи уникальны для каждого приложения, поэтому если у вас несколько приложений, выберите нужный ключ.

Скопируйте следующий код в App.tsx, чтобы активировать Adapty:

adapty.activate('YOUR_PUBLIC_SDK_KEY');

Теперь настройте пейволы в вашем приложении:

• Если вы используете Flow & Paywall Builder, следуйте quickstart.
• Если вы создаёте собственный UI пейвола, см. quickstart для кастомных пейволов.

Активация модуля AdaptyUI SDK Adapty

Если вы планируете использовать Flow & Paywall Builder, вам понадобится модуль AdaptyUI. Он активируется автоматически вместе с основным модулем — никаких дополнительных действий не требуется.

Дополнительная настройка

Логирование

Настройка системы логирования

Adapty записывает ошибки и другую важную информацию, чтобы вы понимали, что происходит. Доступны следующие уровни логирования:

Вы можете задать уровень логирования в приложении до или во время конфигурации Adapty:

// Set log level before activation
// 'verbose' is recommended for development and the first production release
adapty.setLogLevel('verbose');

// Or set it during configuration
adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  logLevel: 'verbose',
});

Политики данных

Adapty не хранит личные данные пользователей, если вы явно их не передаёте. Однако вы можете настроить дополнительные политики безопасности данных для соответствия требованиям стора или законодательству конкретной страны.

Отключение сбора и передачи IP-адресов

При активации модуля Adapty установите ipAddressCollectionDisabled в значение true, чтобы отключить сбор и передачу IP-адресов пользователей. Значение по умолчанию — false.

Используйте этот параметр для защиты конфиденциальности пользователей, соблюдения региональных требований законодательства о защите данных (например, GDPR или CCPA), а также для сокращения избыточного сбора данных, когда функции на основе IP-адреса не нужны в вашем приложении.

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  ipAddressCollectionDisabled: true,
});

Отключить сбор и передачу рекламного идентификатора

При активации модуля Adapty установите ios.idfaCollectionDisabled (iOS) или android.adIdCollectionDisabled (Android) в значение true, чтобы отключить сбор рекламных идентификаторов. Значение по умолчанию — false.

Используйте этот параметр для соблюдения требований App Store/Play Store, чтобы не вызывать запрос App Tracking Transparency, или если ваше приложение не использует атрибуцию рекламы или аналитику на основе рекламных идентификаторов.

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  ios: {
    idfaCollectionDisabled: true,
  },
  android: {
    adIdCollectionDisabled: true,
  },
});

Настройте конфигурацию медиакеша для AdaptyUI

По умолчанию AdaptyUI кэширует медиафайлы (изображения и видео) для повышения производительности и снижения сетевой нагрузки. Вы можете настроить параметры кеширования, передав собственную конфигурацию.

Используйте mediaCache, чтобы переопределить настройки кеша по умолчанию:

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  mediaCache: {
    memoryStorageTotalCostLimit: 200 * 1024 * 1024, // Optional: memory cache size in bytes
    memoryStorageCountLimit: 2147483647,            // Optional: max number of items in memory
    diskStorageSizeLimit: 200 * 1024 * 1024,       // Optional: disk cache size in bytes
  },
});

Включение локальных уровней доступа (Android)

По умолчанию локальные уровни доступа включены на iOS и отключены на Android. Чтобы включить их на Android, установите localAccessLevelAllowed в true:

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  android: {
     localAccessLevelAllowed: true,
  },
});

Очистка данных при восстановлении из резервной копии

Если clearDataOnBackup установлен в true, SDK определяет, когда приложение восстановлено из резервной копии iCloud, и удаляет все локально сохранённые данные SDK: кешированную информацию профиля, данные о продуктах и пейволы. После этого SDK инициализируется с чистого состояния. Значение по умолчанию — false.

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
   ios: {
      clearDataOnBackup: true
   },
});

Включить Adapty Attribution

Если вы используете Adapty Attribution, установите adaptyAttributionEnabled в true при активации SDK. Значение по умолчанию — false: без этого параметра SDK не регистрирует установки и не передаёт данные об установке в ваше приложение. В версиях SDK ниже 4.1 Adapty Attribution включается автоматически.

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
   adaptyAttributionEnabled: true,
});

Советы для среды разработки

Отложите активацию SDK в целях разработки

При активации SDK Adapty заранее загружает все необходимые данные о пользователе, чтобы обеспечить быстрый доступ к актуальной информации.

Однако в симуляторе iOS это может создавать неудобства: в процессе разработки симулятор часто запрашивает аутентификацию. Adapty не управляет процессом аутентификации StoreKit, но может отложить запросы SDK на получение свежих данных о пользователе.

Включив свойство __debugDeferActivation, вы откладываете вызов активации до следующего обращения к Adapty SDK. Это позволяет избежать лишних запросов аутентификационных данных, если они не нужны.

Важно учитывать, что эта функция предназначена только для разработки, поскольку не охватывает все возможные сценарии использования. В продакшене откладывать активацию не следует: реальные устройства, как правило, сохраняют аутентификационные данные и не запрашивают учётные данные повторно.

Рекомендуемый подход к использованию:

try {
  adapty.activate('PUBLIC_SDK_KEY', {
    __debugDeferActivation: isSimulator(), // 'isSimulator' from any 3rd party library
  });
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
  // Handle the error appropriately for your app
}

Устранение ошибок активации SDK при Fast Refresh в React Native

При разработке с Adapty SDK в React Native вы можете столкнуться с ошибкой: Adapty can only be activated once. Ensure that the SDK activation call is not made more than once.

Это происходит потому, что функция быстрого обновления (fast refresh) в React Native вызывает несколько активаций во время разработки. Чтобы этого избежать, используйте опцию __ignoreActivationOnFastRefresh со значением __DEV__ (флаг режима разработки в React Native).

try {
  adapty.activate('PUBLIC_SDK_KEY', {
    __ignoreActivationOnFastRefresh: __DEV__,
  });
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
  // Handle the error appropriately for your app
}

Настройка mock-режима для локального тестирования

Для локальной разработки и тестирования можно включить mock-режим, чтобы не использовать аккаунты песочницы App Store/Google Play и ускорить итерации. Mock-режим полностью обходит нативные модули Adapty и возвращает симулированные данные.

Чтобы включить mock-режим, установите enableMock в true:

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  enableMock: true,
});

Когда активен режим mock:

• Все методы Adapty возвращают mock-данные без сетевых запросов к серверам Adapty.
• По умолчанию исходный mock-профиль не имеет активных подписок.
• По умолчанию makePurchase(...) симулирует успешную покупку и предоставляет премиум-доступ.

Вы можете настроить mock-данные с помощью mockConfig при активации. Формат конфига и поддерживаемые параметры описаны здесь.

try {
   await adapty.activate('YOUR_PUBLIC_SDK_KEY', {
      mockConfig: {
         // Customize the initial mock profile (optional)
      },
   });
} catch (error) {
   console.error('Failed to activate Adapty SDK:', error);
}

Если вам нужно вызвать методы SDK до активации (например, isActivated() или setLogLevel()), используйте enableMock() перед activate(). Если мост уже инициализирован, этот метод ничего не делает.

adapty.enableMock(); // Optional: pass mockConfig to customize mock data

// Now you can call methods before activation

await adapty.activate('YOUR_PUBLIC_SDK_KEY');

Устранение неполадок

Ошибка минимальной версии iOS

Если вы получаете ошибку минимальной версии iOS, обновите Podfile:

-platform :ios, min_ios_version_supported
+platform :ios, '15.0'

Конфликт манифеста Android Auto Backup

Некоторые SDK (включая Adapty) поставляются с собственной конфигурацией Android Auto Backup. Если вы используете несколько SDK, каждый из которых определяет правила резервного копирования, слияние манифестов Android может завершиться с ошибкой, связанной с android:fullBackupContent, android:dataExtractionRules или android:allowBackup.

Типичные симптомы ошибки: Manifest merger failed: Attribute application@dataExtractionRules value=(@xml/your_data_extraction_rules) is also present at [com.other.sdk:library:1.0.0] value=(@xml/other_sdk_data_extraction_rules)

Чтобы решить эту проблему, нужно:

• Указать слиянию манифестов использовать значения вашего приложения для атрибутов, связанных с резервным копированием.

• Создать файлы правил резервного копирования, которые объединяют правила Adapty с правилами других SDK.

1. Добавьте пространство имён tools в манифест

В файле AndroidManifest.xml убедитесь, что корневой тег <manifest> содержит tools:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.example.app">

    ...
</manifest>

2. Переопределите атрибуты резервного копирования в <application>

В том же файле AndroidManifest.xml обновите тег <application>, чтобы ваше приложение задавало финальные значения и указывало слиянию манифестов заменять значения библиотек:

<application
android:name=".App"
android:allowBackup="true"
android:fullBackupContent="@xml/sample_backup_rules"           
android:dataExtractionRules="@xml/sample_data_extraction_rules"
tools:replace="android:fullBackupContent,android:dataExtractionRules">

    ...
</application>

Если какой-либо SDK также задаёт android:allowBackup, добавьте его в tools:replace:

tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules"

3. Создайте объединённые файлы правил резервного копирования

Создайте XML-файлы в директории res/xml/ вашего Android-проекта, объединив правила Adapty с правилами других SDK. Android использует разные форматы правил резервного копирования в зависимости от версии ОС, поэтому создание обоих файлов обеспечивает совместимость со всеми версиями Android, которые поддерживает ваше приложение.

Для Android 12 и выше (используется новый формат правил извлечения данных):

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </cloud-backup>

    <device-transfer>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </device-transfer>
</data-extraction-rules>

Для Android 11 и ниже (используется устаревший формат полного резервного копирования):

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    
    <exclude domain="sharedpref" path="appsflyer-data"/>

    
    <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>

    

Покупки не завершаются после возврата из другого приложения на Android

Если Activity, запускающий флоу покупки, использует нестандартный launchMode, Android может некорректно пересоздать или повторно использовать его, когда пользователь возвращается из Google Play, банковского приложения или браузера. Это может привести к тому, что результат покупки будет потерян или расценён как отменённый.

Чтобы покупки работали корректно, используйте только режимы запуска standard или singleTop для Activity, которая инициирует флоу покупки, и избегайте любых других режимов.

В файле AndroidManifest.xml убедитесь, что Activity, запускающая флоу покупки, имеет режим standard или singleTop:

<activity
    android:name=".MainActivity"
    android:launchMode="standard" />

Ошибка версии плагина Kotlin Gradle в React Native ниже 0.73

На React Native ранее версии 0.73.0 сборка Android завершается с ошибкой из-за версии Kotlin Gradle plugin. Обновите файл /android/build.gradle. Убедитесь, что в нём есть зависимость kotlin-gradle-plugin:1.8.0 или более новая:

...
buildscript {
  ...
  dependencies {
    ...
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0"
  }
}
...

Ошибки сборки Swift 6, вызванные переопределением SWIFT_VERSION в Podfile

При сборке React Native-приложения для iOS могут возникать ошибки компиляции Swift 6 в целевых объектах подов Adapty. Типичные признаки: несоответствия @Sendable в AdaptyUIBuilderLogic, отсутствующее соответствие Sendable у типов Adapty или ошибки изоляции акторов.

Поды Adapty объявляют s.swift_version = '6.0' и требуют Swift 6 для сборки. Код вашего приложения может оставаться на Swift 5 — только целевые поды Adapty (Adapty, AdaptyUI, AdaptyUIBuilder, AdaptyLogger, AdaptyPlugin) должны собираться с Swift 6.

Наиболее распространённая причина — хук post_install в ios/Podfile, который перезаписывает SWIFT_VERSION для каждого подового таргета:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_VERSION'] = '5.9'
    end
  end
end

Исправление: Исключите pod-таргеты Adapty из переопределения:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    next if %w[Adapty AdaptyUI AdaptyUIBuilder AdaptyLogger AdaptyPlugin].include?(target.name)
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_VERSION'] = '5.9'
    end
  end
end

Затем выполните pod install из директории ios/ и пересоберите проект.

Чтобы проверить, откройте ios/Pods/Pods.xcodeproj, выберите pod-таргет Adapty → Build Settings → Swift Language Version. Там должно быть указано Swift 6.