# iOS SDK

# Getting started

Latest release: Version 1.17.1 (Changelog)

# Requirements

• iOS 9.0 or later (FaceScan3D module requires iOS 10+)
• Xcode 11+

# Resources

• IdensicMobileSDK iOS Demo - a demo project in Swift.
• sample.swift - Swift sample code. Feel free to use it as a boilerplate.
• applicantActions-sample.swift - Sample code for the usage in Applicant Actions mode.

# Installation

This framework is meant to be installed via cocoapods.

# Podfile

Update your Podfile:

• Add source options for SumSubstance and Cocoapods repositories
• Add IdensicMobileSDK dependency to your target

platform :ios, '9.0'

source 'https://cdn.cocoapods.org/'
source 'https://github.com/SumSubstance/Specs.git'

target 'YourApp' do

  pod 'IdensicMobileSDK'

  # any other dependencies
end

Then run this in your project directory

pod install

# Permissions

The framework will ask for access to the camera and possibly the microphone and the photo library too. Because of this, it is required to have the corresponding usage descriptions in the application's Info.plist file:

<key>NSCameraUsageDescription</key>
<string>Let us take a photo</string>
<key>NSMicrophoneUsageDescription</key>
<string>Time to record a video</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Let us pick a photo</string>

Also, if your app targets iOS 10 and below, it's required to turn on the iCloud Documents capabilities in Xcode as described here

# Basic Usage

# Initialization

First of all, import the framework:

import IdensicMobileSDK

Then declare the initialization parameters:

let baseUrl = "https://test-api.sumsub.com" // or "https://api.sumsub.com" for production
let flowName = "msdk-basic-kyc" // the name of the applicant flow (must be set up via the dashboard)
let accessToken = "..." // use the `accessToken` for the applicant to be verified got from your backend
let locale = Locale.current.identifier // locale in the form of "en" or "en_US"
let supportEmail = "[email protected]" // optional support email

While baseUrl, flowName and accessToken are mandatory, locale and supportEmail are optional

• If you do not provide locale, the current one will be used automatically
• Setting supportEmail is just a convenient way to configure the Support screen; it's ok to set it to nil and configure Support Items later on.

Next you instantiate SNSMobileSDK and check if setup succeeded:

let sdk = SNSMobileSDK(
    baseUrl: baseUrl,
    flowName: flowName,
    accessToken: accessToken,
    locale: locale,
    supportEmail: supportEmail
)

guard sdk.isReady else {
    print("Initialization failed: " + sdk.verboseStatus)
    return
}

Here you create an instance of the SDK and ensure that the setup was successful with sdk.isReady, if it happens to fail, you will be able to pinpoint the reason by printing sdk.verboseStatus.

The next important step is to set the tokenExpirationHandler. The matter is that typically the access token is valid for a rather short period of time and when it's expired you must provide another one (see Token Expiration for details).

sdk.tokenExpirationHandler { (onComplete) in
    get_token_from_your_backend { (newToken) in
        onComplete(newToken)
    }
}

Most likely, you will then tune up the sdk a bit further by assigning Handlers and Callbacks, and possibly by applying some Customization, but that's just an optional feature.

# Presentation

In any case once setup is done you are ready to present the SDK on the screen:

yourViewController.present(sdk.mainVC, animated: true, completion: nil)

Since SDK contains its own navigation stack, it's required to be presented modally instead of being pushed.

You can also use a shortcut like this:

sdk.present(from: yourViewController)

Or even shorter if it's comfortable for you to present the sdk on the key window's root view controller:

sdk.present()

# Dismission

Normally the user closes the sdk himself, but if you need to do it programmatically, here is the helper:

sdk.dismiss()

# Handlers

Technically the handlers are optional, but you are strongly encouraged to provide at least tokenExpirationHandler to make sure that the access token always is live.

# Token Expiration

Because of the limited lifespan of the accessToken, it's important that you are able to handle the situation where the token expires and needs to be refreshed. As a solution to this, you set tokenExpirationHandler. The handler should make a call to your backend, obtain the newToken and then pass it back to the sdk by running onComplete closure.

sdk.tokenExpirationHandler { (onComplete) in
    get_token_from_your_backend { (newToken) in
        onComplete(newToken)
    }
}

⚠️ onComplete must be executed even if you fail to provide a new token, just pass nil in this case.

# Verification Completion

You can use verificationHandler to be informed when the verification process has been concluded with a final decision. The parameter isApproved lets you know if the applicant was approved or finally rejected. If you'd like to get notified about any other stages of the verification process, use onStatusDidChange described below.

sdk.verificationHandler { (isApproved) in
    print("verificationHandler: Applicant is " + (isApproved ? "approved" : "finally rejected"))
}

# Dismission Control

You can take over the dismissal control by assigning dismissHandler. The handler takes the current sdk instance and the mainVC controller. It's up to you to dismiss the mainVC in the manner that you see fit.

sdk.dismissHandler { (sdk, mainVC) in
    mainVC.dismiss(animated: true, completion: nil)
}

# Callbacks

Callbacks are completely optional. Use them if you feel that they will be helpful.

# Status Updates Notification

Use onStatusDidChange callback to get notified about the stages of the verification process.

The callback takes two parameters. The first one sdk is the SDK instance, and the last one prevStatus gives you a chance to know the previous value of the status. Following this, you are able to examine sdk.status enum in order to determine the current sdk status.

sdk.onStatusDidChange { (sdk, prevStatus) in

    print("onStatusDidChange: [\(sdk.description(for: prevStatus))] -> [\(sdk.description(for: sdk.status))]")

    switch sdk.status {

    case .ready:
        // Technically .ready couldn't ever be passed here, since the callback has been set after `status` became .ready
        break

    case .failed:
        print("failReason: [\(sdk.description(for: sdk.failReason))] - \(sdk.verboseStatus)")

    case .initial:
        print("No verification steps are passed yet")

    case .incomplete:
        print("Some but not all of the verification steps have been passed over")

    case .pending:
        print("Verification is pending")

    case .temporarilyDeclined:
        print("Applicant has been temporarily declined")

    case .finallyRejected:
        print("Applicant has been finally rejected")

    case .approved:
        print("Applicant has been approved")

    case .actionCompleted:
        print("Applicant action has been completed")
    }
}

# Events Notification

Subscribing to onEvent callback allows you to be aware of the events happening along the processing.

Events are passed into the callback as instances of a class inherited from the base SNSEvent class, this way each event has its eventType and some parameters packed into payload dictionary. So, depending on your needs, you can get event parameters either by examining the payload directly or by casting the given event instance to a specific SNSEvent* class according to its type.

sdk.onEvent { (sdk, event) in

    switch event.eventType {

    case .stepInitiated:
        if let event = event as? SNSEventStepInitiated {
            print("onEvent: Step \(event.idDocSetType) has been initiated")
        }

    case .stepCompleted:
        if let event = event as? SNSEventStepCompleted {
            print("onEvent: Step \(event.idDocSetType) has been \(event.isCancelled ? "cancelled" : "fulfilled")")
        }

    @unknown default:
        print("onEvent: eventType=\(event.description(for: event.eventType)) payload=\(event.payload)")
    }

}

# Dismiss Notification

An optional way to be notified when mainVC is dismissed:

sdk.onDidDismiss { (sdk) in
    print("onDidDismiss: sdk has been dismissed with status [\(sdk.description(for: sdk.status))]")
}

# Logging

There's no need to mention the importance of logs in the case that something goes wrong.

# Log Level

By default SDK tries not to spam your console and will print only when something critical has happened, however, sometimes, it makes sense to know what's going on under the hood.

You can choose the desired logLevel from .off that logs nothing, through .error (default), .warning, .info, .debug and up to .trace that will try to log as much as possible.

sdk.logLevel = .error

# Log Interception

By default SDK uses NSLog for logging purposes. If, for some reason, it does not work for you, feel free to use logHandler to intercept log messages and direct them as required.

sdk.logHandler { (level, message) in
    print(Date(), "[Idensic] \(message)")
}

# Customization

# Support Items

Support items define the ways in which your users will be prompted to contact you at the Support screen. Initially if non-empty supportEmail parameter passed during initialization, then an Email item would be created automatically.

Feel free to reconfigure support items as necessary. In order to do so, you could either assign an array of items to sdk.supportItems property directly, or use sdk.addSupportItem helper to add them one by one.

sdk.addSupportItem { (item) in
    item.title = NSLocalizedString("URL Item", comment: "")
    item.subtitle = NSLocalizedString("Tap me to open an url", comment: "")
    item.icon = UIImage(named: "AppIcon")
    item.actionURL = URL(string: "https://google.com")
}

sdk.addSupportItem { (item) in
    item.title = NSLocalizedString("Callback Item", comment: "")
    item.subtitle = NSLocalizedString("Tap me to get callback fired", comment: "")
    item.icon = UIImage(named: "AppIcon")
    item.actionHandler { (supportVC, item) in
        print("[\(item.title)] tapped")
    }
}

Each item must have a mandatory title, optional icon, subtitle and an action expressed with actionURL or actionHandler. If actionHandler is defined, it would be called when the item is tapped, otherwise actionURL would be opened with UIApplication's openURL: method. If no actionURL and no actionHandler are provided, then no action would be taken on tap.

# Theme

The theme allows you to customize things such as fonts, colors and images used across SDK. The default theme is accessible once the sdk is initialized. So depend on your needs you either adjust the theme in place

sdk.theme.sns_CameraScreenTorchButtonTintColor = .white

or inherit from SNSTheme and apply your own theme at once

sdk.theme = OwnTheme()

class OwnTheme: SNSTheme {
    override init() {
        super.init()

        sns_CameraScreenTorchButtonTintColor = .white
    }
}

All of the customizable options start from sns_ prefix, so when you start typing, you will begin to see them all.

# Localization

You can customize or localize the texts used within the SDK through the MSDK Translations tool in the dashboard.

# Applicant Actions

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

# Action Flow

In order to run the SDK in applicant action mode, you need to create an applicant flow of Applicant actions type in the dashboard and specify its name as the flowName initialization parameter. Also, it'll be required to make an Access Token not only with the userId parameter, but with the externalActionId one as well.

Aside from the notes above, you manage the sdk the same way that you do with regular flows, the only difference is in how you get the action's result.

When an action is completed, the sdk.status will be set to .actionCompleted and sdk.actionResult will contain the outcome of the last action's invocation.

You can use onDidDismiss, dismissHandler or onStatusDidChange callback in order to determine the sdk's status and get the action's result.

For example:

sdk.onDidDismiss { (sdk) in

    switch sdk.status {

    case .failed:
        print("failReason: [\(sdk.description(for: sdk.failReason))] - \(sdk.verboseStatus)")

    case .actionCompleted:
        // the action was performed or cancelled

        if let result = sdk.actionResult {
            print("Last action result: actionId=\(result.actionId) answer=\(result.answer ?? "<none>")")
        } else {
            print("The action was cancelled")
        }

    default:
        // in case of an action flow, the other statuses are not used for now,
        // but you could see them if the user closes the sdk before the flow is loaded
        break
    }
}

# Action Result

The action's result is represented by the sdk.actionResult property, that contains the following fields:

The absence of the sdk.actionResult means that the user has cancelled the process.

# Result Handler

In addition, there is an optional actionResultHandler, 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.

sdk.actionResultHandler { (sdk, result, onComplete) in

    print("actionResultHandler: actionId=\(result.actionId) answer=\(result.answer ?? "<none>")")

    // you are allowed to process the result asynchronously, just don't forget to call `onComplete` when you finish,
    // you could pass `.cancel` to force the user interface to close, or `.continue` to proceed as usual
    onComplete(.continue)
}

⚠️ onComplete must be executed at the end of processing.