React Native - Adapty SDK installation & configuration

Learn how to install and configure Adapty SDK and AdaptyUI SDK for React Native, essential for seamless integration of Adapty into your mobile app

Adapty comprises two crucial SDKs for seamless integration into your mobile app:

  • Core AdaptySDK: This is a fundamental, mandatory SDK necessary for the proper functioning of Adapty within your app.
  • AdaptyUI SDK: This optional SDK becomes necessary if you use the Adapty Paywall builder: a user-friendly, no-code tool for easily creating cross-platform paywalls. These paywalls are built in a visual constructor right in our dashboard, run entirely natively on the device, and require minimal effort from you to create something that performs well.


Go through release checklist before releasing your app

Before releasing your application, make sure to carefully review the Release Checklist thoroughly. This checklist ensures that you've completed all necessary steps and provides criteria for evaluating the success of your integration.

Install Adapty SDKs

Currently, React Native provides two development paths: Expo and Pure React Native. Adapty seamlessly integrates with both. Please refer to the section below that matches your chosen setup.

Install Adapty SDKs for Expo React Native

You can streamline your development process with Expo Application Services (EAS). While configuration may vary based on your setup, here you'll find the most common and straightforward setup available:

  1. If you haven't installed the EAS Command-Line Interface (CLI) yet, you can do so by using the following command:
npm install -g eas-cli
  1. In the root of your project, install the dev client to make a development build:
expo install expo-dev-client
  1. Run the installation command:
expo install react-native-adapty
expo install @adapty/react-native-ui
  1. For iOS: Make an iOS build with EAS CLI. This command may prompt you for additional info. You can refer to expo official documentation for more details:
eas build --profile development --platform ios
  1. For Android: Make an Android build with EAS CLI. This command may prompt you for additional info. You can refer to expo official documentation for more details:
eas build --profile development --platform android
  1. Start a development server with the following command:
expo start --dev-client

This should result in the working app with react-native-adapty.

Possible errors:

Failed to start (Invariant Violation: Native module cannot be null)if you scan a QR code from a CLI dev client it might lead you to this error. To resolve it you can try the following:

> On your device open EAS built app (it should provide some Expo screen) and manually insert the URL that Expo provides (screenshot below). You can unescape special characters in URL with the JS function unescape(“string”), which should result in something like

Install Adapty SDKs with Pure React Native

If you opt for a purely native approach, please consult the following instructions:

  1. In your project, run the installation command:
yarn add react-native-adapty
yarn add @adapty/react-native-ui
  1. For iOS: Install required pods:
pod install --project-directory=ios
pod install --project-directory=ios/

The minimal supported iOS version is 13.0. If you encounter an error during pod installation, locate this line in yourios/Podfile and update the minimal target. Tand update the minimum target. Afterward, you should be able to successfully execute pod install.

-platform :ios, min_ios_version_supported
+platform :ios, 13.0
  1. For Android: Update the /android/build.gradle file. Make sure there is the kotlin-gradle-plugin:1.8.0 dependency or a newer one:
buildscript {
  dependencies {
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0"

Configure Adapty SDKs

To use Adapty SDKs, import adapty and invoke activate in your core component such as App.tsx. Preferably, position the activation before the React component to ensure no other Adapty calls occur before the activation.

import { adapty } from 'react-native-adapty';


const App = () => {
	// ...

You can pass several optional parameters during activation:

adapty.activate('PUBLIC_SDK_KEY', {
  observerMode: false,
  customerUserId: 'YOUR_USER_ID',
  logLevel: 'error',
  __debugDeferActivation: false,
  ipAddressCollectionDisabled: false,
  ios: {
    idfaCollectionDisabled: false,
import { IosStorekit2Usage, LogLevel } from 'react-native-adapty';

adapty.activate('PUBLIC_SDK_KEY', {
  observerMode: false,
  customerUserId: 'YOUR_USER_ID',
  logLevel: LogLevel.ERROR,
  __debugDeferActivation: false,
  ipAddressCollectionDisabled: false,
  ios: {
    idfaCollectionDisabled: false,

Activation parameters:

PUBLIC_SDK_KEYrequiredA Public SDK Key is the unique identifier used to integrate Adapty into your mobile app. You can copy it in the Adapty Dashboard: App settings -> General tab -> API Keys section.
SDK keys are unique for every app, so if you have multiple apps make sure you choose the right one.
Make sure you use the Public SDK key for the Adapty initialization, since the Secret key should be used for the server-side API only.
observerModeoptionalA boolean value controlling Observer mode . Turn it on if you handle purchases and subscription status yourself and use Adapty for sending subscription events and analytics. The default value is false.

🚧 When running in Observer mode, Adapty SDK won't close any transactions, so make sure you're handling it.
customerUserIdoptionalAn identifier of a user in your system. We send it with subscription and analytical events, so we can match events to the right user profile. You can also find customers using the customerUserId in the Profiles section.

If you don't have a user ID when you start with Adapty, you can add it later using the adapty.identify() method. For more details, see the Identifying users section.
logLeveloptionalA string parameter that makes Adapty record errors and other important information to help you understand what's happening.
__debugDeferActivationoptionalA boolean parameter, that lets you delay SDK activation until your next Adapty call. This is intended solely for development purposes and should not be used in production.
ipAddressCollectionDisabledoptionalSet to true to disable user IP address collection and sharing.
The default value is false.
idfaCollectionDisabledoptionalA boolean parameter, that allows you to disable IDFA collection for your iOS app. The default value is false. For more details, refer to the Analytics integration section.

Please keep in mind that for paywalls and products to be displayed in your mobile application, and for analytics to work, you need to display the paywalls and, if you're using paywalls not created with the Paywall Builder, handle the purchase process within your app.

Set up the logging system

Adapty logs errors and other crucial information to provide insight into your app's functionality. There are the following available levels:

errorOnly errors will be logged.
warnErrors and messages from the SDK that do not cause critical errors, but are worth paying attention to will be logged.
infoErrors, warnings, and serious information messages, such as those that log the lifecycle of various modules will be logged.
verboseAny additional information that may be useful during debugging, such as function calls, API queries, etc. will be logged.

You can set logLevel at any time in the application's lifespan, but we recommend that you do this before configuring Adapty.

import { LogLevel } from 'react-native-adapty';


For both activate and setLogLevel methods TypeScript validates the string you pass as an argument. However, if you're using JavaScript, you may prefer to use the LogLevel enum, that would guarantee to provide you a safe value:

Handle logs

If you're storing your standard output logs, you might wish to distinguish Adapty logs from others. You can achieve this by appending a prefix to all AdaptyError instances that are logged:

import { AdaptyError } from 'react-native-adapty';

AdaptyError.prefix = "[ADAPTY]";

You can also handle all raised errors from any location you prefer using onError. Errors will be thrown where expected, but they will also be duplicated to your event listener.

import { AdaptyError } from 'react-native-adapty';

AdaptyError.onError = error => {
	// ... 

Delay SDK activation for development purposes

Adapty pre-fetches all necessary user data upon SDK activation, enabling faster access to fresh data.

However, this may pose a problem in the iOS simulator, which frequently prompts for authentication during development. Although Adapty cannot control the StoreKit authentication flow, it can defer the requests made by the SDK to obtain fresh user data.

By enabling the __debugDeferActivation property, the activate call is held until you make the next Adapty SDK call. This prevents unnecessary prompts for authentication data if not needed.

It's important to note that this feature is intended for development use only, as it does not cover all potential user scenarios. In production, activation should not be delayed, as real devices typically remember authentication data and do not repeatedly prompt for credentials.

Here's the recommended approach for usage:

adapty.activate('PUBLIC_SDK_KEY', {
  __debugDeferActivation: isSimulator(), // 'isSimulator' from any 3rd party library