React Native - Adapty SDK installation & configuration
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.
You currently need to have a react-native-adapty
of version 2.4.7 or higher to use UI SDK.
Please consult the compatibility table below to choose the correct pair of Adapty SDK and AdaptyUI SDK.
Adapty SDK version | AdaptyUI version |
---|---|
2.7.0 – 2.9.2 | 2.0.0 - 2.0.1 |
2.9.3 - 2.9.8 | 2.1.0 |
2.10.0 | 2.1.1 |
2.10.1 | 2.1.2 |
2.11.2 | 2.11.0 |
2.11.3 | 2.11.1 |
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:
-
If you haven't installed the EAS Command-Line Interface (CLI) yet, you can do so by using the following command:
Shellnpm install -g eas-cli
-
In the root of your project, install the dev client to make a development build:
Shellexpo install expo-dev-client
-
Run the installation command:
Shellexpo install react-native-adapty
expo install @adapty/react-native-ui -
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:
Shelleas build --profile development --platform ios
-
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:
Shelleas build --profile development --platform android
-
Start a development server with the following command:
Shellexpo start --dev-client
This should result in the working app with react-native-adapty.
Possible errors:
Error | Description |
---|---|
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 |
Install Adapty SDKs with Pure React Native
If you opt for a purely native approach, please consult the following instructions:
-
In your project, run the installation command:
Shellyarn add react-native-adapty
yarn add @adapty/react-native-ui -
For iOS: Install required pods:
Shellpod 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 your
ios/Podfile
and update the minimal target. Tand update the minimum target. Afterward, you should be able to successfully executepod install
.Podfile-platform :ios, min_ios_version_supported
+platform :ios, 13.0 -
For Android: Update the
/android/build.gradle
file. Make sure there is thekotlin-gradle-plugin:1.8.0
dependency or a newer one:/android/build.gradle...
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';
adapty.activate('PUBLIC_SDK_KEY');
const App = () => {
// ...
}
You can pass several optional parameters during activation:
- Typescript
- JavaScript
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:
Parameter | Presence | Description |
---|---|---|
PUBLIC_SDK_KEY | required | A 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. |
observerMode | optional | A 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 🚧 When running in Observer mode, Adapty SDK won't close any transactions, so make sure you're handling it. |
customerUserId | optional | An 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 If you don't have a user ID when you start with Adapty, you can add it later using the |
logLevel | optional | A string parameter that makes Adapty record errors and other important information to help you understand what's happening. |
__debugDeferActivation | optional | A 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. |
ipAddressCollectionDisabled | optional | Set to The default value is |
idfaCollectionDisabled | optional | A 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:
Level | Description |
---|---|
error | Only errors will be logged. |
warn | Errors and messages from the SDK that do not cause critical errors, but are worth paying attention to will be logged. |
info | Errors, warnings, and serious information messages, such as those that log the lifecycle of various modules will be logged. |
verbose | Any 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.
- Typescript
- Javascript
adapty.setLogLevel('verbose');
import { LogLevel } from 'react-native-adapty';
adapty.setLogLevel(LogLevel.VERBOSE);
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 => {
// ...
console.error(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
});