Cordova plugin
Latest release: Version 1.33.1 (Changelog)
Installation
Capacitor note
In case you are going to use the plugin in a Capacitor-powered app, add the following line at the top of your
ios/App/Podfile
before adding the plugin.source 'https://github.com/SumSubstance/Specs.git'
Depending on the verification steps, the plugin might request access to the camera, microphone, photo library, and geolocation. Because of this, it is mandatory to have the corresponding usage description in the application Info.plist
file.
When the system prompts the user to allow access, the corresponding usage string is displayed as part of the dialog box.
To add the entries, you must pass the variables CAMERA_USAGE
, MICROPHONE_USAGE
, PHOTO_USAGE
and LOCATION_USAGE
on plugin install.
cordova plugin add @sumsub/cordova-idensic-mobile-sdk-plugin \
--variable CAMERA_USAGE="Let us take a photo" \
--variable MICROPHONE_USAGE="Time to record a video" \
--variable PHOTO_USAGE="Let us pick a photo" \
--variable LOCATION_USAGE="Please provide us with your geolocation data to prove your current location
If you do not provide the variables, the defaults shown in the example above will be used instead.
Attention
- Use Kotlin 1.7.10 and API level 21 (Android 5.0) or higher in your Android project.
- Disable bitcode for your iOS project.
Modules
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, the module comes out of the box. For iOS, to enable it, follow the instructions below:
- Use the
--with-MRTDReader
option during the plugin installation.
cordova plugin add @sumsub/cordova-idensic-mobile-sdk-plugin \
--with-MRTDReader
- Open the iOS project in XCode.
xed platforms/ios/
- Turn on the
Near Field Communication Tag Reading
capability for your project target. - Add to
{YourProjectName}-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 required only if you are going to use the video identification during verification.
To enable the module:
- Use the
--with-VideoIdent
option during the plugin installation.
cordova plugin add @sumsub/cordova-idensic-mobile-sdk-plugin \
--with-VideoIdent
- Open the iOS project in XCode.
xed platforms/ios/
- Add the
Background mode
capability for your project target and select theAudio, AirPlay, and Picture in Picture
option required for the video call not to be broken when the application goes into background.
eID
The EID
is an optional module required only if you are going to use "eID Verification" during the verification flow.
To enable the module:
- Use the
--with-EID
option during the plugin installation.
cordova plugin add @sumsub/cordova-idensic-mobile-sdk-plugin \
--with-EID
- Open the iOS project in XCode.
xed platforms/ios/
- Turn on the
Near Field Communication Tag Reading
capability for your project target. - Add to
{YourProjectName}-Info.plist
file.
<key>NFCReaderUsageDescription</key>
<string>Let us scan the eID card to verify your identity</string>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
<string>A0000002471001</string>
<string>E80704007F00070302</string>
</array>
Usage
Attention
Before launching, make sure you have configured your verification level and access token.
Launch
// 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.
//
let accessToken = 'your_access_token';
let snsMobileSDK = SNSMobileSDK.init(accessToken, () => {
// this is a token expiration handler. It will be called if the provided token is invalid or got expired
// call your backend to fetch a new access token (this is just an example)
return new Promise((resolve, reject) => {
resolve('new_access_token')
})
})
.withHandlers({ // Optional callbacks you can use to get notified of the corresponding events
onStatusChanged: (event) => {
console.log("onStatusChanged: [" + event.prevStatus + "] => [" + event.newStatus + "]");
}
})
.withDebug(true)
.withLocale('en') // Optional, for cases when you need to override the system locale
.build();
snsMobileSDK.launch().then(result => {
console.log("Sumsub SDK State: " + JSON.stringify(result))
}).catch(err => {
console.log("Sumsub SDK Error: " + JSON.stringify(err))
});
The snsMobileSDK.launch()
returns a Promise
that will be resolved with the Result object. Use it to determine the SDK status upon its closure.
Here is an example of the result
.
{
"success": false,
"status": "Failed",
"errorType": "Unauthorized",
"errorMsg": "Unauthorized access with accessToken=[your access token]"
}
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 is required, you can provide an email and/or phone number that will be assigned to the applicant initially.
.withApplicantConf({
"email": "...",
"phone": "..."
})
Preferred Documents
For IDENTITY\*
steps, it is possible to specify the preferred country and document type to be selected, automatically 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
Attention
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 will be set according to the system locale, but you can override it with the locale you desire.
.withLocale("en")
For a complete list of supported locales, see this article.
Strings
In addition to the MSDK Translations tool and .withLocale
, you can use .withStrings
option that allows you to define the strings locally.
This may 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 screen 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 is up to you to use the required localization.
Analytics
The SDK collects and sends usage data to Sumsub servers. We do not 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 transferred to third parties, and we do not 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 can be delivered into an optional onEvent
handler.
.withHandlers({
onEvent: (event) => {
console.log("onEvent: " + JSON.stringify(event));
}
})
Each Event has eventType
and some parameters packed into payload
hash, for example:
{
"eventType": "StepInitiated",
"payload": {
"idDocSetType": "IDENTITY"
}
}
Possible events:
eventType | payload | Description | |
---|---|---|---|
"ApplicantLoaded" | { | The applicant $applicantId has been loaded. | |
"StepInitiated" | { | Step $idDocSetType has been initiated. | |
"StepCompleted" | { | true } | Step $idDocSetType has been fulfilled or cancelled. |
"Analytics" | { | Analytics event $eventName has occurred. |
Applicant Actions
To run the iOS SDK in Applicant actions mode, you need to have:
- A verification level with the Applicant actions type.
- An access token created with the
userId
,levelName
, andexternalActionId
parameters.
Aside from the notes above, use the SDK the same way that you do with regular levels, but the further processing may differ depending on the action type.
The action type is configured for a particular level in the Dashboard and can be one of the following:
Additional Verification
Additional verification actions are processed identically to the regular level verifications. You configure and manage the SDK the same way. Nothing special is required.
Attention
The
Payment methods
step is not supported at the moment.
Face Auth
Face authentication actions are handled in a specific manner. The user is taken to the FaceScan (Liveness) screen directly and once the action is complete, the SDK will be automatically closed.
When an action is completed, the status
will be set to ActionCompleted
and the result structure would contain the actionResult
field that describes the outcome of the last action invocation.
{
"success": true,
"status": "ActionCompleted",
"actionResult": {
"actionId": "5f77648daee05c419400c572",
"answer": "GREEN"
}
}
An empty value of actionResult.answer
means that the action was cancelled.
Action Result Handler
In addition, for Face Auth actions, there is an optional onActionResult
handler that allows you to handle the action result upon its arrival from the backend.
The user sees the Processing... screen at this moment.
.withHandlers({
onActionResult: (result) => {
console.log("onActionResult: " + JSON.stringify(result));
// you must return a `Promise` that in turn should be resolved with
// either `cancel` to force the user interface to close, or `continue` to proceed as usual
return new Promise(resolve => {
resolve("continue");
})
}
})
API Reference
Result
An object described the outcome of the last SDK launch:
Field | Type | Description |
---|---|---|
success | Boolean | The boolean value indicates if there was an error on the moment the SDK is closed. Use errorType and errorMsg to see the reasons of the error if any. |
status | String | SDK status. |
errorType | String | A formal reason of the error if any. |
errorMsg | String | A verbose error description if any. |
actionResult | Object | Describes the result of the last Face Auth action's invocation if any. |
While success
and status
are always present, the rest fields are optional.
Status
Here is the possible SDK statuses:
Case | Description |
---|---|
Ready | SDK is initialized and ready to be presented. |
Failed | SDK fails for some reasons (see errorType and errorMsg for details). |
Initial | No verification steps are passed yet. |
Incomplete | Some but not all of the verification steps have been passed over. |
Pending | Verification is pending. |
TemporarilyDeclined | Applicant has been declined temporarily. |
FinallyRejected | Applicant has been finally rejected. |
Approved | Applicant has been approved. |
ActionCompleted | Face Auth action has been completed. |
Error type
Here is the possible error types:
Case | Description |
---|---|
Unknown | Unknown or no fail. |
InvalidParameters | An attempt to setup with invalid parameters. |
Unauthorized | Unauthorized access detected (most likely accessToken is invalid or expired and had failed to be refreshed). |
InitialLoadingFailed | Initial loading from backend is failed. |
ApplicantNotFound | No applicant is found for the given parameters. |
ApplicantMisconfigured | Applicant is found, but is misconfigured (most likely lacks of idDocs). |
InitializationError | An initialization error occured. |
NetworkError | A network error occurred (the user will be presented with Network Oops screen). |
UnexpectedError | Some unexpected error occurred (the user will be presented with Fatal Oops screen). |
Event
An object that represents an event happening along the processing:
Field | Type | Description |
---|---|---|
eventType | String | Event type. |
payload | Object | Event payload. |
Face Auth action result
An object that represents the Face Auth action result:
Field | Type | Description |
---|---|---|
actionId | String | Face Auth action identifier to check the results against the server. |
answer | String | Overall result. Typical values are GREEN , RED or ERROR . |
Updated 28 days ago