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 offers two essential SDKs for seamless integration into your mobile app:

• The primary Adapty SDK: This is a foundational, obligatory SDK required for the operation of Adapty within your app.
• AdaptyUI SDK: This additional SDK is essential if you plan to use the Paywall Builder. The Paywall Builder is a convenient, user-friendly tool designed for a no-code approach. It empowers you to effortlessly create a subscription or other virtual product purchase page, known as a Paywall in Adapty. This approach ensures seamless integration of paywalls directly into your iOS or Android apps as native layout pages.
  The Adapty Paywall Builder is crafted to streamline the setup of core conversion-driving elements of paywalls with just a few clicks in the dashboard, eliminating the need to spend time on minor design tweaks and technical configurations. It also enables you to edit your paywall's native layout on-the-go by making visual changes in the Adapty web interface.

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 or later	2.1.2

❗️

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:

Shell

npm install -g eas-cli

2. In the root of your project, install the dev client to make a development build:

Shell

expo install expo-dev-client

3. Run the installation command:

Shell

expo install react-native-adapty
expo install @adapty/react-native-ui

4. 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:

Shell

eas build --profile development --platform ios

4. 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:

Shell

eas build --profile development --platform android

5. Start a development server with the following command:

Shell

expo 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 unescape(“string”), which should result in something like http://192.168.1.35:8081

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:

Shell

yarn add react-native-adapty
yarn add @adapty/react-native-ui

2. For iOS: Install required pods:

Shell

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.

Podfile

-platform :ios, min_ios_version_supported
+platform :ios, 13.0

2. For Android: Update the /android/build.gradle file. Make sure there is the kotlin-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.

/src/App.tsx

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

adapty.activate('PUBLIC_SDK_KEY');

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

You can pass several optional parameters during activation:

TypeScript

adapty.activate('PUBLIC_SDK_KEY', {
  observerMode: false,
  customerUserId: 'YOUR_USER_ID',
  logLevel: 'error',
  __debugDeferActivation: false,
  ios: {
    idfaCollectionDisabled: false,
  },
});

JavaScript

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

adapty.activate('PUBLIC_SDK_KEY', {
  observerMode: false,
  customerUserId: 'YOUR_USER_ID',
  logLevel: LogLevel.ERROR,
  __debugDeferActivation: false,
  ios: {
    storeKit2Usage: IosStorekit2Usage.EnabledForIntroductoryOfferEligibility,
    idfaCollectionDisabled: false,
    enableUsageLogs: true,
  },
});

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 false. 🚧 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 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.
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.
idfaCollectionDisabled	optional	A boolean parameter, that allows you to disable IDFA collection for your app. The default value is false. For more details, refer to the Analytics integration section.

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

adapty.setLogLevel('verbose');

JavaScript

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:

TypeScript

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.

TypeScript

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:

TypeScript

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