iOS Integration

Integrate Attestr Studio iOS SDK within your mobile applications to automate eKYC workflows.

Available Versions

Attestr iOS SDK is distributed as XCFramework. Made for Iphone and IPad

Integration Steps

Step 1. Add Attestr Flowx iOS SDK library in your iOS application.

Cocoapods

Attestr iOS SDK is distributed through Cocoapods. Add the following line to the application Podfile.

pod 'attestr-flowx', '~> 0.5.0'

Manual

• Download the SDK from the changelog link above and unzip it.
• Open your project in XCode and go to File under Menu. Select Add files.
• Select attestr-flowx.xcframework from the directory created in step 1 after unzipping.
• Select the Copy items if needed check-box.
• Click Add.
• Navigate to Target settings > General and add the attestr-flowx.xcframework in both Embedded Binaries and Linked Frameworks and Libraries.

Step 2. Add required permissions to Info.plist

The following properties must be specified in the Info.plist file for the face match and digital address verification stages. For flows that do not use these verification stages, this step can be skipped.

NSCameraUsageDescription

NSLocationAlwaysAndWhenInUseUsageDescription

NSLocationAlwaysUsageDescription

NSLocationWhenInUseUsageDescription

NSPhotoLibraryUsageDescription

Step 3. Create a handshake on the server side

The first step involves initiating a handshake. Invoke Create Handshake API from your server side code which returns a handshake Id (also known as device session Id).

Step 4. Store the handshake Id in database

The handshake Id generated in step one must be stored in the database for later retrieval. This is needed for two reasons - 1) To retrieve the final result for the handshake 2) To validate the result signature. More details on signature below.

Step 5. Import Attestr Flowx in view controller

import attestr_flowx

Step 6. Conform to AttestrFlowxEventProtocol

Make your view controller conform to AttestrFlowxEventProtocol and add your implementation success, error and skip handlers.

extension ViewController: AttestrFlowxEventProtocol {

    func onFlowxSuccess(_ data: [String : AnyObject]) {

        // your implementation here

    }

​

    func onFlowxSkip(_ data: [String : AnyObject]) {

        // your implementation here

    }

​

    func onFlowxError(_ data: [String : AnyObject]) {

        // your implementation here

    }

}

onFlowxSuccess

On successful completion of the flow execution, result signature is returned in the dictionary object.

{"signature": "2021cc7afd51885eab998765c3dc502177b74ae9f98ff622f05d65dc7d075efe"}

onFlowxError

This handler is triggered, if an irrecoverable error is encountered during the flow execution which leads to termination of user's device session. The signature of error object is as follows.

{"code": 5001, "httpStatusCode": 500, "message": "अनुरोध पूरा नहीं किया जा सका। बाद में कोशिश करें।","retry": false, "stage":"FS02zfeuv3tcnkq2mond2", "original": {"code":4035, httpStatusCode:403, "message":"Requested service is not provisioned for your account"}}

• code An error code which determines the type of error. Every flow stage has its own set of possible error codes. Please check the respective stage type documentation for the list of error codes.
• httpStatusCode The http status codes are used as standard to classify the error into malformed inputs, authorization related issues, configuration issues and other unknown errors.
• message This is the localized error message describing the cause of error in user's language as passed in the launch method below. It can be used to display the errors to user if desired.
• retry Whether the given error is recoverable or irrecoverable. It is always set as False while invoking onFlowxError function as onFlowxError is only called if the error is irrecoverable. Any recoverable errors are handled by the Attestr framework.
• stage This is the Id of the stage at which the execution is halted. If the flow errors while identifying the next stage to run, this returns the last stage which completed successfully. If the flow fails while identifying the first stage in the flow, this key will be set as null.
• original This key is available only in the cases when the error's root cause is something else. It could be either due to low credits balance, rate limit exceeded, service not provisioned etc. Check the error codes in the respective API documentation for the possible values that can show up in original object.

Check the respective stage documentation for possible error code values.

onFlowxSkip

This handler is triggered if the flow session is interrupted by the user. The data object contains only one key called stage which is the Id of the stage at which execution is skipped. If the execution is skipped while the server is busy fetching the next stage, this returns the last stage which completed successfully. If the flow is skipped while identifying the first stage in the flow, this key will be set as null.

{"stage": "FS02zfeuv3tcnkq2mond2"}

Step 7. Initialize the AttestrFlowx object

In your view controller, create an instance of AttestrFlowx by calling the initialize method.

/// Initailises an instance of AttestrFlowx

    /// -  Parameters:

    ///   - cl: client key (MANDATORY)

    ///   - hs: handshake key (MANDATORY)

    ///   - vc: view controller on which flow is to be presented. This view must conform to AttestrFlowxEventProtocol (MANDATORY)

    /// - Returns: An optional instance of AttestrFlowx

//public func initialize(cl: String, hs: String, _ vc: UIViewController) -> AttestrFlowx?

​

let p = AttestrFlowx().initialize(cl: "client_key", hs: "handshakeId", self)

Step 8. Launch the flow

You must call launch function of AttestrFlowX object to run the flow. The syntax is as below. This establishes the connection with Attestr servers and runs the flow on user's device.

/// Launches the flow with the following specifications

    /// - Parameters:

    ///   - lc: language code , for eg: use 'en' for English (MANDATORY)

    ///   - retry: pass retry as True if re-running the flow for a previously used handshake (MANDATORY)

    ///   - qr: query parameters (OPTIONAL)

//public func launch(lc: String, retry: Bool, qr: [String: String]?)

​

p?.launch(lc: "en", retry: retry, qr: nil)

Sample View Controller

import UIKit

import attestr_flowx

​

class ViewController: UIViewController {

  ....

  override func viewDidLoad() {

    super.viewDidLoad()

    ...

    let p = AttestrFlowx().initialize(cl: "client_key", hs: "handshakeId", self)

    p?.launch(lc: "en", retry: false, qr: nil)

    ...

  }

}

​

extension ViewController: AttestrFlowxEventProtocol {

    func onFlowxSuccess(_ data: [String : AnyObject]) {

        let alert = UIAlertController(title: "Success!", message: "The verification process was completed successfully.", preferredStyle: .alert)

        alert.addAction(UIAlertAction(title: "OK", style: .default))

        self.present(alert, animated: true)

    }

    func onFlowxSkip(_ data: [String : AnyObject]) {

        let alert = UIAlertController(title: "Skipped", message: "The verification process was skipped. Some parts of it might be repeated.", preferredStyle: .alert)

        alert.addAction(UIAlertAction(title: "OK", style: .default))

        self.present(alert, animated: true)

    }

    func onFlowxError(_ data: [String : AnyObject]) {

        let code = data["code"] as! Int

        let alert = UIAlertController(title: "Error \(code)", message: data["message"] as? String, preferredStyle: .alert)

        alert.addAction(UIAlertAction(title: "OK", style: .default))

        self.present(alert, animated: true)

    }

}

https://github.com/attestr/ios-sample-app/blob/master/FlowxApp/ViewController.swift

Step 9. Fetch the result on the server side.

On successful completion of the flow, call Execution Result API on the server side to query the result of the session. Pass the handshake Id generated in step 1 while calling the API.

Step 10. Validate signature on server side

This is the final step in integration. The outcome of Execution Result API contains a result signature key. You must perform the following 2 checks.

• Check if the signature returned in the API matches the signature retrieved in the onSuccess handler.
• Generate signature on your server side code base and check if it matches the signature returned in the API. To generate the signature, use the SHA256 algorithm, the client secret and the result object as returned in step 6 to generate a HMAC Hex Digest as shown in the sample code below.

const crypto = require("crypto");

​

var clientSecret; // This should be initialized as client secret.

var apiResponse; // This is apiResponse as retuned in step 6.

​

function hmacHexDigest(secret, input) {

    const hmac = crypto.createHmac('sha256', secret)

    hmac.update(input)

    return hmac.digest('hex')

}

​

var signature = hmacHexDigest(clientSecret, JSON.stringify(apiResponse.result));

​

// Check if signature matches

if(signature !== apiResponse.resultSignature){

  // Flow is tampered.

}

Retry On Error

Attestr offers retry mechanism to reattempt flows that run into errors or return invalid data output for one or more stages. To rerun the flow, set the retry parameter to true while initializing AttestrFlowx object and launch the flow. Check step 5 above.

Retry skips all stages that ran successfully during the previous run. If all stages were successful during the previous run, the flow simply returns invoking the success handler.

Attestr Sample iOS Application

Clone this project and add to XCode. Run pod install and launch app.

https://github.com/attestr/ios-sample-app