Install & configure Adapty React Native SDK in an Expo project

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

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

Если вам нужен полный туториал по реализации встроенных покупок в React Native-приложении, ознакомьтесь с этим материалом.

Полное пошаговое руководство по реализации также доступно в виде видео:

Требования

Adapty React Native SDK требует iOS 15.0+.

Для сборки под iOS необходим Swift 6.0 или более новая версия. Kids Mode требует Swift 6.1 или более новой версии.

Установка Adapty SDK

1. Установите Adapty SDK (при этом автоматически устанавливается @adapty/core):

   npx expo install react-native-adapty
   npx expo prebuild

2. Соберите приложение для разработки с помощью EAS или локальной сборки:

# For iOS
eas build --profile development --platform ios

# For Android
eas build --profile development --platform android

# For iOS
npx expo run:ios

# For Android
npx expo run:android

3. Запустите dev-сервер:

   npx expo start --dev-client

Adapty SDK 4.0: включение Swift Package Manager

React Native SDK 4.0 — который добавляет поддержку Flow Builder — требует React Native 0.75 или выше. Установите SDK:

npx expo install react-native-adapty@^4.0.0

v4 подключает нативные iOS SDK (Adapty, AdaptyUI, AdaptyPlugin) через Swift Package Manager вместо CocoaPods sub-dependencies (репозиторий спецификаций CocoaPods переходит в режим «только чтение» в декабре 2026 года). SPM требует динамических фреймворков, которые в Expo включаются через плагин expo-build-properties. Добавьте его в app.json (или app.config.js):

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

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

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

См. Миграция Adapty React Native SDK на v4 для полного руководства по миграции.

Активация модуля 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');

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

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

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

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

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

Логирование

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

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

Советы по разработке

Настройка режима заглушки для Expo Go / Expo Web

В Expo Go и Expo Web нет доступа к нативным модулям Adapty. Чтобы избежать ошибок во время выполнения и при этом иметь возможность собирать и тестировать UI приложения и логику пейвола, Adapty предоставляет режим заглушки.

По умолчанию SDK автоматически определяет среды Expo Go и web и включает режим mock. Никакой дополнительной настройки не требуется — если только вы не хотите изменить mock-данные.

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

• Все методы Adapty возвращают mock-данные, не отправляя запросы на серверы Adapty.
• По умолчанию исходный mock-профиль не имеет активных подписок.
• По умолчанию makePurchase(...) симулирует успешную покупку и предоставляет премиум-доступ. Вы можете настроить мок-данные с помощью 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');

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

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

Однако в симуляторе 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
}

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

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

При сборке для iOS может появиться ошибка о минимальной версии iOS или deployment target. Adapty требует iOS 15.0+.

Поскольку Expo генерирует iOS-проект (включая Podfile) во время выполнения expo prebuild, не редактируйте Podfile напрямую. Вместо этого настройте deployment target через config-плагин expo-build-properties.

1. Установите плагин:

   npx expo install expo-build-properties

2. Обновите конфигурацию Expo (app.json или app.config.js), указав iOS deployment target:

{
    "expo": {
        // ...other Expo config...
        "plugins": [
            [
                "expo-build-properties",
                {
                    "ios": {
                        // Adapty requires iOS 15.0+.
                        "deploymentTarget": "15.0"
                    }
                }
            ],
        ]
    }
}

3. Пересоздайте нативный iOS-проект и выполните сборку:

npx expo prebuild --clean
npx expo run:ios      # или `eas build -p ios` на вашем CI

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

Когда вы используете Expo с несколькими SDK, которые настраивают Android Auto Backup (например, Adapty, AppsFlyer или expo-secure-store), может возникнуть конфликт при слиянии манифестов.

Типичная ошибка выглядит так: Manifest merger failed : Attribute application@fullBackupContent value=(@xml/secure_store_backup_rules) from AndroidManifest.xml:24:248-306 is also present at [io.adapty:android-sdk:3.12.0] AndroidManifest.xml:9:18-70 value=(@xml/adapty_backup_rules). Чтобы решить этот конфликт, нужно разрешить плагину Adapty управлять конфигурацией резервного копирования Android. Если в вашем проекте также используется expo-secure-store, отключите его собственную настройку резервного копирования, чтобы избежать конфликта.

Вот как настроить app.json:

{
  "expo": {
    "plugins": [
      ["react-native-adapty", { "replaceAndroidBackupConfig": true }],
      ["expo-secure-store", { "configureAndroidBackup": false }]
    ]
  }
}

Опция replaceAndroidBackupConfig по умолчанию имеет значение false. При включении она позволяет плагину Adapty управлять правилами резервного копирования Android. Добавьте "configureAndroidBackup": false, если вы используете expo-secure-store, чтобы избежать предупреждений — настройка резервного копирования SecureStore теперь будет выполняться через Adapty.