Installation

This page covers everything you need to install and initialize the Incode React Native SDK in your app: choosing the right SDK variant, environment requirements, platform-specific setup for iOS and Android, and Expo configuration.

Once installation is complete, initialize the SDK (see Getting Started), then see SDK Modes to choose how the SDK operates, and Common Implementation Patterns to choose how to drive the onboarding flow.

SDK Variants

The SDK is published as @incode-sdks/react-native-incode-sdk. Pick the version suffix that matches your feature set.

Environment Setup

Requirements

Access prerequisites

Three separate credentials are required before the SDK will install and build:

• An NPM account that has accepted the invitation to the Incode React Native team. See Get access to the private NPM package.
• GitHub authentication configured on your machine over SSH or HTTPS. The Incode CocoaPods podspec sources are hosted on GitHub and iOS builds cannot resolve them otherwise.
• A GitHub token with the read:packages scope for the android-omni-packages registry, used by Android builds.

Contact your Incode representative to request the NPM invitation and the GitHub Packages credentials.

Tooling

• React Native app with Android and/or iOS targets.
• Node 18+; Node 20+ recommended.
• Xcode 15.0.1+.
• Swift 5.5+.
• CocoaPods 1.11+.
• iOS 13+.
• Android minSdkVersion 23+; use 24+ when using the video-streaming dependency.
• Android compileSdkVersion 36+.
• Android Gradle Plugin 8.9.1+.
• Gradle 8.14.5+.
• Kotlin 2.2.21+.

Installation

Get access to the private NPM package

The React Native SDK is distributed as a private NPM package. Before you install it, you must have a free NPM account. Once your NPM account is set up, contact Incode and share your NPM username. We send an invitation to join our React Native team to the email address associated with your NPM account. You must accept this invitation within 7 days to access the SDK.

Add an .npmrc file to your project

An .npmrc file customizes NPM's behavior, including access to private packages. In the root directory of your React Native project, create an .npmrc file with these contents:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}
@incode-sdks:registry=https://registry.npmjs.org/

Export the token in the shell you install from:

export NPM_TOKEN="<your-npm-token>"

NPM expands ${NPM_TOKEN} from the environment at install time, so this .npmrc holds no secret and is safe to commit. Never commit a file containing the literal token value.

Create the token in your NPM account settings. See Creating and viewing access tokens in the NPM documentation. Either token type works:

• A classic token with Read-only access.
• A granular access token with Read permission for the @incode-sdks scope. Granular tokens expire, so renew the token before its expiration date or installs start failing.

The @incode-sdks:registry line matters when your team installs through a mirror or proxy registry such as Artifactory or Verdaccio. It routes the Incode scope to npmjs.org while every other package keeps resolving through the mirror.

Yarn and pnpm

pnpm and Yarn Classic (1.x) read .npmrc as shown above. Yarn Berry (2.x and newer) ignores it, so configure the scope in .yarnrc.yml instead:

npmScopes:
  incode-sdks:
    npmRegistryServer: "https://registry.npmjs.org"
    npmAuthToken: "${NPM_TOKEN}"

Install the package

Install the standard package:

npm i @incode-sdks/react-native-incode-sdk

Or pin the dependency in package.json:

{
  "dependencies": {
    "@incode-sdks/react-native-incode-sdk": "[VERSION]"
  }
}

Use a variant suffix when needed:

{
  "dependencies": {
    "@incode-sdks/react-native-incode-sdk": "[VERSION]-vc"
  }
}

Additional Setup Instructions

iOS Setup

Set the deployment target to iOS 13 or higher:

-platform :ios, '10.0'
+platform :ios, '13.0'

Add the CocoaPods sources at the top of your Podfile:

source 'https://cdn.cocoapods.org/'
source 'git@github.com:Incode-Technologies-Example-Repos/IncdDistributionPodspecs.git'

For React Native 0.69 and newer, autolinking is enough. For older React Native versions, add the package path manually:

pod 'react-native-incode-sdk', :path => '../node_modules/@incode-sdks/react-native-incode-sdk/'

Add an empty Swift file to the native project in Xcode. When prompted, create the bridging header.

Before running pod install, configure SSH or HTTPS GitHub authentication. The Incode podspec source is hosted on GitHub and requires authenticated access.

Run CocoaPods:

cd ios
pod install
cd ..

Add these Info.plist usage descriptions:

• NSCameraUsageDescription. The SDK uses the camera in order to verify the identity of the customer, for example in ID scan and Selfie scan.
• NSLocationWhenInUseUsageDescription. The SDK uses the current user location for the Geolocation step.
• NSMicrophoneUsageDescription. The SDK uses the microphone during video conference and video selfie flows.

Add the required linker flags in the app target's Build Settings > Other Linker Flags:

$(inherited) -all_load -ObjC -l "stdc++" -l "iconv"

Android Setup

Set Android SDK versions:

minSdkVersion = 23
compileSdkVersion = 35

Use minSdkVersion = 24 when enabling video streaming.

Enable multidex:

defaultConfig {
+  multiDexEnabled true
}

Add the multidex dependency:

implementation 'com.android.support:multidex:1.0.3'

Make the application extend MultiDexApplication:

import androidx.multidex.MultiDexApplication;

public class MyApplication extends MultiDexApplication implements ReactApplication {
}

Add the Incode Maven repository and credentials to the project build.gradle:

allprojects {
  repositories {
    maven { url "https://jitpack.io" }
    maven {
      url = uri("https://maven.pkg.github.com/Incode-Technologies-Example-Repos/android-omni-packages")
      credentials {
        username = "incode-customers"
        password = "GITHUB_TOKEN"
      }
    }
  }
}

Prefer environment or Gradle properties for real credentials. Do not commit tokens.

Troubleshooting tip: If Gradle cannot resolve Incode dependencies, verify credentials and repository access with your Incode representative. See Troubleshooting for more build and setup issues.

Expo SDK Installation

If your app is built with Expo, install the Expo configuration plugin instead of doing the iOS and Android setup steps above.

Install the plugin:

npx expo install @incode-sdks/expo-incode-sdk-configuration

Add it to app.json or app.config.js:

{
  "expo": {
    "plugins": [
      [
        "@incode-sdks/expo-incode-sdk-configuration",
        {
          "cameraUsageDescription": "The SDK uses the camera in order to verify the identity of the customer.",
          "locationWhenInUseUsageDescription": "The SDK uses the current user location for Geolocation steps.",
          "microphoneUsageDescription": "The SDK uses the microphone for video conference or video selfie.",
          "allowBackupOverride": true,
          "koinVersion": "3.5.3",
          "iosPodspecSource": "ssh",
          "addStreaming": false,
          "addDynamicLocalization": false,
          "addVoiceConsentFaceRecognition": false,
          "addNfc": false
        }
      ]
    ]
  }
}

Android builds need GitHub Packages credentials:

export GITHUB_USERNAME="<github-username>"
export GITHUB_TOKEN="<github-token>"

Then prebuild and run:

npx expo prebuild --clean --platform android
npx expo run:android --device

iosPodspecSource can be ssh or https. When using HTTPS, configure GitHub authentication outside the project with GitHub CLI, Git Credential Manager, macOS Keychain, or ~/.netrc.