Onfido Studio: iOS SDK integration

Start here

This is an introductory guide to integrating Onfido Studio - our drag and drop interface for building, managing, and deploying identity verification journeys - with Onfido’s iOS SDK. For more general information regarding Onfido Studio, please see our product guide.

Getting started

All of the interactive tasks of an end-user’s verification journey designed and built using Onfido Studio are managed by our SDKs.

The iOS SDK communicates directly and dynamically with active Studio workflows to display the relevant screens to ensure the correct capture and upload of user information, such as identity documents, selfie photos and videos. As a result, the SDK flow will vary depending on the workflow configuration. You won't need to specify any steps directly in the SDK integration as these will be overridden when the workflow run ID is passed into the SDK initialization.

The iOS SDK supports:

iOS 11+
Swift interface only

Create a workflow run

As a first step, you will need to create a Workflow Run by making a call to the Onfido API. At a minimum, you will need to provide a workflow_id from a valid, active workflow, as well as an Applicant ID. More details on creating a workflow run can be found in our API reference.

The server will return a workflow run object, with a workflow run ID contained in the response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<WORKFLOW_RUN_ID>",
  "applicant_id": "<APPLICANT_ID>",
  "workflow_id": "<WORKFLOW_ID>",
  "workflow_version_id": 11,
  "status": "approved",
  "dashboard_url":"https://dashboard.onfido.com/results/<WORKFLOW_RUN_ID>"
  "output": {"prop1": "val_1", "prop2": 10},
  "reasons": ["reason_1", "reason_2"],
  "error": null,
  "created_at": "2022-06-28T15:39:42Z",
  "updated_at": "2022-07-28T15:40:42Z",
  "link": {
      "completed_redirect_url": "https://example.onfido.com",
      "expired_redirect_url": "https://example.onfido.com",
      "expires_at": "2022-10-17T14:40:50Z",
      "language": "en_US",
      "url": "https://eu.onfido.app/l/<WORKFLOW_RUN_ID>"
  },
}

Generate an SDK token

SDK tokens are required to authenticate the SDKs for Studio workflows, generated by making a call to the Onfido API.

$ curl https://api.eu.onfido.com/v3.6/sdk_token \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -F 'applicant_id=<APPLICANT_ID>' \
  -F 'application_id=<YOUR_APPLICATION_BUNDLE_IDENTIFIER>'

SDK tokens expire after 90 minutes. You can use the optional expireHandler parameter in the SDK token configurator function to generate and pass a new SDK token when it expires. This ensures the SDK continues its flow even after an SDK token has expired.

Swift:

func getSDKToken(_ completion: @escaping (String) -> Void) {
    // Your network request logic to retrieve SDK token goes here
    completion(myNewSDKtoken)
}

let workflowConfiguration = WorkflowConfiguration(workflowRunId: "<WORKFLOW_RUN_ID>", sdkToken: "<YOUR_SDK_TOKEN>")
workflowConfiguration.withTokenExpirationHandler(handler: getSDKToken)

Objective-C:

-(void) getSDKTokenWithCompletion: (void(^)(NSString *))handler {
   // <Your network request logic to retrieve SDK token goes here>
   handler(sdkToken);
}

ONWorkflowConfiguration *workflowConfiguration = [[ONWorkflowConfiguration  alloc] initWithWorkflowRunId: @"<WORKFLOW_RUN_ID>"  sdkToken: @"<YOUR_SDK_TOKEN>"];
workflowConfiguration = [workflowConfiguration withTokenExpirationHandler: ^(void (^handler)(NSString *)) { 
    [self getSDKTokenWithCompletion:handler]; 
}];

More detailed documentation about SDK tokens can be found in our API reference.

Add the SDK dependency

Using CocoaPods

The SDK is available on CocoaPods and you can include it in your project by adding the following to your Podfile:

pod 'Onfido'

Run pod install to install the SDK.

Using Swift Package Manager

The SDK is also available with Swift Package Manager and you can include it in your project by adding the following package repository URL:

dependencies: [
    .package(url: "https://github.com/onfido/onfido-ios-sdk.git", .branch("master"))
]

Initialize the SDK for Studio

Now you can initialize the SDK, using your generated SDK token and workflow run ID.

Build a configuration object

let workflowConfiguration = WorkflowConfiguration(workflowRunId: "workflowRunId", sdkToken: "sdkToken")

Start the flow

let onfidoRun = OnfidoFlow(workflowConfiguration: orchestrationConfig)
customerViewController.present(try onfidoRun.run(), animated: true, completion: nil)
// listen for the result

Handling callbacks

To receive the result from a completed workflow, you should pass a callback to the instance of OnfidoFlow. The following code is provided as an example:

onfidoRun.with(responseHandler: { (response: OnfidoResponse) in
    switch response {
        case .success:
        // User completed the flow

        case .cancel(let cancellationReason):
        // Flow cancelled by user
        print(cancellationReason)

        case .error(let error):
        // Error occurred
        print(error)

    }
},
    dismissFlowOnCompletion: true)
    // Dismiss the whole flow when the user completes it, and return back to the integrator view

ATTRIBUTE	NOTES
.success	Callback that fires when all interactive tasks in the workflow have been completed. On success, if you have configured webhooks, a notification will be sent to your backend confirming the workflow run has finished. You do not need to create a check using your backend as this is handled directly by the workflow
.error(Error)	Callback that fires when an error occurs
.cancel	Callback that fires when the workflow was exited prematurely by the user. The reason can be `.userExit` or `.consentDenied`

Error handling

The Error object returned as part of OnfidoResponse.error(Error) is of type OnfidoFlowError. It's an enum with multiple cases depending on the error type.

switch response {
  case let OnfidoResponse.error(error):
    switch error {
      case OnfidoFlowError.cameraPermission:
        // This happens if the user denies permission to the SDK during the flow
      case OnfidoFlowError.failedToWriteToDisk:
        // This happens when the SDK tries to save capture to disk, maybe due to a lack of space
      case OnfidoFlowError.microphonePermission:
        // This happens when the user denies permission for microphone usage by the app during the flow
      case OnfidoFlowError.upload(let OnfidoApiError):
        // This happens when the SDK receives an error from an API call.
        // See https://documentation.onfido.com/#errors for more information
      case OnfidoFlowError.exception(withError: let error, withMessage: let message):
        // This happens when an unexpected error occurs.
        // Please email ios-sdk@onfido.com when this happens
      case OnfidoFlowError.versionInsufficient:
        // This happens when you are using an older version of the iOS SDK and trying
        // to access a new functionality from workflow. You can fix this by updating the SDK

      default: // necessary because of Swift
    }
}

Customizing the SDK

The iOS SDK has multiple customizable features that provide flexibility, while also being easy to integrate. For more detailed documentation, read our SDK customization guide.

UI Customization

The iOS SDK supports the customization of colors, fonts and strings used in the SDK flow. For more information, please see our SDK customization guide.

Language localization

The SDK supports and maintains multiple languages. Please refer to the iOS SDK language localization documentation for more details.