Latest release: Version 1.27.0 (Changelog)

Installation

The plugin will ask for access to the camera and possibly the microphone, the photo library and geolocation too. Because of this, it is mandatory to have the corresponding usage descriptions in the application's Info.plist file. When the system prompts the user to allow access, the corresponding usage string is displayed as part of the dialog box.

In order to add the entries, you must pass the variables CAMERA_USAGE, MICROPHONE_USAGE, PHOTO_USAGE andLOCATION_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.5 and API level 21 (Android 5.0) or higher in your Android project.
• Disable bitcode for your iOS project.

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:

1. Use the --with-MRTDReader option during the plugin installation.

cordova plugin add @sumsub/cordova-idensic-mobile-sdk-plugin \
  --with-MRTDReader

2. Open up the iOS project in XCode.

xed platforms/ios/

3. Turn on the Near Field Communication Tag Reading capability for your project’s target.
4. 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 that is required only if you are going to use the video identification during the verification flow.

To enable the module:

1. Use the --with-VideoIdent option during the plugin installation.

cordova plugin add @sumsub/cordova-idensic-mobile-sdk-plugin \
  --with-VideoIdent

2. Open up the iOS project in XCode.

xed platforms/ios/

3. Add the Background mode capability for your project’s target and select the Audio, AirPlay, and Picture in Picture option. That's required for the video call not to be broken when the application goes into background.

Capacitor

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 the plugin adding.

source 'https://github.com/SumSubstance/Specs.git'

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 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]"
}

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 can 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 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 of the texts 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'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 transferred 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 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:

"ApplicantLoaded"

{
  "applicantId": "$applicantId"
}

"StepInitiated"

{
  "idDocSetType": "$idDocSetType"
}

"StepCompleted"

{
  "idDocSetType": "$idDocSetType",
  "isCancelled": false|true
}

"Analytics"

{
  "eventName": "$eventName",
  "eventPayload": object
}

Applicant Actions

There is a special way to use the SDK in order to perform Applicant actions.

🚧

Attention

Only the Face authentication action is supported at the moment.

In order to run the SDK in applicant action mode:

1. Associate your applicant level with a customization of Applicant actions type in your dashboard.
2. Make an access token with the userId, levelName and externalActionId 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:

While successand status are always present, the rest fields are optional.

Status

Here is the possible SDK statuses:

Error Type

Here is the possible error types:

Event

An object that represents an event happening along the processing:

Action result

An object that represents the applicant action result: