onfido ios sdk
32.1.0
The Onfido Smart Capture SDKs provide a set of screens and functionalities that enable applications to implement user identity verification flows. Each SDK contains:
All Onfido Smart Capture SDKs are orchestrated using Onfido Studio workflows, with only minor customization differences between the available platforms.
Two environments exist to support the Onfido SDK integrations:
The environment being used is determined by the API token that is used to generate the necessary SDK token.
Once you are satisfied with your integration and are ready to go live, please contact Onfido's Customer Support to obtain a live API token. You will have to replace the sandbox token in your code with the live token.
Check that you have entered correct billing details inside your Onfido Dashboard, before going live.
The iOS SDK supports:
Note: The latest SDK version to support Xcode 11.5-12 is iOS SDK version 22, Xcode 14+ is iOS SDK version 29. There is a workaround for older versions of Xcode if required. Please contact Onfido's Customer Support team for more information.
Note: The iOS SDK requires CoreNFC to run (regardless of whether you use NFC or not). Since Xcode 12, there is a bug where libnfshared.dylib is missing from simulators. Refer to Stack Overflow for a solution to this problem.
Note: In the event that you disable the NFC feature, Apple might ask you to provide a video to demonstrate NFC usage because NFC-related code is part of the SDK binary, regardless of runtime configuration. While we're working on a permanent solution for this problem, you can contact Onfido's Customer Support in the meantime to obtain a video.
The SDK makes use of a user's device camera (for document and face capture) and microphone (for video and motion capture). You're required to have the following keys in your application's Info.plist file:
NSCameraUsageDescriptionNSMicrophoneUsageDescription<key>NSCameraUsageDescription</key>
<string>Required for document and face capture</string>
<key>NSMicrophoneUsageDescription</key>
<string>Required for video capture</string>Note: All keys will be required for app submission.
The SDK is 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"))
]The SDK is also available on CocoaPods, and you can include it in your project by adding the following to your Podfile:
pod 'Onfido'Run pod install to get the SDK.
The SDK is available in the GitHub Releases tab, where you can download the compressed framework. You can find the latest release here.
Onfido.xcframework
Onfido.xcframework artefact into your project folderOnfido.xcframework located within your project to the Embedded binaries section in the General tab of your
iOS app targetIf your app is not Swift based, then you must create a new Swift file inside of your project. This file is required to force Xcode to package Swift runtime libraries required for the Onfido iOS SDK to run.
Create a Swift file with the following contents:
import Foundation
import AVFoundation
import CoreImage
import UIKit
import Vision
func fixLibSwiftOnoneSupport() {
// from https://stackoverflow.com/a/54511127/2982993
print("Fixes dyld: Library not loaded: @rpath/libswiftSwiftOnoneSupport.dylib")
}Set Always Embed Swift Standard Libraries to Yes in your project configuration.
️ The following SDK initialization documentation applies to identity verification workflows orchestrated using Onfido Studio. For integrations where the verification steps are manually defined and configured, please refer to the Advanced flow customization section below.
The iOS SDK has multiple initialization and customization options that provide flexibility to your integration, while remaining easy to integrate.
Onfido Studio is the platform used to create highly reusable identity verification workflows for use with the Onfido SDKs. For an introduction to working with workflows, please refer to our Getting Started guide, or the Onfido Studio product guide.
SDK sessions are orchestrated by a session-specific workflow_run_id, itself derived from a workflow_id, the unique identifier of a given workflow.
For details on how to generate a workflow_run_id, please refer to the POST /workflow_runs/ endpoint definition in the Onfido API reference.
Note that in the context of the SDK, the
workflow_run_idproperty is referred to asworkflowRunId.
When defining workflows and creating identity verifications, we highly recommend saving the applicant_id against a specific user for potential reuse. This helps to keep track of users should you wish to run multiple identity verifications on the same individual, or in scenarios where a user returns to and resumes a verification flow.
The SDK is authenticated using SDK tokens. Onfido Studio generates and exposes SDK tokens in the workflow run payload returned by the API when a workflow run is created.
SDK tokens for Studio can only be used together with the specific workflow run they are generated for, and remain valid for a period of five weeks.
Note: You must never use API tokens in the frontend of your application as malicious users could discover them in your source code. You should only use them on your server.
To use the SDK, you need to obtain an instance of the client object, using your generated SDK token and workflow run ID.
let workflowConfiguration = WorkflowConfiguration(workflowRunId: "<WORKFLOW_RUN_ID>", sdkToken: "<YOUR_SDK_TOKEN>")let onfidoRun = OnfidoFlow(workflowConfiguration: orchestrationConfig)
customerViewController.present(try onfidoRun.run(), animated: true, completion: nil)
// listen for the resultRecent passports, national identity cards and residence permits contain a chip that can be accessed using Near Field Communication (NFC). The Onfido SDKs provide a set of screens and functionalities to extract this information, verify its authenticity and provide the resulting verification as part of a Document report.
From version 29.1.0 onwards of the Onfido iOS SDK, NFC is enabled by default and offered to end users when both the document and the device support NFC.
For more information on how to configure NFC and the list of supported documents, please refer to the NFC for Document Report guide.
This feature requires Near Field Communication Tag Reading capability in your app target. If you haven't added it
before, please follow the steps in Apple's documentation.
To support NFC PACE documents, you need to edit app entitlements:
Near Field Communication Tag Reader Session Formats keyPassword Authenticated Connection Establishment (PACE) from the dropdown list<key>com.apple.developer.nfc.readersession.formats</key>
<array>
<string>PACE</string>
<string>TAG</string>
</array>You're required to have the following key in your application's Info.plist file:
<key>NFCReaderUsageDescription</key>
<string>Required to read ePassports</string>Info.plist file to be able to read NFC tags properly.<key>com.apple.developer.nfc.readersession.felica.systemcodes</key>
<array>
<string>12FC</string>
</array>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
<string>A0000002471001</string>
<string>A0000002472001</string>
<string>00000000000000</string>
<string>D2760000850101</string>
</array>
To configure NFC using Onfido Studio, you can use one of the following options in the workflow builder:
optional): NFC reading will be attempted, if possibleTo configure NFC in code, call the withNFC() function while configuring OnfidoConfig (see the Advanced flow customization section below) using the above options.
️ When NFC is configured asrequiredwith code, unlike with Studio, SDK will not filter out document types that are not NFC capable, for end-user best experience, expose only document types that are NFC capable as listed here, or prefer using Studio
The iOS SDK supports the customization of colors, fonts and strings used in the SDK flow.
To customize the look and feel of the SDK, you can pass the required CSS values to the Appearance object, in the root of the WorkflowConfiguration object.
let appearance = Appearance()
appearance.primaryColor = <DESIRED_UI_COLOR_HERE>
appearance.primaryTitleColor = <DESIRED_UI_COLOR_HERE>ONAppearance *appearance = [[ONAppearance alloc] init];
appearance.primaryColor = <DESIRED_UI_COLOR_HERE>;
appearance.primaryTitleColor = <DESIRED_UI_COLOR_HERE>;Please refer to the SDK customization documentation for details of the supported UI options that can be set in this property.
The iOS SDK supports dark theme customization. By default, the user's active device theme will be automatically applied to the Onfido SDK. However, you can opt out from dynamic theme switching at run time and instead set a theme statically at the build time as shown below. In this case, the flow will always be displayed in the selected theme regardless of the user's device theme.
interfaceStyle allows you to force light or dark mode via .dark and .light respectively.
By default, it is set to .unspecified, which will follow the system's interface style.
Note: The previous attribute supportDarkMode is now deprecated. Please use interfaceStyle instead.
For example, to set the interface style to .dark, you can use the code below:
let appearance = Appearance()
appearance.setUserInterfaceStyle(.dark)ONAppearance *appearance = [ONAppearance new];
[appearance setUserInterfaceStyle:UIUserInterfaceStyleDark];To apply the appearance you can use the methods below:
let configBuilder = OnfidoConfig.builder()
configBuilder.withAppearance(appearance)ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder];
[configBuilder withAppearance:appearance];The Onfido SDK allows for two co-branding options that affect the display of the Onfido logo at the bottom of the Onfido screens.
cobrand {Object} - optional
The most effective way to add your brand to the footer watermark is by use of the cobrand property under enterpriseFeatures. This property takes a text parameter.
let companyName = "MyCompany"
let enterpriseFeatures = EnterpriseFeatures.builder()
.withCobrandingText(companyName)
.build()NSString *companyName = @"MyCompany";
ONEnterpriseFeaturesBuilder *enterpriseFeatures = [ONEnterpriseFeatures builder];
[enterpriseFeatures withCobrandingText: companyName];
[enterpriseFeatures build];Please note: Text co-branding must be enabled by Onfido. Please contact your Solutions Engineer or Customer Success Manager to activate the feature.
logoCobrand {Object} - optional
As an alternative to cobrand, you may specify a set of images to be defined in the logoCobrand property under enterpriseFeatures. You must provide the path to an image for use in 'dark' mode and a separate image for 'light' mode. Both images must have a resolution of 144x32.
let onfidoEnterpriseFeatures = EnterpriseFeatures.builder()
.withCobrandingLogo(
UIImage(named: "imageName_for_lightmode")!,
cobrandingLogoDarkMode: UIImage(named: "imageName_for_darkmode")!
)
.build()ONEnterpriseFeaturesBuilder *enterpriseFeatures = [ONEnterpriseFeatures builder];
[enterpriseFeatures withCobrandingLogo:
[UIImage imageNamed:@"onfido-logo-white"] cobrandingLogoDarkMode:[UIImage imageNamed:@"onfido-logo-grey"]
];
[enterpriseFeatures build];Please note: Logo co-branding must be enabled by Onfido. Please contact your Solutions Engineer or Customer Success Manager to activate the feature.
To apply co-branding, add the enterprise features object to OnfidoConfig:
let configBuilder = OnfidoConfig.builder()
configBuilder.withEnterpriseFeatures(enterpriseFeatures)ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder];
[configBuilder withEnterpriseFeatures: enterpriseFeatures];The Onfido SDK supports and maintains translations for over 40 languages.
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.
- (void)withCustomLocalization {
[self.configBuilder withCustomLocalization]; // will look for localizable strings in your Localizable.strings file
}For the list of languages supported by Onfido, please refer to our SDK customization documentation.
Note: If no language is selected, the SDK will detect and use the end user's device language setting. If the device's language is not supported, the SDK will default to English (en_US).
The SDK can also be displayed in a custom language for locales that Onfido does not currently support. You can supply full or partial translations. For any key without a translation, the supported language default will be used.
When adding custom translations, you must add the whole set of keys included in the Localizable.strings file.
You can 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:
withCustomLocalization(andTableName: "MY_CUSTOM_STRINGS_FILE") (Swift)[configBuilder withCustomLocalizationWithTableName:@"MY_CUSTOM_STRINGS_FILE"]; (Objective-C)Additionally you can specify the bundle from which to read the strings file:
withCustomLocalization(andTableName: "MY_CUSTOM_STRINGS_FILE", in: myBundle) (Swift)[configBuilder withCustomLocalizationWithTableName:@"MY_CUSTOM_STRINGS_FILE" in: myBundle]; (Objective-C)Note:
To request a new language translation, or offer feedback or suggestions on the translations provided, you can get in touch with Onfido's Customer Support
When the Onfido SDK session concludes, a range of callback functions may be triggered.
For advanced callbacks used for user analytics and returning submitted media, please refer to the Advanced Callbacks section of this document.
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
|
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/api/latest#errors for more information
case OnfidoFlowError.exception(withError: let error, withMessage: let message):
// This happens when an unexpected error occurs.
// Please email [Customer support](mailto:supportonfido.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
}
}While the SDK is responsible for capturing and uploading the user's media and data, identity verification reports themselves are generated based on workflows created using Onfido Studio.
For a step-by-step walkthrough of creating an identity verification using Onfido Studio and our SDKs, please refer to our Quick Start Guide.
If your application initializes the Onfido iOS SDK using the options defined in the Advanced customization section of this document, you may create checks and retrieve report results manually using the Onfido API. You may also configure webhooks to be notified asynchronously when the report results have been generated.
This section on 'Advanced customization' refers to the process of initializing the Onfido iOS SDK without the use of Onfido Studio. This process requires a manual definition of the verification steps and their configuration.
These flow step parameters are mutually exclusive with workflowRunId, requiring an alternative method of instantiating the client and starting the flow.
Note that this initialization process is not recommended as the majority of new features are exclusively released for Studio workflows.
The SDK is authenticated using SDK tokens. As each SDK token must be specific to a given applicant and session, a new token must be generated each time you initialize the Onfido iOS SDK.
| Parameter | Notes |
|---|---|
applicant_id |
required Specifies the applicant for the SDK instance. |
application_id |
required The application ID (for iOS "application bundle ID") that was set up during development. For iOS, this is usually in the form com.your-company.app-name. Make sure to use a valid application_id or you'll receive a 401 error. |
For details on how to manually generate SDK tokens, please refer to POST /sdk_token/ definition in the Onfido API reference.
Note: You must never use API tokens in the frontend of your application as malicious users could discover them in your source code. You should only use them on your server.
expireHandler
When manually generating SDK tokens, it's important to note that they expire after 90 minutes.
With this in mind, we recommend you use the optional expireHandler parameter in the SDK token configuration 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.
For example:
func getSDKToken(_ completion: @escaping (String) -> Void) {
// Your network request logic to retrieve SDK token goes here
completion(myNewSDKtoken)
}
let config = try OnfidoConfig.builder()
.withSDKToken("<YOUR_SDK_TOKEN>", expireHandler: getSDKToken)-(void) getSDKToken: (void(^)(NSString *)) handler {
// <Your network request logic to retrieve SDK token goes here>
handler(sdkToken);
}
ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder];
[configBuilder withSdkToken:@"YOUR_SDK_TOKEN" expireHandler:^(void (^ handler)(NSString * expireHandler)) {
[self getSDKToken:handler];
}];Once you have added the SDK dependency, and you have an applicant ID, you can manually configure the SDK flow steps:
let config = try OnfidoConfig.builder()
.withSDKToken("<YOUR_SDK_TOKEN>")
.withWelcomeStep()
.withDocumentStep()
.withProofOfAddressStep()
.withFaceStep(ofVariant: .photo(withConfiguration: nil))
.build()
let onfidoFlow = OnfidoFlow(withConfiguration: config)
.with(responseHandler: { results in
// Callback when flow ends
})ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder];
[configBuilder withSdkToken:@"YOUR_SDK_TOKEN"];
[configBuilder withWelcomeStep];
[configBuilder withDocumentStep];
[configBuilder withProofOfAddressStep];
NSError *variantConfigError = NULL;
Builder *variantBuilder = [ONFaceStepVariantConfig builder];
[variantBuilder withPhotoCaptureWithConfig: NULL];
[configBuilder withFaceStepOfVariant: [variantBuilder buildAndReturnError: &variantConfigError]];
if (variantConfigError == NULL) {
NSError *configError = NULL;
ONFlowConfig *config = [configBuilder buildAndReturnError:&configError];
if (configError == NULL) {
ONFlow *onFlow = [[ONFlow alloc] initWithFlowConfiguration:config];
[onFlow withResponseHandler:^(ONFlowResponse *response) {
// Callback when flow ends
}];
}
}try onfidoRun.run(from: yourViewController, animated: true)NSError *runError = NULL;
[onFlow runFrom:yourViewController animated:YES error:&runError completion:nil];
if (runError != NULL) {
// do fallback logic
}To customize the look and feel of the SDK, you can pass the required CSS values to the Appearance object in the root of the OnfidoConfig.builder() object.
let appearance = Appearance()
appearance.primaryColor = <DESIRED_UI_COLOR_HERE>
appearance.primaryTitleColor = <DESIRED_UI_COLOR_HERE>ONAppearance *appearance = [[ONAppearance alloc] init];
appearance.primaryColor = <DESIRED_UI_COLOR_HERE>;
appearance.primaryTitleColor = <DESIRED_UI_COLOR_HERE>;To apply the appearance, you can use the methods below:
let configBuilder = OnfidoConfig.builder()
configBuilder.withAppearance(appearance)ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder];
[configBuilder withAppearance:appearance];Please refer to the SDK customization documentation for details of the supported UI options that can be set in this property.
You can customize the flow of the SDK by adding steps to the SDK flow.
The possible steps include:
| Step | Description |
|---|---|
withWelcomeStep |
Welcome screen shown to the user with preliminary instructions. Customization options include modification to the text elements and instructions shown to the user. |
withDocumentStep |
Set of screens that control the capture via photo or upload of the user's document. Numerous customization options are available to define the document list presented to the user and the overall capture experience. |
withFaceStep |
Set of screens that control the capture of a selfie, video or motion capture of the user. The customization options allow the selection of the capture variant. |
withProofOfAddressStep |
Screen where the user selects the issuing country and type of document to verify their address. |
This step is the introduction screen of the SDK. It introduces the process and prepares the user for the steps they will need to complete.
While this screen is optional, we only recommend its removal if you already have your own identity verification welcome screen in place.
You can show the welcome screen by calling configBuilder.withWelcomeStep() in Swift
or [configBuilder withWelcomeStep] in Objective-C.
