# Installation

Install the Incode Onboarding Flutter SDK, configure the iOS and Android projects that consume it, and initialize the SDK. After initialization, see [Common Implementation Patterns](./flutter-common-implementation-patterns) to start an onboarding session.

## SDK variants

The SDK is distributed in several variants. Select a variant by pointing the `ref` field in your `pubspec.yaml` at the matching release branch (see [Add the SDK to your project](./flutter-installation#add-the-sdk-to-your-project)). Combined variants are not supported.

- **Standard:** The default variant. No modifier.
- `-vc`: Streams the camera feed during Selfie and ID scan.
- `-nfc`: Reads data from a passport or ID chip via NFC.
- `-l`: Manipulates locally stored identities. Required for 1:N `FaceAuthMode.local` [Face Login](./flutter-face-login).

## Requirements

- Flutter 3.16 or higher (recommended)
- Flutter 1.20.0 minimum

## Add the SDK to your project

Add the SDK as a Git dependency in your `pubspec.yaml`. Use the block that matches the variant you need.

### Standard variant

```yaml
onboarding_flutter_wrapper:
  git:
    url: git@github.com:Incode-Technologies-Example-Repos/FlutterSampleApp.git
    ref: release/[VERSION]
```

### Camera streaming variant (-vc)

```yaml
onboarding_flutter_wrapper:
  git:
    url: git@github.com:Incode-Technologies-Example-Repos/FlutterSampleApp.git
    ref: release/[VERSION]-vc
```

### NFC variant (-nfc)

```yaml
onboarding_flutter_wrapper:
  git:
    url: git@github.com:Incode-Technologies-Example-Repos/FlutterSampleApp.git
    ref: release/[VERSION]-nfc
```

### Local identities variant (-l)

```yaml
onboarding_flutter_wrapper:
  git:
    url: git@github.com:Incode-Technologies-Example-Repos/FlutterSampleApp.git
    ref: release/[VERSION]-l
```

Replace `[VERSION]` in the `ref` field with the release branch name (for example, `release/4.18.0`). To use an older version, replace `[VERSION]` with the specific release branch (for example, `release/4.2.0`).

## iOS setup

After adding the SDK to your project, complete the following iOS-specific setup steps.

### 1. Update the Podfile deployment target

In the `ios` folder, change your `Podfile` so it requires deployment target 13 or higher.

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

### 2. Install pods

Run `pod install` within the `ios` folder:

```sh
pod install
```

### 3. Add permission entries to Info.plist

Add the permission entries required by the modules you plan to use.

- Camera modules (`IdScan`, `SelfieScan`, `DocumentScan`, `VideoSelfie`): `NSCameraUsageDescription` is mandatory.
- `Geolocation` module: requires `NSLocationWhenInUseUsageDescription`.
- `VideoSelfie` module voice consent step: requires `NSMicrophoneUsageDescription`.
- `NFCScan` module: requires `NFCReaderUsageDescription` and `NSNFCUsageDescription`.

## Android setup

After adding the SDK to your project, complete the following Android-specific setup steps.

### 1. Update app/build.gradle

In `app/build.gradle`, enable `multiDexEnabled` and set the minimum API level. Use API level 23, or API level 24 if you are using the video streaming dependency.

```diff
defaultConfig {
  …
  multiDexEnabled true
  minSdkVersion 23
}
```

### 2. Configure the GitHub Packages repository

Modify your project's `build.gradle` to include the GitHub Packages repository with credentials provided by Incode.

```diff
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"
+      }
+    }
    ...
  }
}
```

### 3. Set the Kotlin version (conditional)

If you explicitly set a `kotlin-gradle-plugin` version, ensure Kotlin is set to `1.9.22` or higher.

```diff
buildscript {
+    ext.kotlin_version = '1.9.22'

    dependencies {
        ...
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}
```

### 4. Add optional dependencies for Face Login (conditional)

If you plan to use 1:N Face Login with `FaceAuthMode.local`, add the following dependencies to your `app/build.gradle`:

- `com.incode.sdk:model-liveness-detection:[VERSION]`: enables local liveness detection.
- `com.incode.sdk:model-face-recognition:[VERSION]`: enables local face recognition.

See [Face Login](./flutter-face-login) for details on local authentication mode.

## Update to the latest version

To update the SDK to the latest version, run one of the following:

```sh
flutter pub upgrade
```

or

```sh
flutter packages upgrade
```

If the iOS SDK version was updated, also run the following inside your `ios` folder:

```sh
pod install --repo-update
pod update IncdOnboarding
```

## Initialize the SDK

Initialize the SDK before calling any other SDK methods. Incode provides your `apiKey` and `apiUrl`.

```dart
IncodeOnboardingSdk.init(
  apiKey: 'YOUR_API_KEY',
  apiUrl: 'YOUR_API_URL',
  testMode: false,
  onError: (String error) {
    IncodeSdkInitError? e = error.toIncodeSdkInitError();
    switch (e) {
      case IncodeSdkInitError.simulatorDetected:
        print('Incode init failed, simulator detected: $IncodeSdkInitError.simulatorDetected');
        break;
      case IncodeSdkInitError.testModeEnabled:
        print('Incode init failed, test mode enabled: $IncodeSdkInitError.testModeEnabled');
        break;
      default:
        print('Incode init failed: $error');
        break;
    }
  },
  onSuccess: () {
    // Update UI, safe to start Onboarding
    print('Incode initialize successfully!');
  },
);
```

### Init parameters

The parameters most commonly set during initial integration are:

- `apiKey`: String. Provided by Incode.
- `apiUrl`: String. Provided by Incode.
- `testMode`: bool. Set to `true` when running on a simulator.
- `onSuccess`: Callback invoked when initialization succeeds. Safe to start onboarding from here.
- `onError`: Callback invoked when initialization fails. Receives an error `String`; possible values are listed in the `IncodeSdkInitError` enum: `simulatorDetected`, `testModeEnabled`, and `unknown`.

The SDK supports additional optional parameters for logging, tutorial behavior, security, and analytics. See [`init`](./flutter-api-reference#init) on the API Reference page for the full parameter list.

### Initializing without an API key

To initialize the SDK without an `apiKey`, provide only the `apiUrl` to the `init` method, then configure your `OnboardingSessionConfiguration` with a `token`. See [Token-Based Setup](./flutter-token-based-setup) for details.