Onfido iOS Authentication SDK

Table of contents

• Overview
• Getting started
• Handling callbacks
• Customizing the SDK
• User consent screen

Overview

The Onfido iOS Authentication SDK provides a set of screens for iOS applications to capture 3D face scans for the purpose of identity authentication.

Getting Started

The SDK supports iOS 11+.

1. Adding 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 'OnfidoAuth'

Run pod install to install the SDK.

Using Swift Package Manager

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

https://github.com/onfido/onfido-auth-sdk-ios.git

2. App permissions

The SDK uses the device's camera. You must have the NSCameraUsageDescription key in your application's Info.plist file.

<key>NSCameraUsageDescription</key>
<string>Required for facial capture</string>

3. Creating the SDK configuration

Once you have added the SDK as a dependency and you have an applicant ID, you can configure the SDK:

let config = try! OnfidoAuthConfig.builder()
    .withSDKToken("<YOUR_SDK_TOKEN_HERE>")
    .withRetryCount(2) // Optional, default is 0
    .build()

let flow = OnfidoAuthFlow(withConfiguration: config)
    .with(responseHandler: { response in
        // Callback when flow ends
    })

Use .withRetryCount() to set the number of repeat attempts a user can do after the first unsuccessful try.

4. Starting the flow

Run the flow from the view controller you want the flow to be presented from e.g. self, where self is a view controller.

flow.run(from: self)

You have now successfully started the flow. Read the next sections to learn how to handle callbacks and customize the SDK.

Handling callbacks

To receive the response from the flow, pass a callback to the instance of OnfidoAuthFlow. Typically, on success, you would create a check on your backend server.

The response object passed to the callback can include the following attributes: .success(AuthenticationResult), .cancel(CancellationReason) and .error(Error).

let responseHandler: (OnfidoAuthResponse) -> Void = { response in
    switch response {
        case .success(let result):
            // User completed flow
            // You can create your check here
        case .cancel(let reason):
            // Flow cancelled by user
            // Reason can be:
            // .deniedConsent -> denied consent on consent screen
            // .openedInLandscape -> face scan in landscape orientation
            // .openedInReversePortrait -> face scan upside down
            // .userExited -> tapped back button on first screen
        case .error(let error):
            // Error occurred
    }
}

Success handling

Success is when the user has reached the end of the flow. AuthenticationResult has the verified, uuid and token properties. If authentication was successful, verified will be true and token will be the JWT. This JWT token can be used to validate the response. There should always be a uuid, whether authentication succeeded or failed.

Error handling

Response handler errors

The Error object returned as part of OnfidoAuthResponse.error(Error) is of type OnfidoAuthFlowError. It is an enum with multiple cases depending on the type of error.

switch response {
    case .error(let error):
        switch error {
            case OnfidoAuthFlowError.cameraPermissionDenied:
                // User denied permission to use camera
            case OnfidoAuthFlowError.sessionCreationUnsuccessful:
                // Failed to create face scan session
                // Could indicate issue with SDK token
            case OnfidoAuthFlowError.api(let error):
                // Received error from API call
            case OnfidoAuthFlowError.exception(let error):
                // Unexpected error
                // Please contact: ios-sdk@onfido.com
            default:
                // Necessary because Swift
        }
}

Configuration errors

The following are required when configuring the SDK:

• SDK token

If these are not included, you may encounter the following errors when calling the build() method on the OnfidoAuthConfigBuilder instance:

• OnfidoAuthConfigError.missingToken -> no SDK token or an empty string is provided

Customizing the SDK

UI customization

In order to enhance the user experience on the transition between your application and the SDK, you can customize some of the colors and fonts used in the SDK flow. Note that every customization is optional, so if you do not specify a particular customization or set it to nil, the default value will be used.

let appearance = OnfidoAuthAppearance(
    primaryTextColor: <DESIRED_UICOLOR_HERE>,
    …
    buttonCornerRadius: <DESIRED_CGFLOAT_HERE>,
    …
    fontRegular: <DESIRED_FONT_NAME_HERE>,
    …)

let config = try! OnfidoAuthConfig.builder()
    ...
    .withAppearance(appearance)
    ...
    .build()

Localization

The SDK comes with out-of-the-box translations for the following locales:

• English (en) 🇬🇧
• Spanish (es) 🇪🇸
• French (fr) 🇫🇷
• German (de) 🇩🇪

Language customization

The strings used within the SDK can be customized by having a Localizable.strings in your app for the desired language and by configuring the flow using the withCustomLocalization() method on the configuration builder.

let config = try! OnfidoAuthConfig.builder()
    ...
    .withCustomLocalization()
    ...
    .build()

You can supply partial translations, meaning if you do not include a translation for a particular key our translation will be used instead. You can also name the strings file with the translated keys as you desire, but the name of the file will have to be provided to the SDK as a parameter to the withCustomLocalization() method i.e. withCustomLocalization(andTableName: "MY_CUSTOM_STRINGS_FILE"). Additionally, you can specify the bundle from which to read the strings file i.e withCustomLocalization(andTableName: "MY_CUSTOM_STRINGS_FILE", in: myBundle).

Note:

• If the strings translations change it will result in a MINOR version change, therefore you are responsible for testing your translated layout in case you are using this feature.
• When adding custom translations, please make sure you add the whole set of keys we have in the example Localizable.strings file.

User consent screen

This step contains a screen to collect US end users' privacy consent for Onfido. It contains the required consent language as well as links to Onfido's policies and terms of use. This is an optional screen.

The user must select "Accept" to progress and continue with the flow. The content is available in English only, and is not translatable.

let config = try! OnfidoAuthConfig.builder()
    ...
    .withUserConsentScreen()
    ...
    .build()

⚠️ This step does not automatically inform Onfido that the user has given their consent.

If you choose to disable this step, you must incorporate the required consent language and links to Onfido's policies and terms of use into your own application's flow before your US user starts interacting with the Onfido SDK.

For more information about this step, and how to collect user consent for Onfido, please visit Onfido Privacy Notices and Consent.