> ## Documentation Index
> Fetch the complete documentation index at: https://developer.incode.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IncdOnboarding SDK Usage

# IncdOnboarding SDK Usage

## Requirements:

* iOS 13.0+
* Xcode 15.0.1+

IncdOnboarding SDK can be used in three ways - **Standard**, **Advanced** and **Capture only**. Standard mode starts the Onboarding flow that consists of specified steps and validates user inputs along the way. Advanced mode enables you to fully customize the experience of the flow, ie. by splitting it into multiple sections, adding your own custom screens between some of the steps etc. Capture only mode enables you to just retrieve captured images during ie. ID or Selfie scan, without doing any validations such as ID validation, Face recognition and Liveness detection.

# Standard

## 1. Initialize IncdOnboarding SDK

Add the following line of code to your `AppDelegate` class:

```
IncdOnboardingManager.shared.initIncdOnboarding(url: url, apiKey: apiKey)
```

`url` and `apiKey` will be provided to you by Incode. To initialize the SDK without an `apiKey`, please follow the section `Using SDK without API key` below.

`clientExperimentId` parameter is an identifier in case you want to participate in new or experimental features. Talk to your Incode representative for more information.

If you're running the app on a simulator, please set the `testMode` parameter to true.

## 2. Configure the Onboarding session

Firstly, you should create an instance of `IncdOnboardingSessionConfiguration`, which provides a configuration of onboarding session:

```
let sessionConfig = IncdOnboardingSessionConfiguration()
```

You can optionally customize the onboarding session by providing these parameters:

* Parameter `regionCode`: Specify the user's region
* Parameter `queue`: Specify the queue which the user will enter once the flow is completed. If none specified user goes to default queue.
* Parameter `configurationId`: Specify flow id from the dashboard in order to use configurations applied to that flow. Note that you still have to add onboarding steps via `IncdOnboardingFlowConfiguration` in order to display onboarding flow to the user.
* Parameter `validationModules`: List of Onboarding Validation modules to be taken into account for user scoring and approval. By default it is `.id`, `.liveness`, `.faceRecognition`
* Parameter `customFields`: Provide a list of custom fields that will be stored for this session
* Parameter `interviewId`: ID of the onboarding session. Specify in order to resume existing onboarding session.
* Parameter `token`: Token of the onboarding session. Specify in order to resume existing onboarding session.
* Parameter `externalId`: Id that is used outside of Incode Omni platform. If a session with the same externalId already exists, it will be resumed instead of creating a new one.
* Parameter `externalCustomerId`: Similar to externalId, but instead of restarting the session it will create a new one.
* Parameter `e2eEncryptionEnabled`: Enables End-to-end encryption for API requests.
* Parameter `mergeSessionRecordings`: A Boolean value that indicates whether the session recordings will be compiled into a single video. If set to true, the recordings from the ID capture and Face capture will be merged.

## 3. Configure the Onboarding flow

Depending on your needs you should specify the steps you want to include using `IncdOnboardingFlowConfiguration`, ie.:

```
let flowConfig = IncdOnboardingFlowConfiguration()
flowConfig.addIdScan()
flowConfig.addSelfieScan()
flowConfig.addFaceMatch()
```

The steps will be executed in the order you added them to the flow config.

## 4. Start the Onboarding

In your `UIViewController` class where you want to start the onboarding flow you should call `startOnboarding` function:

```
IncdOnboardingManager.shared.presentingViewController = self
IncdOnboardingManager.shared.startOnboarding(sessionConfig: sessionConfig, flowConfig: flowConfig, delegate: self)
```

You should provide your `UIViewController` instance, previosuly created `IncdOnboardingSessionConfiguration`, `IncdOnboardingFlowConfiguration` and a delegate that conforms to `IncdOnboardingDelegate` protocol that will be notified about updates from IncdOnboarding SDK as the user goes through the flow.

```
  
    // Called when front Id Scan is completed
    func onIdFrontCompleted(_ result: IdScanResult)

    // Called when back Id Scan is completed
    func onIdBackCompleted(_ result: IdScanResult)

    // Called when process ID step is completed.
    func onIdProcessed(_ result: IdProcessResult)

    // ...

    // Called when Onboarding flow is finished successfully
    func onSuccess()

    // Called when some unexpected error occured during Onboarding flow
    func onError(_ error: IncdFlowError)

```

# Advanced flow SDK mode

Advanced flow SDK mode enables you to fully customize the experience of the flow, ie. by splitting Onboarding flow into multiple sections, adding your own custom screens between some of the steps etc.

## 1. Initialize IncdOnboarding SDK

Add the following line of code to your `AppDelegate`class:

```
IncdOnboardingManager.shared.initIncdOnboarding(url: url, apiKey: apiKey)
```

`url` and `apiKey` will be provided to you by Incode. To initialize the SDK without an `apiKey`, please follow the section `Using SDK without API key` below.

Optionally disable logs, by providing `false` for `loggingEnabled` parameter.

## 2. Setup onboarding session

Before calling other Onboarding SDK components it is nececessary to setup an onboarding session.

```

 IncdOnboardingManager.shared.setupOnboardingSession(sessionConfig: IncdOnboardingSessionConfiguration()) { (sessionResult) in
    // Setting up the onboarding session is completed
    if sessionResult.result == .success {
       // Its now safe to start to call other methods
       ...
    }
   
 }
```

## 3. Show Onboarding Sections or call other SDK methods

After onboarding session is setup you can show Onboarding SDK components based on your need, here's some examples what you can do inside your `UIViewController` classes where you would like to show Onboarding SDK components.

If you would like to show multiple steps sequentially, you can specify which ones and their order by creating `IncdOnboardingFlowConfiguration` object:

```
IncdOnboardingFlowConfiguration flowConfig  = IncdOnboardingFlowConfiguration()
flowConfig.addIdScan()
flowConfig.addFaceScan()
```

After you've created the flow configuration, you need to call `startOnboardingSection` to start the flow:

```
IncdOnboardingManager.shared.presentingViewController = self
IncdOnboardingManager.shared.startOnboardingSection(flowConfig: flowConfig, sectionTag: "MySection", delegate: self)
```

Once the section is completed you'll get notified through the delegate and its `onOnboardingSectionCompleted` function:

```
func onOnboardingSectionCompleted(_ flowTag: String) {
    print("onOnboardingSectionCompleted")
    // Show custom UI, create and show another Onboarding section or individual screen
  }
```

## Separated Front and Back ID Scan

If you would like to scan the front side of the ID separately from the back side, you need to:

1. Specify ScanSide parameter:

```
firstSection.addIdScan(scanStep: .front)
```

```
secondSection.addIdScan(scanStep: .back)
```

2. Add ID Process module (this step is not required if `scanStep` is `.both`)

```
thirdSection.addIdProcess()
```

Note: `firstSection`, `secondSection` and `thirdSection` are separated to make an example.
They can also be one section but after `IdProcess` no more scanning will be possible.

Results will be returned in the same way as before, via:

```
  
    // Called when front Id Scan is completed
    func onIdFrontCompleted(_ result: IdScanResult)

    // Called when back Id Scan is completed
    func onIdBackCompleted(_ result: IdScanResult)

    // Called when process ID step is completed.
    func onIdProcessed(_ result: IdProcessResult)
```

## Call individual Onboarding SDK components

If you would like to show a single step, ie. do a geolocation only, you can call use the API to call individual Onboarding SDK components.
To start the geolocatiion:

```
IncdOnboardingManager.shared.presentingViewController = self
IncdOnboardingManager.shared.geolocation() { (result) in
    // geolocation is completed, result is of type `GeolocationResult`
}
```

## 4. Finish the session

Once you're done with all the steps needed from IncdOnboarding SDK it is necessary to flag this session as finished.

To do so you need to call `finishFlow`:

```
IncdOnboardingManager.shared.finishFlow() { success, error in 
  // Session is now flag as finished
}
```

If you don't want to flag this session as finished, but still want to perform a session cleanup before using the SDK further, please call `deleteLocalUserData` method:

```
IncdOnboardingManager.shared.deleteLocalUserData()
// Session cleanup completed
}
```

# Capture Only

Full guide for Capture Only SDK mode is available [here](USER_GUIDE_CAPTURE_ONLY.md)

### Simulator Support:

To enable simulator support, when initializing the IncdOnboardingManager using the `initIncdOnboarding(url:apiKey:token:loggingEnabled:testMode:_:)` method, set the `testMode` parameter to true.

On the simulator, onboarding modules which require use of the device camera will show a black or grey background instead of the camera preview. The modules will only last for 2 seconds before returning `.simulatorDetected` and then moving on to the next module.

### Background conference support

* In order to enable conference background mode, OpenTok requires a key-value pair to be added to your app. In the Info.plist file for your app, set up the background mode permissions as described in the Apple documentation for creating VoIP apps. The key is `UIBackgroundModes`. Do add the `audio` value to this dictionary.

# Other API methods

### Get Regions

To fetch all the regions available use `getRegions()` method.

Example usage:

```
IncdOnboardingManager.shared.getRegions() { regions, error in
  var myRegionCode: String?
  // Go through the list of available regions to set `myRegionCode`, and the provide it to the `IncdOnboardingSessionConfiguration` to apply it to your onboarding session
  let sessionConfig = IncdOnboardingSessionConfiguration(regionCode: myRegionCode)
}
```

### Dismissing Incode UX

Calling `dismiss` method will try to dismiss current flow.
If flow or module is not yet finished nothing will happen.

To force interruption of the flow specify `forceInterrupt` to true, which will also mark the session as finished and trigger the callback `onError` with the value `.interrupted` in case `delegate` was provided in `startOnboarding` or `startOnboardingSection`.

```
IncdOnboardingManager.shared.dismiss()
```

or

```
IncdOnboardingManager.shared.dismiss(forceInterrupt: true)
```

### Force close Incode UX

Calling the `forceInterrupt` method will imediatelly cancel IncdOnboarding simple flow, section flow or individual module.

It will try to mark current session as finished if `tryFinishingFlow` is `true`, and lastly trigger the callback `onError` with the value `.interrupted` in case `delegate` was provided in `startOnboarding` or `startOnboardingSection`.

* Parameters:
  * `tryFinishingFlow`: If `true`, it will try asynchronously to mark current session as finished. Default is `false`.
  * `interviewId`: Optional `interviewId` in case you would like to finish a specific user session, instead of the most recent one.
  * `completion`: Callback for getting result of this step.
    * success: `Bool`
    * error: `IncdError?`

```
IncdOnboardingManager.shared.forceInterrupt() { success, error in
  // if `success` true the flow was successfully interrupted
}
```

### Load machine learning models

Calling `loadModels` method will start loading of image processing models that are used in camera capture modules, ie. Selfie scan.

May be called in advance to minimize delays at corresponding modules initialization and faster startup of these modules.

```
IncdOnboardingManager.shared.loadModels()
```

# Using SDK without API key

To avoid providing API key to the SDK and actually creating onboarding sessions on your backend, please use the following guide.

## Init the SDK without API key

Provide an URL to the `initIncdOnboarding` that ends with an `/0` to specify environment that doesn't require API key to function properly.

```
IncdOnboardingManager.shared.initIncdOnboarding(url: "https://demo-api.incodesmile.com/0") { success,error in

}
```

## Provide a session token

1. Create an onboarding session token on your backend using `omni/start` API method that will return a `token`.

2. Pass it to the `IncdOnboardingSessionConfiguration` object before starting the flow:

```
let sessionConfiguration = IncdOnboardingSessionConfiguration(token: "YOUR_TOKEN_GOES_HERE")
```

Please note there is no need to specify `interviewId` or `configurationId` params, only specifying `token` is enough and all necessary configurations will be applied to this session.

## Start the flow

3. Provide `sessionConfiguration` created in previous step to the `startOnboarding` or `setupOnboardingSession` methods depending if you're using `Standard` or `Advanced` flow.

Example for `startOnboarding`:

```
let flowConfig = IncdOnboardingFlowConfiguration()
flowConfig.addIdScan()
IncdOnboardingManager.shared.startOnboarding(sessionConfig: sessionConfig,
                                             flowConfig: flowConfig,
                                             delegate: self)
```

Example for `setupOnboardingSession` and using sections:

```
IncdOnboardingManager.shared.setupOnboardingSession(sessionConfig: sessionConfig) { session, error in
  guard error == nil else {
    // Session couldn't be created due to some error
    return
  }
  let flowConfig = IncdOnboardingFlowConfiguration()
  flowConfig.addIdScan()
  IncdOnboardingManager.shared.startOnboardingSection(flowConfig: flowConfig, sectionTag: "id", delegate: self)
}
```

# Risk Analysis

To use Risk Analysis feature prerequisite is to use 'd-ra' framework variant.

Once you obtain the token created outside of the native SDK, please follow the guide [here](https://developer.incode.com/docs/user_guide#using-sdk-without-api-key) how to initialize the SDK and provide the token

# Customize Face Capture and Video Selfie text

Follow the custom localization guide [here](LOCALIZATION_GUIDE.md). Define in your `Localizable.strings` files the following keys: `"incdOnboarding.videoSelfie.customText"` and `"incdOnboarding.selfie.customText"`.

# E2EE (End-to-end Encryption) for API requests and responses

To enable E2EE for API requests and responses:

1. Provide API URL with `e2eeURL` parameter of the `initIncdOnboarding` method.
2. Set `e2eEncryptionEnabled` flag of the `IncdOnboardingSessionConfiguration` model to `true`

Full guide for E2EE is available [here](USER_GUIDE_E2EE.md)