# React Native Module
# Latest Release
Version 1.17.0 (Changelog)
# Installation
yarn add @sumsub/react-native-mobilesdk-module
# Android
Add the following repository to your android/build.gradle
file:
allprojects {
repositories {
// ...
maven { url "https://maven.sumsub.com/repository/maven-public/" }
// ...
}
}
# iOS
- Add as follows at the top of
ios/Podfile
:
source 'https://cdn.cocoapods.org/'
source 'https://github.com/SumSubstance/Specs.git'
Then run:
npx pod-install
If it fails with CocoaPods could not find compatible versions for pod "IdensicMobileSDK"
message then do as follows:
cd ios && pod update IdensicMobileSDK && cd ..
- Update
Info.plist
to have description for the camera, microphone and the photo library usage
plutil -insert "NSCameraUsageDescription" -string "Let us take a photo" ios/${PWD##*/}/Info.plist
plutil -insert "NSMicrophoneUsageDescription" -string "Time to record a video" ios/${PWD##*/}/Info.plist
plutil -insert "NSPhotoLibraryUsageDescription" -string "Let us pick a photo" ios/${PWD##*/}/Info.plist
# Usage
Before launching make sure you did the Backend routines
# Setup
import SNSMobileSDK from '@sumsub/react-native-mobilesdk-module';
// ...
let launchSNSMobileSDK = () => {
let apiUrl = "https://test-api.sumsub.com" // or https://api.sumsub.com
let flowName = "msdk-basic-kyc" // or set up your own with the dashboard
let accessToken = "your_access_token" // generate one on the backend
let snsMobileSDK = SNSMobileSDK.Builder(apiUrl, flowName)
.withAccessToken(accessToken, () => {
// this is a token expiration handler, 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 fetch('http://example.org/', {
method: 'GET',
}).then(resp => {
// return a fresh token from here
return '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 + "]");
},
onLog: (event) => {
console.log("onLog: [Idensic] " + event.message);
}
})
.withDebug(true)
.withSupportEmail('[email protected]')
.withLocale('en') // Optional, for cases when you need to override 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 a 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]"
}
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:
<Button
onPress={launchSNSMobileSDK}
title="Launch SumSub SDK"
/>
# Dismission
Normally the user closes the sdk himself, but if you need to do it programmatically, here is the helper:
snsMobileSDK.dismiss()
# Advanced
# Events
Various events happening along the processing could 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 |
---|---|---|
"StepInitiated" | { | Step $idDocSetType has been initiated |
"StepCompleted" | { | Step $idDocSetType has been fulfilled or cancelled |
# 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 use the SDK in applicant action mode, you need to have:
- A flow of
Applicant actions
type. - An Access Token created with both
userId
andexternalActionId
parameters.
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's 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, 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.
.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 applicant 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 | Applicant 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) |
InititlizationError | An initialization error occured |
NetworkError | A network error occured (the user will be presented with Network Oops screen) |
UnexpectedError | Some unexpected error occured (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 |
# Action Result
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 | String | Overall result. Typical values are GREEN , RED or ERROR |