# 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](index.md)), then see [SDK Modes](react-native-sdk-modes.md) to choose how the SDK operates, and [Common Implementation Patterns](../react-native-common-implementation-patterns/index.md) to choose how to drive the onboarding flow.

## Variant Explanation

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

| Variant | Example dependency | Use when you need |
|---------|--------------------|-------------------|
| Standard | `"[VERSION]"` | Base onboarding modules. |
| Streaming | `"[VERSION]-vc"` | Camera frame streaming for ID/Selfie capture. |
| Face Login | `"[VERSION]-l"` | `startFaceLogin()` and locally stored identity flows. |
| NFC | `"[VERSION]-nfc"` | `NFCScan` and NFC-based face match flows. |

## Environment Setup

### Requirements

* React Native app with Android and/or iOS targets.
* 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` 35+.

## Installation

Install the standard package:

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

Or pin the dependency in `package.json`:

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

Use a variant suffix when needed:

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

## Additional Setup Instructions

### Additional setup for iOS

Set the deployment target to iOS 13 or higher:

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

Add the CocoaPods sources at the top of your `Podfile`:

```ruby
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:

```ruby
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:

```sh
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:

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

### Additional setup for Android

Set Android SDK versions:

```gradle
minSdkVersion = 23
compileSdkVersion = 35
```

Use `minSdkVersion = 24` when enabling video streaming.

Enable multidex:

```diff
defaultConfig {
+  multiDexEnabled true
}
```

Add the multidex dependency:

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

Make the application extend `MultiDexApplication`:

```java
import androidx.multidex.MultiDexApplication;

public class MyApplication extends MultiDexApplication implements ReactApplication {
}
```

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

```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](react-native-troubleshooting.md) 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:

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

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

```json
{
  "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:

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

Then prebuild and run:

```sh
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`.