# Flutter Plugin
# Latest Release
Version 1.28.0 (Changelog)
# Installation
Add this to your package's pubspec.yaml
file:
dependencies:
flutter_idensic_mobile_sdk_plugin: ^1.28.0
Then run:
flutter pub get
# Android
Please, make sure you are using Kotlin 1.5 and API level 21 (Android 5.0) or higher in your Android project.
# iOS
Ensure that you have bitcode disabled for the whole project and for the flutter_idensic_mobile_sdk_plugin
target under Pods
project in particular (Pods -> flutter_idensic_mobile_sdk_plugin -> Build Settings -> Enable Bitcode -> No
)
- Update
ios/Podfile
as follows:
platform :ios, '9.0'
source 'https://cdn.cocoapods.org/'
source 'https://github.com/SumSubstance/Specs.git'
# Enable MRTDReader (NFC) module
#ENV['IDENSIC_WITH_MRTDREADER'] = 'true'
# Enable VideoIdent module
#ENV['IDENSIC_WITH_VIDEOIDENT'] = 'true'
- Update
Info.plist
to have a description for the usage of the camera, the microphone, the photo library and the geolocation:
plutil -insert "NSCameraUsageDescription" -string "Let us take a photo" ios/Runner/Info.plist
plutil -insert "NSMicrophoneUsageDescription" -string "Time to record a video" ios/Runner/Info.plist
plutil -insert "NSPhotoLibraryUsageDescription" -string "Let us pick a photo" ios/Runner/Info.plist
plutil -insert "NSLocationWhenInUseUsageDescription" -string "Please provide us with your geolocation data to prove your current location" ios/Runner/Info.plist
# MRTDReader (NFC)
The MRTDReader
is a module that allows the SDK to detect and read the electronic chips placed on MRTD documents via NFC.
For Android platform the module comes out of the box. To enable iOS, please follow the instructions below.
- Update
ios/Podfile
:
# Enable MRTDReader (NFC) module
ENV['IDENSIC_WITH_MRTDREADER'] = 'true'
- Open up the iOS project in XCode
xed ios/
Then do as follows:
2.1. Turn on Near Field Communication Tag Reading
capability for your project’s target (here is how to)
2.2. Add to the application's Info.plist
file:
<key>NFCReaderUsageDescription</key>
<string>Let us scan the document for more precise recognition</string>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
<string>A0000002471001</string>
<string>A0000002472001</string>
<string>00000000000000</string>
</array>
# VideoIdent
The VideoIdent
is an optional module that is required only if you are going to use the Video Identification during the verification flow.
To enable the module, please follow the instructions below.
- Update
ios/Podfile
# Enable VideoIdent module
ENV['IDENSIC_WITH_VIDEOIDENT'] = 'true'
- Open up the iOS project in XCode
xed ios/
Then add Background mode
capability for your project’s target (here is how to) and select Audio, AirPlay, and Picture in Picture
option there. That's required for the video call not to be broken when the application goes into background.
- To enable
VideoIdent
module on Android, add the following dependency in your `android/app/build.gradle' file
dependencies {
...
// add dependency to enable videoident
implementation "com.sumsub.sns:idensic-mobile-sdk-videoident:<SDK version>"
...
}
# Usage
Before launching make sure you did the Backend routines
# Setup
import 'package:flutter_idensic_mobile_sdk_plugin/flutter_idensic_mobile_sdk_plugin.dart';
void launchSDK() async {
// From your backend get an access token for the applicant to be verified.
// The token must be generated with `levelName` and `userId`,
// where `levelName` is the name of a level configured in your dashboard.
//
// The sdk will work in the production or in the sandbox environment
// depend on which one the `accessToken` has been generated on.
//
final String accessToken = "your_access_token";
// The access token has a limited lifespan and when it's expired, you must provide another one.
// So be prepared to get a new token from your backend.
final onTokenExpiration = () async {
// call your backend to fetch a new access token (this is just an example)
return Future<String>.delayed(Duration(seconds: 2), () => "your new access token");
};
final SNSStatusChangedHandler onStatusChanged = (SNSMobileSDKStatus newStatus, SNSMobileSDKStatus prevStatus) {
print("The SDK status was changed: $prevStatus -> $newStatus");
};
final snsMobileSDK = SNSMobileSDK.init(accessToken, onTokenExpiration)
.withHandlers( // optional handlers
onStatusChanged: onStatusChanged
)
.withDebug(true) // set debug mode if required
.withLocale(Locale("en")) // optional, for cases when you need to override the system locale
.build();
final SNSMobileSDKResult result = await snsMobileSDK.launch();
print("Completed with result: $result");
}
The return type of the snsMobileSDK.launch()
method is the Future
of SNSMobileSDKResult type. Use it to determine the SDK status upon its closure.
Here is an example of the result
:
SNSMobileSDKResult(
success: false,
status: SNSMobileSDKStatus.Failed,
errorType: SNSMobileSDKErrorType.Unauthorized,
errorMsg: "Unauthorized access with accessToken=[your access token]",
actionResult: null
)
Please find a detailed description below.
# Launch
Next, you are able to use the launchSNSMobileSDK()
, as defined above, in order to launch the SDK.
For example:
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
...
Container(
alignment: Alignment.center,
child: RaisedButton(onPressed: () => launchSDK(),
child: Text("Launch Sumsub SDK")),
),
...
],
),
),
# Dismission
By default, once the applicant is approved the sdk will be dismissed in 3 seconds automatically. You can adjust this time interval or switch the automatic dismissal off by setting value of zero:
snsMobileSDK.withAutoCloseOnApprove(0)
Also, in case you need to close the SDK programmatically, here is what you can do:
snsMobileSDK.dismiss()
# Advanced
# Configuration
If it's required, you could provide an email and/or a phone number that will be assigned to the applicant initially:
.withApplicantConf({
"email": "...",
"phone": "..."
})
# Preferred Documents
For IDENTITY* steps, it's possible to specify the preferred country and document type to be selected automatically, therby bypassing the DocType Selector screen. Note that the parameters provided will be applied only if the corresponding combination of country and idDocType is allowed at the step according to the level configuration.
.withPreferredDocumentDefinitions({
"IDENTITY": {
"idDocType":"PASSPORT",
"country":"USA"
},
"IDENTITY2": {
"idDocType":"DRIVERS",
"country":"FRA"
}
})
# Disable Google ML Kit
This is an Android-specific feature
The SumSub SDK uses Google ML Kit face detection library if it is available with the application and builtin Android face detection otherwise. You can disable using ML Kit even if it is available.
.withDisableMLKit(true)
# Localization
You can customize or localize the texts used within the SDK through the MSDK Translations tool in the dashboard.
The language of the texts will be set according to the system locale, but you could override it with the locale you desire:
.withLocale(Locale("en"))
Please check the list of supported locales here.
# Strings
In addition to the MSDK Translations tool and .withLocale
described above, you can use .withStrings
option that allows you to define the strings locally. This could be helpful for iOS apps if you would like to avoid the Wordless Oops screen that could be rendered in case the network happens to be down during the SDK initialization and force the SDK to draw the Network Oops instead:
.withStrings({
"sns_oops_network_title": "Oops! Seems like the network is down.",
"sns_oops_network_html": "Please check your internet connection and try again.",
"sns_oops_action_retry": "Try again",
})
⚠️ Note that .withLocale
does not affect these strings, thus it's up to you to use the required localization.
# Analytics
The SDK collects and sends usage data to Sumsub servers. We don't track any sensitive data. Only general usage statistics is sent to us. It includes screen navigation events, UI controls interaction events and so on. We interpret the usage data in order to improve Sumsub. None of the data is sold or transfered to third parties, and we don't use it for advertisement.
If you still want to disable this feature, you can use the following to do this:
.withAnalyticsEnabled(false)
# Events
Various events happening along the processing could be delivered into an optional onEvent
handler:
final SNSEventHandler onEvent = (SNSMobileSDKEvent event) {
print("onEvent: $event");
};
final snsMobileSDK = SNSMobileSDK.init(accessToken, onTokenExpiration)
.withHandlers(
onEvent: onEvent
)
Each Event has eventType
and some parameters packed into payload
map, for example:
SNSMobileSDKEvent(
eventType: "StepInitiated",
payload: {
"idDocSetType": "IDENTITY"
}
)
# Possible events:
eventType | payload | Description |
---|---|---|
"ApplicantLoaded" | { | The applicant $applicantId has been loaded |
"StepInitiated" | { | Step $idDocSetType has been initiated |
"StepCompleted" | { | Step $idDocSetType has been fulfilled or cancelled |
"Analytics" | { | Analytics event $eventName has occured |
# Applicant Actions
There is a special way to use the SDK in order to perform Applicant actions.
Only the Face authentication action is supported at the moment
In order to run the SDK in applicant action mode, you need to
- Associate your applicant level with a customization of
Applicant actions
type in your dashboard - Make an Access Token with the
userId
,levelName
andexternalActionId
parameters
When an action is completed the status
will be set to .ActionCompleted
and the result structure will contain the actionResult
field that describes the outcome of the last invocation:
SNSMobileSDKResult(
success: true,
status: SNSMobileSDKStatus.ActionCompleted,
errorType: null,
errorMsg: null,
actionResult: SNSMobileSDKActionResult(
actionId: "5f9186b8aee05c5fa1ae11bb",
answer: SNSMobileSDKAnswerType.Green
)
)
An empty value of actionResult.answer
means that the action was cancelled.
# Action Result Handler
In addition, there is an optional onActionResult
handler, that allows you to handle the action's result upon it's arrival from the backend.
The user sees the "Processing..." screen at this moment.
final SNSActionResultHandler onActionResult = (SNSMobileSDKActionResult result) {
print("onActionResult: $result");
// you must return a `Future` that in turn should be completed with a value of `SNSActionResultHandlerReaction` type
// you could pass `.Cancel` to force the user interface to close, or `.Continue` to proceed as usual
return Future.value(SNSActionResultHandlerReaction.Continue);
};
final snsMobileSDK = SNSMobileSDK.init(accessToken, onTokenExpiration)
.withHandlers(
onActionResult: onActionResult
)
# API Reference
# SNSMobileSDKResult
An object describing the result of the last SDK launch:
Field | Type | Description |
---|---|---|
success | bool | The boolean value indicates whether there was an error at the moment the SDK was closed. Use errorType and errorMsg to see the reasons of the error, if there is one |
status | SNSMobileSDKStatus | SDK status expressed with SNSMobileSDKStatus enum |
errorType | SNSMobileSDKErrorType? | Error reason expressed with SNSMobileSDKErrorType enum |
errorMsg | String? | A verbose error description |
actionResult | SNSMobileSDKActionResult? | Describes the result of the latest applicant action's invocation, if any |
# SNSMobileSDKStatus
An enum describing the possible SDK statuses:
Case | Description |
---|---|
Ready | SDK is initialized and ready to be presented |
Failed | SDK has failed for some reason (see errorType and errorMsg for details) |
Initial | No verification steps have been passed yet |
Incomplete | Some, but not all, of the verification steps have been completed |
Pending | Verification is pending |
TemporarilyDeclined | Applicant has been declined temporarily |
FinallyRejected | Applicant has been finally rejected |
Approved | Applicant has been approved |
ActionCompleted | Applicant action has been completed |
# SNSMobileSDKErrorType
An enum describing the possible reasons for failure:
Case | Description |
---|---|
Unknown | Unknown or no failure |
InvalidParameters | An attempt to setup with invalid parameters |
Unauthorized | Unauthorized access detected (most likely accessToken is invalid or expired and couldn't be refreshed) |
InitialLoadingFailed | Initial loading from the backend has failed |
ApplicantNotFound | No applicant can be found for the given parameters |
ApplicantMisconfigured | Applicant has been found, but is misconfigured (most likely they lacks ID Docs) |
InititlizationError | An initialization error has occured |
NetworkError | A network error has occured (the user will be presented with the Network Oops screen) |
UnexpectedError | An unexpected error has occured (the user will be presented with the Fatal Oops screen) |
# SNSMobileSDKEvent
An object that represents an event happening along the processing:
Field | Type | Description |
---|---|---|
eventType | String | Event type |
payload | Map | Event payload |
# SNSMobileSDKActionResult
An object that represents the applicant action's result:
Field | Type | Description |
---|---|---|
actionId | String | Applicant action identifier to check the results against the server |
answer | SNSMobileSDKAnswerType? | Overall result expressed with SNSMobileSDKAnswerType enum |
# SNSMobileSDKAnswerType
An enum describing the possible answers:
Case | Description |
---|---|
Green | Positive answer |
Red | Negative answer |
Yellow | Neutral answer |
Error | Something went wrong |
Ignored | The check had not ever been started |
# SNSActionResultHandlerReaction
An enum describing the possible reactions passed back from the Action Result Handler:
Case | Description |
---|---|
Continue | Proceed as usual |
Cancel | Force the user interface to close |