# iOS SDK

# Version 1.0.0

For version history and release notes please see Changelog

# Prerequisites

iOS 9.0 or later
Xcode 11+

# Installation

This framework ment 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 in your project directory

pod install

# Permissions

The framework will ask to have access to the camera and possibly to the microphone, so it's required to have the corresponding usage descriptions in the application's Info.plist file:

<key>NSCameraUsageDescription</key>
<string>Let us make a photo</string>
<key>NSMicrophoneUsageDescription</key>
<string>Time to record video</string>

# Basic Usage

Before you initialize our SDK you need to do two things on your backend:

Create an applicant and note its applicantId
Make a method for generating an accessToken for the given applicantId

Don't store your API credentials or auth token in your app code.

Please see API Reference for detail explanation of Applicant creation and working with Access tokens.

# 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 accessToken = "..." // use the `accessToken` for the applicant to be verified got from your backend
let locale = Locale.current.identifier // locale in a form of "en_US"
let supportEmail = "[email protected]" // optional support email

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

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

Next you instantiate SNSMobileSDK and check if setup went right:

let sdk = SNSMobileSDK(
    baseUrl: baseUrl,
    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 setup was successful with sdk.isReady, if it happens to fail, you could see exactly reason by printing sdk.verboseStatus.

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

# Presentation

Anyway once setup is done you are ready to present SDK on the screen:

guard let mainVC = sdk.mainVC else {
    print("mainVC is failed to be created")
    return;
}

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

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

# Handlers

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

# Token Expiration

Because of the limited lifespan of the accessToken, it's required to handle the situation where the token is expired and needs to be refreshed. As a solution you set tokenExpirationHandler. The handler should make a call to your backend, obtain the newToken and pass it back to the sdk by calling onComplete closure.

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

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

# Verification Completion

You could use verificationHandler to be informed when verification process is done 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 of 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 could take the dimission control over by assigning dismissHandler. The handler takes the current sdk instanse and the mainVC controller. It's up to you to dismiss the mainVC in the manner you prefer to.

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

# Callbacks

Callbacks are completely optional. Use them if you feel them helpful.

# Status Updates Notification

Use onStatusDidChange callback to get notified of 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. Then you examine sdk.status enum 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 would never be passed here since the callback is 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 verification steps are passed over")
        
    case .pending:
        print("Verification is in pending state")
        
    case .temporarilyDeclined:
        print("Applicant has been declined temporarily")
        
    case .finallyRejected:
        print("Applicant has been finally rejected")
        
    case .approved:
        print("Applicant has been approved")
    }
}

# Dismiss Notification

An optional way to be notified when mainVC is dismissed:

sdk.onDidDismiss { (sdk) in
    print("sdk has been dismissed")
}

# Logging

No need to mention how important to have logs in case if smth went wrong.

# Log Level

By default SDK tries not to spam your console and will print only when something critical is happened, but sometimes it makes sense to see 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 = .info

# Log Interception

By default SDK uses NSLog for the logging purposes. If for some reasons 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(), message)
}

# Customization

# Support Items

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

Feel free to reconfigure support items as required. 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 back 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 such things like 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 the customizable options start from sns_ prefix, so you could start to type to see them all.

# Localization

You can customize or localize the texts used within the SDK with standard system means.

Just add the IdensicMobileSDK.strings file that comes along with SDK into your project, then localize it by adding the languages you desired.

# Resources

sample.swift - Swift sample code. Feel free to use it as a boilerplate.
IdensicMobileSDK.strings - texts in English