iOS

📘

Sample Project

You can find the sample project for an XCode project that showcases the integration with IDWise iOS Framework.

Requirements

The minimum deployment target for IDWiseSDK is iOS 12.0. In order to use the SDK your application minimum deployment target should be iOS 12.0 or higher.
On your development machine you need to have XCode and CocoaPods installed. Both Intel and M1 (Apple Sillicon) based machines are supported. When working with Cocoapods you might have to run some commands through Rosetta Stone compatibility mode.

Latest Stable Version

The current latest release of IDWise SDK.

Installation

IDWiseSDK is available to install via CocoaPods package manager from IDWise private Cocoapods repository.
To add IDWise SDK to your project, first ensure you have these two lines at the top of your Podfile file:

source 'https://cdn.cocoapods.org/'
source 'https://github.com/idwise/ios-sdk'

This adds IDWise private Cocoapods repository as a source to install packages from

Next add this line also to your Podfile but this time underneath your target node for your project:

pod 'IDWise'

Also, add this configuration underneath your target node for your project:

  post_install do |installer|
    installer.pods_project.build_configurations.each do |config|
      config.build_settings['CODE_SIGNING_ALLOWED'] = 'NO'
    end
  end

You can have a look at the example Podfile provided in the root of this repository to see an example Podfile with both the changes above completed

After adding our dependency in your Podfile run:

pod install

Usage

Invoking IDWise SDK is very simple. First import IDWise package in your code file:

import IDWiseSDK

Starting a user journey

IDWise SDK is designed to start on top of a UIViewController in your application. Each user onboarding or verification transaction is named a user journey.

To start a new journey just provide the UIViewController from which you want the flow to start then call IDWiseSDK.initialize method first with your provided client key and then you can call IDWise.startJourney method. If initialization is failed for any reason, you will get an error object with a code and a message explaining the reason of the error. In the following example, we called initialize method and then called startJourney method.

The IDWiseSDK.initialize method accepts clientKey and theme as It's parameters.The theme parameter is for specifying the theme (dark or light). If you want the SDK to be in the same theme mode as set in system display settings, you need to pass IDWiseSDKTheme.systemDefault. However, if the OS is in dark mode and you want the SDK to be in light mode (or vice versa), you can pass the appropriate value for the theme parameter.

Possible values for the theme parameter include IDWiseSDKTheme.light,IDWiseSDKTheme.dard and IDWiseSDKTheme.systemDefault.

        
IDWiseSDKTheme.light // to specify light theme mode for SDK
IDWiseSDKTheme.dark // to specify dark theme mode for SDK
IDWiseSDKTheme.systemDefault // to specify the same theme as of operating system

        IDWise.initialize(clientKey: "<YOUR_CLIENT_KEY>",theme: .systemDefault) { err in
                // Deal with error here
            if let error = err {
              // handle error, show some alert or any other logic
            }
        }
        
        IDWise.startJourney(journeyDefinitionId: "<YOUR_CUSTOMER_ID>", referenceNumber: "<YOUR_REFERENCE_NO>", locale: "en", journeyDelegate: self)
        

This will make IDWise SDK show a UI with a wizard to guide the user through completing the onboarding journey

IDWise.startJourney method takes two parameters:

• journeyDefinitionId: Specifies the journey definition (aka template) to base this new journey on. Journey definitions are created based on your requirements and specify what documents and biometrics to collect from the user and in what order. JourneyDefinitionId is shared with you by IDWise team as part of your use-case and requirements discussions.
• referenceNo : A custom identifier to associate with this journey to enable you to link it back easily or associate it with a user on your system.
• locale : Language code of the language to be used to display the journey user interface. This is either an ISO 639-1 (2-letter for example en) or IETF BCP 47 (2-letter plus extended language specified for example zh-HK or zh-CN)
• journeyDelegate: This parameter is used to provide a set of event handlers to handle the different events that are triggered from IDWise SDK. These events indicate the lifetime of a journey and provide oppurtunity for your application to react to certain events.

For example we can implement the protocol 'IDWiseSDKJourneyDelegate' as an extension on the ViewController like so:

extension ViewController:IDWiseSDKJourneyDelegate {
    func onError(error: IDWiseSDKError) {
       
    }
    
    func JourneyCancelled() {
        
    }
    
    func JourneyStarted(journeyID: String) {
        
    }

    func onJourneyResumed(journeyID: String) {

    }
    
    func JourneyFinished() {
        
    }
}

• JourneyStarted: Triggered when the journey is started and the Journey ID is assigned.
• JourneyFinished: Triggered when the journey is completed by the user.
• JourneyCancelled: Triggered when the user cancels the journey and doesn't finish it.
• onJourneyResumed: Triggered when an existing journey is resumed.
• onError: Triggered when an error occurs for example a network connectivity error and lack of permission to access the camera.

When the journey is started it is assigned a unique id called Journey ID in IDWise system and this is provided as a parameter, journeyID with the triggering of JourneyStarted event.
This identifier can be used to fetch the data and status of the journey from IDWise Journey Fetch API once you get the webhook call to your backend.

The steps that compose part of the journey and the prompts that user see are all cutomisable through IDWise cloud system.

Resuming a Journey

If you want to resume an unfinished journey, you can do so as below:

IDWise.resumeJourney(
  journeyDefinitionId: "<YOUR_CUSTOMER_ID>",
  journeyId: "<JOURNEY_ID>",
  locale: "en",
  journeyDelegate: self
  )

This method takes the following parameters:

• journeyDefinitionId: Specifies the journey definition (aka template) to base this new journey on. Journey definitions are created based on your requirements and specify what documents and biometrics to collect from the user and in what order. JourneyDefinitionId is shared with you by IDWise team as part of your use-case and requirements discussions.
• journeyId: This is a unique identifier that identifies your journey and it can be used to resume. This is received in the implementation of IDWiseSDKJourneyDelegate interface in onJourneyStarted method when you started the journey the first time.
• locale : Language code of the language to be used to display the journey user interface. This is either an ISO 639-1 (2-letter for example en) or IETF BCP 47 (2-letter plus extended language specified for example zh-HK or zh-CN)
• journeyDelegate: This parameter is used to provide a set of event handlers to handle the different events that are triggered from IDWise SDK. These events indicate the lifetime of a journey and provide oppurtunity for your application to react to certain events.

Managing Device Orientation

IDWise SDK only supports portrait orientation for Its screens. If you are supporting multiple orientations other than portrait then you either need to lock your full app to portrait or you can use our helper class that locks the orientation for our SDK screens only.

1. You need to add following struct in your code.

struct AppUtility {

    static func lockOrientation(_ orientation: UIInterfaceOrientationMask) {
    
        if let delegate = UIApplication.shared.delegate as? AppDelegate {
            delegate.orientationLock = orientation
        }
    }

    /// OPTIONAL Added method to adjust lock and rotate to the desired orientation
    static func lockOrientation(_ orientation: UIInterfaceOrientationMask, andRotateTo rotateOrientation:UIInterfaceOrientation) {
   
        self.lockOrientation(orientation)
    
        UIDevice.current.setValue(rotateOrientation.rawValue, forKey: "orientation")
        UINavigationController.attemptRotationToDeviceOrientation()
    }

}

2. You need to add following code in your AppDelegate.swift class.

 /// set orientations you want to be allowed in this property by default
    var orientationLock = UIInterfaceOrientationMask.all

    func application(_ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask {
            return self.orientationLock
    }

3. Now before starting Initialising and starting IDWise journey, you can lock the orientation using follow code.

 AppUtility.lockOrientation(.portrait)

4. After IDWise journey is finished or cancelled, you can unlock the orientation again so It can again support multiple orientations for your application screens.

extension ViewController:IDWiseSDKJourneyDelegate {
    func onError(error: IDWiseSDKError) {
       
    }
    
    func JourneyStarted(journeyID: String) {
        
    }

    func onJourneyResumed(journeyID: String) {

    }
  
    func JourneyCancelled() {
       AppUtility.lockOrientation(.all)
    }
  
    func JourneyFinished() {
       AppUtility.lockOrientation(.all)
    }
}