Incode Onboarding Flutter SDK
Incode Onboarding provides effortless onboarding where security matters. Incode Onboarding is part of Incode's Omnichannel Biometric Identity Platform, which is powered by Incode's world class face recognition, liveness detection and ID validation models.
In this repo you can find an example onboarding an app that uses Incode Onboarding Flutter SDK to enable remote account opening.
Contents:
- SDK Setup
- Updating to latest version
- Usage Example
- Modules
- SDK results
- Advanced usage
- Customization
- SDK Mode
- Known issues
SDK Setup
Requirements
- Flutter version >=1.20.0
Installation
flutter-incode-sdk:
git:
url: git@github.com:Incode-Technologies-Example-Repos/IncdOnboardingFlutter.git
ref: master
Additional setup for iOS
After installation, it's necessary to do the linking for the iOS, after running the command above.
- Change your Podfile so it adds Incode sources and so it requires deployment target 11 or higher:
source 'https://github.com/CocoaPods/Specs.git'
source 'git@github.com:Incode-Technologies-Example-Repos/IncdDistributionPodspecs.git'
-platform :ios, '10.0'
+platform :ios, '11.0'
- Run
pod install
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 user's current location in order to detect exact location for the geolocation step.NSMicrophoneUsageDescription
- The SDK uses a microphone for performing video calls during the video conference step, or for doing speech recognition during a video selfie.
Additional setup for Android
- Modify
app/build.gradle
so that you enablemultiDexEnabled
and set the minimum API level to 17:
defaultConfig {
…
multiDexEnabled true
minSdkVersion 17
}
- Modify your
build.gradle
so it contains an artifactory username and password, provided by Incode:
allprojects {
repositories {
...
+ jcenter()
+ maven {
+ url "https://repo.incode.com/artifactory/libs-incode-welcome"
+ credentials {
+ username = "ARTIFACTORY_USERNAME"
+ password = "ARTIFACTORY_PASSWORD"
+ }
+ }
...
}
}
Updating to latest version
Run flutter pub upgrade
or flutter packages upgrade
, and in case iOS SDK version was updated run pod install --repo-update
and pod update IncdOnboarding
inside your ios folder.
Usage example
- Initialize the SDK
IncodeOnboardingSdk.init(
apiKey: 'YOUR_API_KEY',
apiUrl: 'YOUR_API_URL',
testMode: false,
onError: (String error) {
print('Incode init failed: $error');
},
onSuccess: () {
// Update UI, safe to start Onboarding
print('Incode initialize successfully!');
},
);
apiUrl
and apiKey
will be provided to you by Incode.
If you are running the app on a simulator, please set the testMode
parameter to 'true'.
- Configure Onboarding Flow
First, create an instance of
OnboardingFlowConfiguration
like this:
OnboardingFlowConfiguration flowConfig = OnboardingFlowConfiguration()
Depending on your needs you should specify the steps you want to include. An example of this could be:
flowConfig.addPhone();
flowConfig.addIdScan();
flowConfig.addSelfieScan();
flowConfig.addFaceMatch();
flowConfig.addGeolocation();
flowConfig.addVideoSelfie();
flowConfig.addUserScore();
flowConfig.addApproval();
The steps will be executed in the order you added them to the flowConfig.
Second, you should create an instance of OnboardingSessionConfiguration
:
OnboardingSessionConfiguration sessionConfig = OnboardingSessionConfiguration();
- Start the onboarding like this:
IncodeOnboardingSdk.startOnboarding(
sessionConfig: sessionConfig,
flowConfig: flowConfig,
onSuccess: () {
print('Incode Onboarding completed!');
},
onError: (String error) {
print('Incode onboarding error: $error');
},
onSelfieScanCompleted: (SelfieScanResult result) {
print('Selfie completed');
},
onIdValidationCompleted: (IdValidationResult result) {
print('ID validation completed');
},
);
Once all the steps are completed by the user the onSuccess
method will be called.
In case some error occured that stopped the flow from completing, the onError
method will be called.
To listen for the results of the steps in the flow as soon as they're completed, you can add optional callback methods, ie. onSelfieScanCompleted
and onIdValidationCompleted
that were added in the above example.
Modules
The modules supported by the SDK are listed here, and elaborated in more detail throughout the rest of this document.
Phone
- Ask the user to enter a phone number.IdScan
- Ask the user to capture an ID or Passport.ProcessId
- Process the ID in case the Id Scan was separated to front and back captures.SelfieScan
- Ask the user to capture a selfie.FaceMatch
- Perform a face match between the captured ID and selfieGeolocation
- Get the information about the users current location.VideoSelfie
- Records the device's screen while the user needs to do a selfie, show his ID, answer a couple of questions and verbally confirms that they accept the terms and conditions. The recorded video is then uploaded and stored for later usage.- ⚠️ Android note: Available only for API level 21+.
UserScore
- Shows the info and scoring for all the steps performedSignature
- Ask the user to draw a signatureDocumentScan
- Ask the user to capture a documentCaptcha
- Ask the user to complete CAPTCHACURP
- Validate user's CURP from the IDApprove
- Approves the current onboarding session and adds the user to the Omni database (based on a score).
Modules configuration
Below is the list of all available modules, with additional configuration parameters:
- Phone
- no additional parameters
- IdScan
showTutorials
(optional, defaults totrue
): booleanidType
(optional):IdType.id
orIdType.passport
. If omitted, the app will display a chooser to the user.idCategory
(optional):IdCategory.primary
orIdCategory.secondary
scanStep
(otpional): If you wish to separate the front and back ID scan, specifyScanStepType.front
orScanStepType.back
.ScanStepType.both
is the default and will capture both the front and back of the ID, and process the ID afterwards. If you specifyScanStepType.front
orScanStepType.back
you will have to add theProcessId
module after the captures.
- ProcessId (used only if
ScanStepType.front
orScanStepType.back
were specified asscanStep
forIdScan
module)idCategory
(optional):IdCategory.primary
orIdCategory.secondary
- Note: Please make sure to call this module only after both the
ScanStepType.front
andScanStepType.back
IdScans are completed.
- SelfieScan
showTutorials
(optional, defaults totrue
): bool?
- FaceMatch
idCategory
(optional, defaults toprimary
):IdCategory.primary
orIdCategory.secondary
- Note: has to be specified after IDScan and SelfieScan modules.
- Geolocation
- no additional parameters
- VideoSelfie:
showTutorials
(optional, defaults totrue
): boolean. Show tutorial for video selfie.selfieScanMode
(optional, defaults toselfieMatch
):SelfieScanMode.selfieMatch
orSelfieScanMode.faceMatch
; Specify if you would like to do a selfie comparison, or comparison with the photo from the ID.selfieLivenessCheck
(optional, defaults tofalse
): boolean. Check for user liveness during video selfie.showIdScan
(optional, defaults totrue
): bool?. Ask for ID scan during video selfie.showDocumentScan
(optional, defaults totrue
): boolean. Ask for proof of address during video selfieshowVoiceConsent
(optional, defaults totrue
): boolean. Ask for voice consent during video selfievoiceConsentQuestionsCount
(optional, defaults to3
): integer. Choose a number of questions for video selfie voice consent steps.
- UserScore
mode
(optional, defaults toaccurate
):UserScoreFetchMode.accurate
orUserScoreFetchMode.fast
. Ifaccurate
, the results will be fetched from the server, which may exhibit some latency, but will rely on server-side processing of information. This option may be more reliable than on-device processing. Iffast
, then results based on on-device processing will be shown.
- Approve
forceApproval
(optional, defaults tofalse
): boolean - iftrue
, the user will be force-approved
- Signature
- no additional parameters
- DocumentScan
showTutorials
(optional, defaults totrue
): boolean. Show the tutorial for document scan.showDocumentProviderOptions
(optional, defaults tofalse
).documentType
(optional, defaults toDocumentType.addressStatement
).
- Captcha
- no additional parameters
- CURP
- no additional parameters
Modules interdependencies
ProcessId
module expectsIdScan
bothScanStepType.front
orScanStepType.back
to have executed.FaceMatch
module expectsIdScan
andSelfieScan
to have been executed, in order to perform the match. In other words,IdScan
andSelfieScan
must precedeFaceMatch
VideoSelfie
module expectsIdScan
infaceMatch
mode, orSelfieScan
inselfieMatch
mode.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
andApprove
modules do not depend on each other, so their order can be arbitrary.
SDK results
Phone
Specify onAddPhoneNumberCompleted
to the startOnboarding
method, to receive PhoneNumberResult
:
phone
: String, the phone number the user entered
IdScan
1) Specify onIdFrontCompleted
, onIdBackCompleted
to the startOnboarding
method, to receive IdScanResult
results:
image
: Captured ID imagebase64Image
: String. Captured front ID in base64 formatcroppedFace
: Cropped face from captured ID imagechosenIdType
: User chosen type on ID selection screen -id
orpassport
classifiedIdType
: type of the captured IDidCategory
: IdCategory. Category of the scanned IDscanStatus
: If the status has a value other thanIdValidationStatus.ok
you can consider the ID scan and/or validation did not come through successfully. Other status messages are:errorClassification
,noFacesFound
,errorCropQuality
,errorGlare
,errorSharpness
,errorTypeMismatch
,userCancelled
,unknown
,errorAddress
,errorPassportClassification
.
2) Specify onIdProcessed
to the startOnboarding
method, to receive String
OCR results:
ocrData
: String. Raw JSON containing full OCR data ie.exteriorNumber
,interiorNumber
,typeOfId
,documentFrontSubtype
SelfieScan
Specify onSelfieScanCompleted
to the startOnboarding
method, to receive SelfieScanResult
:
image
: Uint8List. Captured Selfie imagespoofAttempt
: boolean.false
means that the person trying to do selfie is a real person.true
means it is a spoof attempt, meaning that person is trying to spoof the system by pretending to be someone else using physical paper, a digital photo or other methods.nil
means that an unexpected error occured, so it couldn't be determined if the selfie scan was a spoof attempt or not.base64Images
: SelfieScanBase64Images. Contains an image, in different formats, taken during selfie scanselfieBase64
: String. Captured selfie base64 imageselfieEncryptedBase64
: String. Captured selfie encrypted base64 image
FaceMatch
Specify onFaceMatchCompleted
to the startOnboarding
method, to receive FaceMatchResult
:
faceMatched
: boolean.true
means the person's selfie matched successfully with the front ID.false
means that the person's selfie isn't matched with the front ID image.null
means that the front ID image wasn't uploaded at all, so the face match service didn't have data to compare with the selfieidCategory
: IdCategory. Category of the ID that was used for face match.existingUser
: boolean. Indicates whether the user is a new or existing one.existingInterviewId
: String. If user is existing this field is populated with an existing interview ID.
Geolocation
Specify onGeolocationCompleted
to the startOnboarding
method, to receive GeoLocationResult
:
city
: Stringcolony
: StringpostalCode
: Stringstate
: Stringstreet
: String
VideoSelfie
Specify onVideoSelfieCompleted
to the startOnboarding
method, to receive VideoSelfieResult
:
success
: boolean,true
if the video selfie was performed successfully,false
otherwise.
UserScore
Specify onUserScoreFetched
to the startOnboarding
method, to receive UserScoreResult
.
Example UserScoreResult
for completion of the module:
{
ovarall: {
value: '0.0/100',
status: 'ok'
},
faceRecognition: {
value: '0.0/100',
status: 'warn',
},
liveness: {
value: '95.2/100',
status: 'manual',
},
idValidation: {
value: '79.0/100',
status: 'fail',
},
}
The field status
can have one of the following values: warning
, unknown
, manual
, fail
or ok
.
Approve
Specify onApproveCompleted
to the startOnboarding
method, to receive ApprovalResult
.
success
: boolean.true
if the approval was successful,false
otherwise.uuid
: String. Customer II of the newly created customer if approval was successful,null
otherwise.customerToken
: String. Customer token for newly created customer if approval was successful,null
otherwise.
Signature
Specify onSignatureCollected
to the startOnboarding
method, to receive SignatureResult
.
signature
: Uint8List?. Collected signature image.
Document
Specify onDocumentScanCompleted
to the startOnboarding
method, to receive DocumentScanResult
.
image
: Uint8List. Document scan image.documentType
: DocumentType. Type of scanned document.address
: Map<String, dynamic>?. Address fetched from the document. Will be available only forDocumentType.addressStatement
ocrData
: Raw JSON containing full OCR data
Captcha
Specify onCaptchaCompleted
to the startOnboarding
method, to receive CaptchaResult
.
captcha
: String. Entered captcha.
CURP
Specify onCurpValidationCompleted
to the startOnboarding
method, to receive CurpValidationResult
.
curp
: String. User's CURP.valid
: boolean. Indicates if the user's CURP is valid. Null means there is no result (user decided to skip).data
: Map<String, dynamic>. The user's CURP data.
Advanced Usage
If you would like to use SDK in a way that the default flow builder doesn't provide,
you can use SDK APIs for advanced usage where you'll be able to fully customize the experience of the flow.
For example, you can call individual SDK modules, or group SDK modules in sections, and return control to your host application in between.
Create new onboarding session
Before calling any other Onboarding SDK component, it is necessary to create a new onboarding session:
IncodeOnboardingSdk.createNewOnboardingSession(
sessionConfig: OnboardingSessionConfiguration(),
onError: (String error) {
print('Incode onboarding session error: $error');
},
onSuccess: (OnboardingSessionResult result) {
print('Incode Onboarding session created! $result');
},
);
Optionally, you can specify:
- region:
ALL
by default - list of
OnboardingValidationModule
items. This list determines which modules are used for verification and calculation of the onboarding score. If you pass null as validationModuleList, the default values will be used: id, faceRecognition and liveness. - customFields: custom fields which are sent to the server.
- externalId: User identifier outside of the Incode Omni database.
- configurationId: Flow configurationId found on the Incode dashboard.
Configure section flow
Once the new onboarding session is created (See previous section), you can separate the Onboarding SDK flow into multiple sections based on your needs:
IncodeOnboardingFlowConfiguration flowConfig = IncodeOnboardingFlowConfiguration();
flowConfig.addIdScan();
Start onboarding section
Once the IncodeOnboardingFlowConfiguration
is created, call the following method:
IncodeOnboardingSdk.startNewOnboardingSection(
flowConfig: flowConfig,
flowTag: 'idSection',
onError: (String error) {
print('Incode onboarding session error: $error');
},
onIdValidationCompleted: (IdValidationResult result) {
print(result);
onCompleted();
},
onOnboardingSectionCompleted: (String flowTag) {
print('section completed');
},
);
Finish onboarding session
Make sure to call finishFlow()
at the end of the flow (when you are sure the user has finished all onboarding modules and you won't be reusing the same interviewId again).
IncodeOnboardingSdk.finishFlow();
Resuming an existing onboarding session
To continue an existing onboarding when the app is uninstalled and installed again in the middle of the flow, make sure to call the IncodeOnboardingSdk.setOnboardingSession()
API. It is important to call this API prior to making any other API calls in order to reset the configuration that got lost during the uninstall. You can do this by following the code below:
IncodeOnboardingSdk.setOnboardingSession(
config: OnboardingSessionConfiguration(),
interviewId: 'Your interviewId',
onError: (String error) {
print('Incode set onboarding session error: $error');
},
onSuccess: (OnboardingSessionResult result) {
print('Incode set onboarding session success! $result');
},
);
Customization
To change theme and resources (text, images and videos) on an Android platform please look at a guide here.
To change resources on an iOS platform please look at a guide here.
To change themes on an iOS platform, specify the JSON theme configuration and call IncodeOnboardingSdk.setTheme(theme: theme)
:
Map<String, dynamic> theme = {
"buttons": {
"primary": {
"states": {
"normal": {
"cornerRadius": 16,
"textColor": "#ffffff",
"backgroundColor": "#ff0000"
},
"highlighted": {
"cornerRadius": 16,
"textColor": "#ffffff",
"backgroundColor": "#5b0000"
},
"disabled": {
"cornerRadius": 16,
"textColor": "#ffffff",
"backgroundColor": "#f7f7f7"
}
}
}
},
"labels": {
"title": {"textColor": "#ff0000"},
"secondaryTitle": {"textColor": "#ff0000"},
"subtitle": {"textColor": "#ff0000"},
"secondarySubtitle": {"textColor": "#ff0000"},
"smallSubtitle": {"textColor": "#ff0000"},
"info": {"textColor": "#ff0000"},
"secondaryInfo": {"textColor": "#ff0000"},
"body": {"textColor": "#ff0000"},
"secondaryBody": {"textColor": "#ff0000"},
"code": {"textColor": "#ff0000"}
}
};
IncodeOnboardingSdk.setTheme(theme: theme);
SDK Mode
You can choose between two modes: SdkMode.standard
and SdkMode.captureOnly
. SdkMode.standard
is the default, but if you would like to skip the image upload and server validations for the ID and selfie scan, you can specify captureOnly mode using method:
IncodeOnboardingSdk.setSdkMode(sdkMode: SdkMode.captureOnly);
Known issues
- Currently, running the app on iOS simulator from VSCode isn't supported. For now, please run the app from Xcode if you want to test it on an iOS Simulator.
NOTE: Don't forget to set
testMode
totrue
before running the app.