react-native-incode-sdk Usage guide

Contents:

Installation
Additional setup for iOS
Additional setup for Android
Installation Expo SDK
Usage
Onboarding flow and workflow execution results
Flow listeners
- User cancellation
- Step completion
Other API methods
Sections execution API
Dynamic Delivery
Using SDK without an API KEY
SDK impact size optimizations
E2EE SDK Integration Guide
Customization
- Android
- iOS

Installation

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

Additional setup for iOS

After installation, it's necessary to do the linking for the iOS, after running the command above. Requirements:

Xcode 15.0.1+
Swift 5.5+
Cocapods 1.11+
iOS 13+

Change your Podfile so it equires deployment target 13 or higher.

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

Add this line to the top of your Podfile:

RN >= 0.69 no changes needed

RN < 0.69

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

Add an empty Swift file (e.g. Void.swift) through xCode to your native project. When prompted for a bridging header, choose Create Bridging header.
Relying on React Native's auto-linking, run the following:

cd ios && pod install cd ..

Adapt Info.plist by adding:

NSCameraUsageDescription. The SDK uses the camera in order to verify the identity of the customer, e.g. in ID scan, Selfie scan and so on.
NSLocationWhenInUseUsageDescription. The SDK uses the current user location in order to detect exact location for Geolocation step.
NSMicrophoneUsageDescription. The SDK uses microphone for performing a video call during Video Conference step or for doing speech recognition during Video Selfie.

Add Linker flags

Go to your projects Target, then Build Settings -> Other Linker Flags and add these flags:

$(inherited) -all_load -ObjC -l “stdc++” -l “iconv”

Additional setup for Android

In your app's build.gradle please make sure that following settings are set:

Change your minSdkVersion to 21 or higher. Set compileSdkVersion to 34 or higher.
Add this dependency in you app's build.gradle:

  dependencies {
+    implementation 'com.incode.sdk:core-light:2.6.4'
  }

Application has multidex support enabled:

  defaultConfig {
    ...
+   multiDexEnabled true
    ...
  }

  dependencies {
    ...
+   implementation 'com.android.support:multidex:1.0.3'
    ...
  }

Your Application class should now be able to extend MultiDexApplication:

+  import androidx.multidex.MultiDexApplication;

+  public class MyApplication extends MultiDexApplication implements ReactApplication {
  ...
 }

Modify your project's build.gradle so it contains Artifactory username and password, provided by Incode.

allprojects {
  repositories {
    ...
+    maven { url "https://jitpack.io" }
+    maven {
+      url "https://repo.incode.com/artifactory/libs-incode-welcome"
+      credentials {
+        username = "ARTIFACTORY_USERNAME"
+        password = "ARTIFACTORY_PASSWORD"
+      }
+    }
    ...
  }
}

Installation Expo SDK

Install SDK

npx expo install @incode-sdks/react-native-incode-sdk

Install configuration plugin

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

Integrate and configure configuration plugin. Update 'plugins' field in app.json file:

{
  "expo": {
    "plugins": [
      [
        "@incode-sdks/expo-incode-sdk-configuration",
        {
          "artifactoryUserName": "client_artifactory_username",
          "artifactoryPassword": "client_artifactory_password",
          "coreLightVersion": "2.6.4"
        }
      ]
    ]
  }
}

Usage

The typical basis workflow includes the following steps:

Explicitly initialize IncodeSdk
After waiting for the SDK to be initialized, configure Incode Onboarding Flow, by selecting modules (steps) you need
Register listeners for steps-related events (e.g. step completion, step update, step failure)
Run the Onboarding flow

Usage Example

import React from 'react';
import IncodeSdk from '@incode-sdks/react-native-incode-sdk';
import { View, TouchableOpacity } from 'react-native';

const StartOnboardingButton = () => {
  // 1. initialization
  const initializeAndRunOnboarding = () => {
    IncodeSdk.initialize({
      testMode: false,
      apiConfig: {
        key: 'YOUR API KEY HERE',
        url: 'YOUR API URL HERE',
      },
    })
      .then((_) => {
        // 2. configure and start onboarding
        startOnboarding();
      })
      .catch((error) => {
        const e = error as IncodeSdkInitError;
        console.error(`Incode SDK initialize failed with error ${e.code} - ${e.message}`);
      });
  };

  const startOnboarding = () =>
    IncodeSdk.startOnboarding({
      flowConfig: [
        { module: 'IdScan' },
        { module: 'SelfieScan' },
        { module: 'FaceMatch' },
      ],
    })
      .then((result) => {
        console.log(result);
      })
      .catch((error) => console.log(error));

  // 3: register listeners for relevant events when the component gets mounted
  React.useEffect(() => {
    const unsubscribers = setupListeners(); //defined below

    // return a function unregistering all your listeners (called when component is unmounted)
    return () => {
      unsubscribers.forEach((unsubscriber) => unsubscriber());
    };
  }, []);

  return <TouchableOpacity label="Start onboarding!" onPress={initializeAndRunOnboarding} />;
};

const setupListeners = () => {
  // returns a callback to unregister your listener, e.g. when your screen is getting unmounted
  IncodeSdk.onSessionCreated((session) => {
      console.log('Onboarding session created, interviewId: ' + session.interviewId);
    })

  const complete = IncodeSdk.onStepCompleted;
  return [
    complete({
      module: 'IdScanFront',
      listener: (e) => {
        console.log('ID scan front:', e.result);
      },
    }),
    complete({
      module: 'IdScanBack',
      listener: (e) => {
        console.log('ID scan back: ', e.result);
      },
    }),
    complete({
      module: 'ProcessId',
      listener: (e) => {
        console.log('ProcessId result: ', e.result.extendedOcrData);
      },
    }),
    complete({
      module: 'SelfieScan',
      listener: (e) => {
        console.log('Selfie scan complete', e.result);
      },
    }),

    complete({
      module: 'FaceMatch',
      listener: (e) => {
        console.log('Face match complete', e.result);
      },
    }),
  ];
};

Initialize the SDK

Parameters available for IncodeSDK.initialize method:

testMode - Set to true if running on simulator/emulators, false when running on devices. Default false.
sdkMode - Specify standard or captureOnly modes. Default is standard. captureOnly mode works completely offline and for ID and Selfie scan only does image captures without doing any validations.
disableHookCheck - Set to true if you would like to test the app on Android devices that have some hook frameworks installed, cause they are not allowed in production. Default false.
waitForTutorials - Specifying false means that the users can see and press continue button on all video tutorial screens without waiting for the video to complete. Default true.
apiConfig
- key [optional] - API key, provided by Incode
- url - API url, provided by Incode
- e2eeUrl - custom server url used for End-to-End Encryption (E2EE)
sslPinningConfig
- enabled - Set to false to disable SSL pinning. Default is true
disableJailbreakDetection - Set to true if you would like to disable jalibreak detection. Valid only for iOS. Default false.
externalAnalyticsEnabled - Set to true if you would like to enable external analytics. Default true.
loggingEnabled - Set to true if you would like to enable logging. Default true.
externalScreenshotsEnabled - Set to true if you would like to enable external screenshots. Default false.
disableEmulatorDetection - Set to true if you would like to disable emulator detection.Valid only for Android. Default false.
disableRootDetection - Set to true if you would like to disable root detection. Valid only for Android. Default false.

IncodeSDK.initialize method throws IncodeSdkInitError error with following possible values for field code: simulatorDetected, testModeEnabled, invalidInitParams, configError, unknown

Start the onboarding

IncodeSdk.startOnboarding will create a new session based on specified list of modules that you provide via flowConfig.

To change session parameters, specify them inside optional sessionConfig parameter:

region - Specify a region, currently supported are ALL(covers all regions), BR (optimized for Brazil) and IN (optimized for India)
queue - Specify a queue to which this onboarding session will be attached to
interviewId - In case you're creating an onboarding session on the backend, you can provide its interviewId and the flow will be started for that particular onboarding session
configurationId - In case you've created a flow on the dashboard with a specific configuration, you can provide it here so that those settings apply to this session
token - In case you're creating an onboarding session on the backend, you can provide its token and the flow will be started for that particular onboarding session
externalId - ID used outside of Incode Omni
validationModules - List of validation modules that should be enabled in this session
customFields - Custom data that should be attached to this onboarding session
e2eEncryptionEnabled - Enable e2e encryption.

To enable screen recording of ID and Selfie capture, specify optional recordSessionConfig parameter:

Set recordSession to true
Set forcePermissions, true if you wish to abort the session in case user denies permissons, false otherwise

Start workflow

IncodeSdk.startWorkflow will create a new session based on configurationId that you provide via sessionConfig.

To change session parameters, specify them inside required sessionConfig parameter:

configurationId - Configuration ID of a flow on the dashboard. Required parameter.
region - Specify a region, currently supported are ALL(covers all regions), BR (optimized for Brazil) and IN (optimized for India)
queue - Specify a queue to which this onboarding session will be attached to
interviewId - In case you're creating an onboarding session on the backend, you can provide its interviewId and the flow will be started for that particular onboarding session
token - In case you're creating an onboarding session on the backend, you can provide its token and the flow will be started for that particular onboarding session
externalId - ID used outside of Incode Omni
validationModules - List of validation modules that should be enabled in this session
customFields - Custom data that should be attached to this onboarding session

To enable screen recording of ID and Selfie capture, specify optional recordSessionConfig parameter:

Set recordSession to true
Set forcePermissions, true if you wish to abort the session in case user denies permissons, false otherwise

Supported modules

The modules supported by the SDK are listed here, and elaborated in more detail throughout the rest of this document.

Phone
DocumentScan
Geolocation
UserConsent
Signature
VideoSelfie
- ⚠️ Android note: Available only for API level 21+.
IdScan (does capture of both front and back ID and validates it)
IdScanFront (does capture of ony front)
IdScanBack (does capture of only back)
ProcessId (does only validation of the ID - should be called once IdScanFront and IdScanBack are completed)
Conference
SelfieScan
FaceMatch
QrScan
Email
Approve
UserScore
MLConsent
GovernmentValidation
Antifraud
GlobalWatchlist
CustomWatchlist
Aes
Name
CURP
OCREdit
eKYB
eKYC

Modules interdependencies

The order of the modules in the config array indicates the execution order. Note that:

FaceMatch module expects IdScan and SelfieScan to have executed, in order to perform the match. In other words, IdScan and SelfieScan must precede FaceMatch
ProcessId module expects IdScanFront and IdScanBack to have executed, in order to validate the ID properly. In other words, IdScanFront and IdScanBack must precede ProcessId
UserScore module should succeed all other modules (must be at the end)
Approve module should succeed all other modules (must be at the end)
The UserScore and Approve modules do not depend on each other, so their order can be arbitrary.

Onboarding flow and workflow execution results

When the flow completes, the promise startOnboarding and startWorkflow will contain the execution status:

{ "status": "success" }

In case the user cancels the process, the status will be user_cancelled.

In case the execution can not be completed, promise will be rejected with a IncodeSdkFlowError with following possible values for field code: simulatorDetected, rootDetected, hookDetected, badEnvDetected,virtualEnvDetected, permissionsDenied, unknown

Example of handling the error:

try {
      const onboardingResult = await IncodeSdk.startOnboarding({
        sessionConfig: sessionConfig,
        flowConfig: flowConfig,
      });
    } catch (error) {
      const e = error as IncodeSdkFlowError;
      if (e.code === 'permissionsDenied') {
        console.log(`User denied some mandatory permission during the flow`);
      } else {
        console.log('Unknown error occured')
      }
    }

Workflow execution results

When the workflow completes, the promise startWorkflow will contain the execution status:

{ "status": "success" }

In case the user cancels the process, the status will be user_cancelled.

In case the execution can not be completed, the startWorkflow promise will be rejected. This can happen:

if the user cancels the process
if the user fails to enter the correct captcha for 3 times (given the Captcha module is included)

Modules configuration

Common configuration needed for each module includes:

Parameter name	Function
`moduleName`	Mandatory. The name of the module we wish to include
`enabled`	Optional: Whether or not the module is needed in the flow

Below is the list of all available module names, with additional configuration parameters.

Phone
- otpVerification (optional, defaults to false): Ask for otp verification
DocumentScan
- showTutorial (optional, defaults to false): Show tutorial for document scan.
- showDocumentProviderScreen (optional, defaults to true): Specify true if you would like to show document provider screen to the user, or false if you would like to go directly to the capture.
- type - specify document type addressStatement, paymentProof, medicalDoc, otherDocument1, otherDocument2, otherDocument3.
Geolocation
- no additional parameters
UserConsent
- title: string, content: string
Signature
- title: (optional) string - Adds optional title to the top of the screen. Contains value of the title string key
- description: (optional) string - Adds optional description below the title. Contains value of the description string key
- descriptionMaxLines (optional): number - Specifies maximum amount of lines of text in the description
VideoSelfie: Available only for API level 21+.
- showTutorial (optional, defaults to false): Show tutorial for video selfie.
- selfieScanMode (optional, defaults to selfieMatch): selfieMatch | faceMatch; Specify if you would like to do selfie comparison, or comparison with the photo from ID.
- selfieLivenessCheck (optional, defaults to false): Check for user liveness during video selfie.
- showIdScan (optional, defaults to true): Ask for ID scan during video selfie.
- showVoiceConsent (optional, defaults to true): Ask for Voice consent during video selfie
- voiceConsentQuestionsCount (optional, defaults to 3): Choose number of questions for video selfie voice consent steps.
- cameraFacingConfiguration (optional): CameraFacingConfiguration. Specifies which camera will be used during each step in Video selfie.
IdScan
- showTutorial (optional, defaults to true): boolean
- idType (optional): id or passport. If omitted, the app will display a chooser to the user.
- idCategory (optional): primary or secondary. Default primary
- showRetakeScreen (optional, defaults to true): boolean
- enableFrontShownAsBackCheck (optional, defaults to false): boolean
- enableBackShownAsFrontCheck (optional, defaults to false): boolean
- showAutoCaptureRetakeScreen (optional, defaults to false): boolean
- enableRotationOnRetakeScreen (optional, defaults to true): boolean
- autocaptureUxMode (optional): countdown or holdStill. Default 'holdStill'
- showIDOverlay (optional, defaults to false): boolean
IdScanFront
- showTutorial (optional, defaults to true): boolean
- idType (optional): id or passport. If omitted, the app will display a chooser to the user.
- idCategory (optional): primary or secondary. Default primary
- showRetakeScreen (optional, defaults to true): boolean
- enableFrontShownAsBackCheck (optional, defaults to false): boolean
- enableBackShownAsFrontCheck (optional, defaults to false): boolean
- showAutoCaptureRetakeScreen (optional, defaults to false): boolean
- enableRotationOnRetakeScreen (optional, defaults to true): boolean
- autocaptureUxMode (optional): countdown or holdStill. Default 'holdStill'
- showIDOverlay (optional, defaults to false): boolean
IdScanBack
- showTutorial (optional, defaults to true): boolean
- idCategory (optional): primary or secondary. Default primary
- showRetakeScreen (optional, defaults to true): boolean
- enableFrontShownAsBackCheck (optional, defaults to false): boolean
- enableBackShownAsFrontCheck (optional, defaults to false): boolean
- showAutoCaptureRetakeScreen (optional, defaults to false): boolean
- enableRotationOnRetakeScreen (optional, defaults to true): boolean
- autocaptureUxMode (optional): countdown or holdStill. Default 'holdStill'
- showIDOverlay (optional, defaults to false): boolean
ProcessId
- enableIdSummaryScreen: boolean. Specifying false means no summary screen will be shown to the user once he fail to capture ID multiple times. Defaults to true.
Conference
- disableMicOnStart: boolean
SelfieScan
- showTutorial (optional, defaults to true): boolean
- lensesCheck (optional, defaults to true): boolean. Performs check if user is wearing glasses during Selfie Scan.
- cameraFacing (optional, defaults to front): front | back. Specifies which camera will be used during Selfie capture.
- faceMaskCheck (optional, defaults to false): boolean. This checks if a person has a mask on.
- brightnessThreshold (optional, defaults to 50): number. Adjust minimum requirements for a well lit face during capture.
FaceMatch
- idCategory (optional): primary or secondary. Default primary
- showUserExists (optional): defaults to true: boolean
- Note: has to be specified after IDScan and SelfieScan modules.
QrScan
- no additional parameters
Email
- no additional parameters
Approve
- forceApproval (optional, defaults to false): boolean - if true the user will be force-approved
UserScore
- mode (optional, defaults to accurate): accurate or fast. If accurate the results will be fetched from server, which may exhibit some latency, but will rely on server-side processing of information, which may be more reliable than on-device processing. If fast, then results based on on-device processing will be shown.
MLConsent
- type: gdpr | us
GovernmentValidation
- isBackgroundExecuted (optional): defaults to false: boolean
Antifraud
- no additional parameters
GlobalWatchlist
- no additional parameters
CustomWatchlist
- no additional parameters
Aes
- uploadDocument (optional): defaults to false: boolean
- downloadDocument (optional): defaults to false: boolean
Name
- no additional parameters
CURP
- validationEnabled (optional): defaults to true: boolean - Specifies should the CURP be validated on the server or not.
OCREdit
- isEditable (optional): defaults to false: boolean
eKYB
- checkBusinessName (optional): defaults to false: boolean
- checkAddress (optional): defaults to false: boolean
- checkTaxId (optional): defaults to false: boolean
eKYC
- checkName (optional): defaults to false: boolean
- checkEmail (optional): defaults to false: boolean
- checkAddress (optional): defaults to false: boolean
- checkPhone (optional): defaults to false: boolean
- checkSsn (optional): defaults to false: boolean
- checkDob (optional): defaults to false: boolean
- checkNationality (optional): defaults to false: boolean

Flow listeners

The SDK offers several types of listeners:

user cancellation
tracking events
step completion, for each module individually
step error, for each module individually
step update, for each module individually

User cancellation

If the user cancels the onboarding, startOnboarding and startWorkflow method result would have status - 'userCancelled'. On both platforms the user can cancel by pressing 'X' button that can be enabled using IncodeSdk.showCloseButton(true);, and additionally on Android the user can cancel by pressing the back key.

Tracking events

When onboarding has been started, information about events used to track all the user steps in their flow can be obtained using onEvents callback.

IncodeSdk.onEvents((e) => {
  for (const ev of e.events) {
    console.log(ev.event);
  }
});

e: Events - Parameter holding array of all events
events: EventDetails[] - Array of emitted events
event: Event - Event with fields:
- event: string - Unique identifier of the event
- data: string - JSON string with additional event details

Step completion

When onboarding session gets created, the information about the session can be obtained via IncodeSdk.onSessionCreated method.

IncodeSdk.onSessionCreated((session) => {
  console.log(
    'Onboarding session created, interviewId: ' + session.interviewId
  );
});

interviewId: String - Unique identifier of the onboarding session
token: String - Token created for this onboarding session

Note This method should be called before startOnboarding

When a step within the configured Onboarding flow is completed, the information can be obtained by registering a listener via IncodeSdk.onStepCompleted. This takes two arguments: (1) the module name and (2) the callback.

IncodeSdk.onStepCompleted({
  module: 'SelfieScan',
  listener: (selfieScanResult) => {
    console.log('SELFIE SCAN completed', selfieScanResult.result);
  },
});

IdScanFront

image: IncdImage object, containing pngBase64 of the captured front ID
croppedFace: IncdImage object, containing pngBase64 of the cropped face from the front ID
classifiedIdType: the String - Classified ID type by Incode, ie. Voter Identification
chosenIdType: the String - what did the user choose to capture id or passport
idCategory: String, category of the ID verified primary or secondary
status: the String . If value is other than ok you can consider the ID scan and/or validation did not come through successfully. The Incode UI will clearly inform the user about these errors and will attempt the scan several times, before responding with an error. Possible error values: errorClassification, noFacesFound, errorGlare, errorReadability, errorSharpness, errorTypeMismatch, userCancelled, unknownError, errorClassification, errorShadow, errorPassportClassification.

IdScanBack

image: IncdImage object, containing pngBase64 of the captured front ID
classifiedIdType: the String - Classified ID type by Incode, ie. Voter Identification
chosenIdType: the String - what did the user choose to capture id or passport
idCategory: String, category of the ID verified primary or secondary
status: the String . If value is other than ok you can consider the ID scan and/or validation did not come through successfully. The Incode UI will clearly inform the user about these errors and will attempt the scan several times, before responding with an error. Possible error values: errorClassification, noFacesFound, errorGlare, errorReadability, errorSharpness, errorTypeMismatch, userCancelled, unknownError, errorClassification, errorShadow, errorPassportClassification.

Notes:

result.data.birthDate is the epoch time.
result.status.back and result.status.front can take one of following values: ok or several others indicating an issue with the scanning. The Incode UI will clearly inform the user about these errors and will attempt the Scan several times, before responding with an error. Other errors are: errorClassification, noFacesFound, errorCropQuality, errorGlare, errorReadability, errorSharpness, errorTypeMismatch, userCancelled, unknownError, errorClassification, shadow, errorAddress, errorPassportClassification, errorReadability.

ProcessId

data: the basic IdScanOcrData object, containing most important data
ocrData: the String object, raw JSON containing full OCR data ie. exteriorNumber, interiorNumber, typeOfId, documentFrontSubtype

Notes:

result.data.birthDate is the epoch time.

Conference

This module starts a video conference call with the executive.

Example response for completion of the step:

{
  "step": "Conference",
  "result": {
    "status": "success"
  }
}

Example response for error of the step:

{
  "step": "Conference",
  "result": {
    "status": "error"
  }
}

The field result.status can have values userCancelled, invalidSession or error;

DocumentScan

The DocumentScan will attempt reading address from the provided document.

Note: If the user decides to skip this step, you will get a response with blank values, instead of nil/error.

Example response for completion of the step:

{
  "result": {
    "address": { // parsed OCR data
      "city": "Springfield",
      "colony": "Springfield",
      "postalCode": "555555",
      "state": "Serbia",
      "street": "Evergreen terrace"
    },
    "data": {"raw JSON OCR data"},
    "type": "addressStatement",
    "image": {"pngBase64": "/9j/4AAQSkZJRgABAQAAAQABAAD/4..."},
  },
  "step": "DocumentScan"
}

Example response for error of the step:

{
  "status": "userCancelled",
  "step": "DocumentScan"
}

The field status can have one of the following values: permissionsDenied, simulatorDetected or unknown.

Geolocation

The Geolocation steps yields the current location of the user. Example response for completion of the step:

{
  "result": {
    "city": "Springfield",
    "colony": "Springfield",
    "postalCode": "555555",
    "state": "Serbia",
    "street": "Evergreen terrace"
  },
  "step": "Geolocation"
}

The field status can have one of the following values: permissionsDenied, unknownError or noLocationExtracted.

UserConsent

In case the user has given the consent:

{
  "status": "success",
  "step": "UserConsent"
}

If the user declined to give the consent, the onboarding flow will be ended with a status userCancelled.

MLConsent

In case the user has given the machine learning consent:

{
  "status": "success",
  "step": "MLConsent"
}

If some error happened, the "status" field will be set to corresponding error. If the user declined to give the consent, the onboarding flow will be ended with a status userCancelled.

GovernmentValidation

This module enables your user to input their information to validate with Government services as a part of your flow.

On module completion, the result returned will look like this:

{
  "status": "success",
  "step": "GovernmentValidation"
}