/instnt-ios-sdk

Instnt's SDK for iOS Mobile Apps

Primary LanguageSwiftMIT LicenseMIT

Instnt iOS SDK

This documentation covers the basics of the Instnt iOS SDK. iOS SDK provides functions and libraries for seamless integration with your front-end application. For a detailed overview of Instnt's functionality, visit the Instnt documentation hub

Table of Contents

Prerequisites

  • Sign in to your account on the Instnt Accept's dashboard and create a customer signup workflow that works for your company. Get the workflow ID. This ID is essential while integrating with Instnt SDK. Refer Quick start guide and Developer guide, for more information.

  • The integration of SDK depends on your workflow; read the Instnt Accept integration process to understand the functionalities provided by Instnt and how to integrate SDK with your application.

Note: Your implementation with Instnt's SDK may diverge from the integration shown in the sample app. Please get in touch with the Instnt support team for additional questions related to Integration.

Requirements

iOS Swift Xcode
12+ 5.0 11+

Minimum Supported Devices

  • iPhone 6 and 6plus

  • iPad mini 4

  • iPad Air 2

  • iPad Pro (1st generation)

  • iPad 5th generation

Getting started

Instnt iOS SDK is comprised of iOS components and mechanisms to facilitate communication between your application, Instnt SDK, and Instnt's APIs.

Note that a Workflow ID is required to execute this function properly. For more information concerning Workflow IDs, please visit Instnt's documentation library.

  1. Create a workflow in the Instnt dashboard and get the Workflow ID.

  2. Install InstntSDK through CocoaPods by adding the following line to your Podfile:

  pod 'InstntSDK'

Initialize transaction

  • Set your view controller as a delegate in your load function to instantiate the Instnt delegate.
  Instnt.shared.delegate = self
  • import the InstntSDK
import InstntSDK

  • The first step is to begin a transaction and obtain a transaction id, which acts as a correlation key for a user signup session to interact with Instnt.

  • See the following sample code to call the setup fuction:

formKey : workflowID

endpoint: production URL or sandbox URL

completion block : implement and pass a completeion block that checks if the initialization of a transaction is a success or not.

Instnt.shared.setup(with: formKey, endPOint: self.endPoint?.textField.text ?? "", completion: { result in
    SVProgressHUD.dismiss()
    switch result {
    case .success(let transactionID):
        ExampleShared.shared.transactionID = transactionID
        self.addResponse()
        self.getFormAfterSuccess()
        self.lblView?.lblText.text = "Set up is succeded with transaction Id \(transactionID)"
    case .failure(let error):
        self.addResponse()
        self.lblView?.lblText.text = "Set up is failed with \(error.message ?? ""), please try again later"
    }
})

Document verification

Document verification feature comes into the picture if you have enabled it during the workflow creation in our dashboard.

When this feature is enabled, the physical capture and verification of selfies and Government-issued identification documents such as Passports and Driver's Licenses are available.

Add "Privacy - Camera Usage Description" in info.plist file for camera access permission.

Note: Document Verification feature usage in your implementation via SDK requires a License key. Please contact the support at the email support@instnt.org for further assistance.

Document verification pre-requisites

  • iOS devices reasonably updated OS and a good camera are supported for document verification.

Document verifications steps

  1. The first step in document verification is to scan a document. Following is the sample code for scanning a document.

The document verification has an auto-upload feature which is turned on by default. It uploads the image to Instnt cloud storage once the image gets captured successfully.

Instnt.shared.scanDocument(instnttxnid: transactionID, licenseKey: self.licenseKey, from: self, settings: documentSettings)

licenseKey: License key

UIViewController: The document scan UIViewController

documentSettings: The document settings object, which has information such as document type, document side, and capture mode.

  1. Next, upload the attachment. The upload attachment should be called for each side of the document, for example, the front and backside of a driver's license. You only need to take this step if you have autoUpload turned off (when you invoke scanDocument or scanSelfie methods)

The following sample code demonstrates the upload attachment process:

Instnt.shared.uploadAttachment(instnttxnid: transactionID, data: captureResult.selfieData, completion: { result in
    switch result {
    case .success(_):
        if captureResult.farSelfieData != nil {
            Instnt.shared.uploadAttachment(instnttxnid: transactionID, data: captureResult.selfieData, isFarSelfieData: true, completion:  { result in
                switch result {
                case .success():
                    self.verifyDocument()
                case .failure(let error):
                    SVProgressHUD.dismiss()
                    print("uploadAttachment error \(error.localizedDescription)")
                    self.instntDocumentScanError()
                }
            })
        } else {
            self.verifyDocument()
        }
        
    case .failure(let error):
        SVProgressHUD.dismiss()
        print("uploadAttachment error \(error.localizedDescription)")
        self.instntDocumentScanError()
    }
})
  1. Next, verify the documents that were uploaded. Once all the documents are uploaded, call verifyDocuments function to verify the documents.
  Instnt.shared.verifyDocuments(instnttxnid: transactionID, completion: { result in
        DispatchQueue.main.async {
            SVProgressHUD.dismiss()
            switch result {
            case .success():
                self.instntDocumentVerified()
            case .failure(let error):
                self.showSimpleAlert("Document verification failed with error: \(error.message ?? "Technical Difficulties")", target: self)
            }
        }
    })
  1. In the Instnt iOS SDK, we provide another functionality for selfie scan/capture. It is similar to the document scan and upload process. Pass the UIViewController type as the argument. It also takes a far Selfie as a second check but this can be disabled by setting farSelfie false as argument.
Instnt.shared.scanSelfie(from: self, instnttxnid: transactionID, farSelfie: self.isFarSelfie ?? false, isAutoUpload: self.isAutoUpload ?? true)

OTP (One-Time Passcode)

OTP functionality can be enabled by logging in Instnt dashboard and enabling OTP in your workflow. Refer to the OTP section of the Quickstart guide for more information.

OTP flow

  • User enters mobile number as part of the signup screen.
  • Your app calls send OTP() SDK function and pass the mobile number.
  • Instnt SDK calls Instnt API and returns the response upon successful OTP delivery.
  • Your app shows the user a screen to enter the OTP code.
  • User enters the OTP code which they received.
  • Your app calls verify the OTP() SDK function to verify the OTP and pass mobile number and OTP code.
  • Instnt SDK calls Instnt API and returns the response upon successful OTP verification.

Instnt SDK provides two library functions to enable OTP. we have also provided the sample code for the implementation.

  1. sendOTP (mobileNumber)
Instnt.shared.sendOTP(instnttxnid: transactionID, phoneNumber: phone, completion: { result in
        SVProgressHUD.dismiss()
        switch result {
        case .success:
            ExampleShared.shared.formData["mobileNumber"] = self.phone?.textField.text
            ExampleShared.shared.formData["email"] = self.email?.textField.text
            guard let vc = Utils.getStoryboardInitialViewController("VerifyOTP") as? VerifyOTPVC else {
                return
            }
            vc.presenter?.phoneNumber = phone
            self.vc?.navigationController?.pushViewController(vc, animated: true)
        case .failure( let error):
            if let vc = self.vc {
                self.vc?.showSimpleAlert(error.message ?? "Error getting the OTP", target: vc)
            }
        }
    })
  1. verifyOTP(mobileNumber, otpCode)
Instnt.shared.verifyOTP(instnttxnid: transactionID, phoneNumber: phone, otp: otp, completion: { result in
        SVProgressHUD.dismiss()
        switch result {
        case .success:
            ExampleShared.shared.formData["otpCode"] = self.otp?.textField.text
            guard let vc = Utils.getStoryboardInitialViewController("Address") as? AddressVC else {
                return
            }
            self.vc?.navigationController?.pushViewController(vc, animated: true)
        case .failure(let error):
            if let vc = self.vc {
                self.vc?.showSimpleAlert(error.message ?? "Invalid OTP", target: vc)
            }
        }
    })

Submit form data

After gathering all the relevant end-user information and processing the documents, you can submit all the data to Instnt via submitData function.

See the sample code of the implementation:

Instnt.shared.submitData(instnttxnid: transactionID, data: ExampleShared.shared.formData, completion: { result in
    SVProgressHUD.dismiss()
    switch result {
    case .success(let response):
        if response.success == true,
            let decision = response.decision,
            let jwt = response.jwt {
            self.instntDidSubmitSuccess(decision: decision, jwt: jwt)
        } else {
            if let msg = response.message {
                self.instntDidSubmitFailure(error: InstntError(errorConstant: .error_FORM_SUBMIT, message: msg))
            } else {
                self.instntDidSubmitFailure(error: InstntError(errorConstant: .error_FORM_SUBMIT))
            }
            
        }
    case .failure(let error):
        self.instntDidSubmitFailure(error: error)
    }
    
})

The completion block that is passed as an argument when submitdata fuction is called can be implemented as you want. The following parameter are returned:

  • decision: Form submission result. One of the following three values is returned: ACCPET, REJECT and REVIEW
  • jwt: Instnt JWT token

Instnt delegate

Instnt SDK provides InstntDelegate which has the delegate fuctions as shown below. Implement the InstntDelegate Protocol:

public protocol InstntDelegate: NSObjectProtocol {

    func onDocumentScanFinish(captureResult: CaptureResult)
    func onDocumentScanCancelled(error: InstntError)
    
    func onSelfieScanCancelled()
    func onSelfieScanFinish(captureResult: CaptureSelfieResult)
    func onSelfieScanError(error: InstntError)
    
    func onDocumentUploaded(imageResult: InstntImageData, error: InstntError?)
}

  • onDocumentScanFinish: This function is called when a document scan is successfully completed.

  • onDocumentScanCancelled: This function is called when document scan is unsuccessful.

  • onSelfieScanCancelled: This function is called when the selfie scan is canceled.

  • onSelfieScanFinish: This function is called when the selfie scan is successfully completed.

  • onSelfieScanError: This function is called when a selfie scan has an error.

Instnt object

Property

Type

Description

instnttxnid

UUID

Instnt Transaction ID

formId

string

Instnt Form/Workflow ID. This ID is available in the Instnt dashboard, where you created a signup workflow.

isOTPSupported

boolean

Checks whether Instnt Form/Workflow has OTP verification enabled

isDocumentVerificationSupported

boolean

Checks whether Instnt Form/Workflow has document verification enabled

Instnt functions

Method

Input Parameters

Description

setup

(with formId: String, endPOint: String, completion: @escaping(Result) -> Void)

Initializes a user signup session.

scanDocument

(instnttxnid: transactionID, licenseKey: String, from vc: UIViewController, settings: DocumentSettings)

Enables a document scan.

scanSelfie

(from vc: UIViewController, instnttxnid: transactionID, farSelfie: bool)

Enables a selfie scan/capture.

uploadAttachment

(instnttxnid: transactionID, data: Data, completion: @escaping(Result) -> Void)

Upload a document file to Instnt server.

verifyDocuments

(instnttxnid: transactionID, completion: @escaping(Result) -> Void)

Initiate document verification on Instnt server.

submitData

(instnttxnid: transactionID, data: [String: Any], completion: @escaping(Result) -> Void)

Submit the user entered data and the documents uploaded to the Instnt server and initiate customer approval process.

sendOTP

(instnttxnid: transactionID, phoneNumber: String, completion: @escaping(Result) -> Void)

Sends one-time password to the mobile number provided.

verifyOTP

(instnttxnid: transactionID, phoneNumber: String, otp: String, completion: @escaping(Result) -> Void)

Verifies one-time password that was sent to the provided mobile number.

Resource links

License

The instnt-iOS SDK is under MIT license.