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

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

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

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

Для полного пошагового разбора реализации можно также посмотреть видео:

Требования

Зависимости

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

Установка Adapty SDK

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

1. Установите Adapty SDK:

   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 v4

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

npx expo install react-native-adapty@^4.0.0

v4 загружает нативные iOS-библиотеки (Adapty, AdaptyUI, AdaptyPlugin) как Swift-пакеты вместо CocoaPods-зависимостей (репозиторий спецификаций CocoaPods переходит в режим «только чтение» в декабре 2026 года). Swift-пакеты линкуются динамически, а в 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

Если после этого сборка iOS завершается ошибкой 'React/RCTBridge.h' file not found, см. соответствующий раздел устранения неполадок.

Подробнее о переходе см. в разделе Миграция 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');

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

• Если вы используете Flow & Paywall Builder, следуйте quickstart.
• Если вы создаёте собственный интерфейс пейвола, смотрите 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

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

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
   adaptyAttributionEnabled: 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.

Сборка iOS завершается с ошибкой 'React/RCTBridge.h' file not found

При включённых динамических фреймворках для Adapty SDK v4 сборка iOS может завершиться с ошибкой в expo-updates, @expo/ui или другом пакете с Objective-C-источниками:

error: 'React/RCTBridge.h' file not found

Ошибка вызвана багом в пакете expo-modules-autolinking (зависимость expo). Затронуты версии 57.0.5–57.0.9 (Expo SDK 57) и 56.0.19–56.0.21 (Expo SDK 56); баг исправлен в версиях 57.0.10 и 56.0.22.

Чтобы исправить сборку, обновите expo-modules-autolinking до исправленной версии и пересоздайте нативный проект:

npm update expo-modules-autolinking
npx expo prebuild

Если исправленная версия ещё недоступна для вашего Expo SDK, соберите React Native из исходников. Это обходит баг, но увеличивает время iOS-сборок:

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