Skip to main content

React Native - Adapty SDK installation & configuration

Adapty SDK includes two key modules for seamless integration into your mobile app:

  • Core Adapty: This essential SDK module is required for Adapty to function properly in your app.
  • AdaptyUI: This optional module is needed if you use the Adapty Paywall Builder, a user-friendly, no-code tool for easily creating cross-platform paywalls. These paywalls are built with a visual constructor right in our dashboard, run natively on the device, and require minimal effort to create high-performing designs.

Install Adapty SDK​

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 SDK 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

  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

  5. 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

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

ErrorDescription
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 SDK 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

  2. For iOS: Install required pods:

    Shell
    pod install --project-directory=ios
    pod install --project-directory=ios/

    The minimum supported iOS version is 13.0, but the new Paywall Builder requires iOS 15.0 or higher.

    If you run into an error during pod installation, find this line in your ios/Podfile and update the minimum target. After that, you should be able to run pod install without any issues.

    Podfile
    -platform :ios, min_ios_version_supported
    +platform :ios, 15.0

  3. 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 SDK​

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:

adapty.activate('PUBLIC_SDK_KEY', {
  observerMode: false,
  customerUserId: 'YOUR_USER_ID',
  logLevel: 'error',
  __debugDeferActivation: false,
  ipAddressCollectionDisabled: false,
  ios: {
    idfaCollectionDisabled: false,
  },
  activateUi: true,
  mediaCache: {
    memoryStorageTotalCostLimit: 100 * 1024 * 1024, // 100MB
    memoryStorageCountLimit: 2147483647, // 2^31 - 1
    diskStorageSizeLimit: 100 * 1024 * 1024, // 100MB
  },
});

Parameters:

ParameterPresenceDescription
observerModeoptional

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.

customerUserIdoptionalAn identifier of the user in your system. We send it in subscription and analytical events, to attribute events to the right profile. You can also find customers by customerUserId in the Profiles and Segments menu.
logLeveloptionalAdapty logs errors and other crucial information to provide insight into your app's functionality. There are the following available levels:
  • 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.
activateUioptionalSet to false to disable the Adapty UI module. This module is only required if you're using Paywall Builder paywalls. By default, it is always enabled.
idfaCollectionDisabledoptionalSet to true to disable IDFA collection and sharing. The default value is false. For more details on IDFA collection, refer to the Analytics integration section.
mediaCacheoptional

Define the limits for the cache of the media files: video and images.

  • memoryStorageTotalCostLimit: (required) Total cost limit of the storage in bytes.
  • memoryStorageCountLimit: (required) The item count limit of the memory storage.
  • diskStorageSizeLimit: (required) The file size limit on the disk of the storage in bytes. 0 means no limit.

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:

LevelDescription
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.

adapty.setLogLevel('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
});