# Cordova Plugin

# Latest Release

Version 1.17.0 (Changelog)

# Installation

The plugin will ask for access to the camera and possibly the microphone and the photo library 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 a part of the dialog box. In order to add the entries you must pass the variables CAMERA_USAGE, MICROPHONE_USAGE and PHOTO_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"

If you do not provide the variables, the defaults shown in the example above will be used instead.

# Capacitor

In case you are going to use the plugin in a Capacitor-powered app, please add the following line at the top of your ios/App/Podfile before the plugin adding:

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

# Usage

# Launch

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 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)
        .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.

# 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:

"StepInitiated"

{
  "idDocSetType": "$idDocSetType"
}

"StepCompleted"

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

# Applicant Actions

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

In order to use the SDK in applicant action mode, you need to have:

1. A flow of Applicant actions type.
2. An Access Token created with both userId 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's result: