onfido ios sdk
32.1.0
Onfido 智能捕获 SDK 提供了一组屏幕和功能，使应用程序能够实现用户身份验证流程。每个 SDK 包含：
所有 Onfido 智能捕获 SDK 均使用 Onfido Studio 工作流程进行编排，可用平台之间只有微小的定制差异。
有两种环境支持 Onfido SDK 集成：
所使用的环境由用于生成必要的 SDK 令牌的 API 令牌决定。
一旦您对集成感到满意并准备好上线，请联系 Onfido 的客户支持以获取实时 API 令牌。您必须将代码中的沙箱令牌替换为实时令牌。
在上线之前，请检查您是否在 Onfido 控制面板中输入了正确的账单详细信息。
iOS SDK 支持：
注意：支持 Xcode 11.5-12 的最新 SDK 版本是 iOS SDK 版本 22，Xcode 14+ 是 iOS SDK 版本 29。如果需要，有针对旧版本 Xcode 的解决方法。请联系 Onfido 的客户支持团队了解更多信息。
注意：iOS SDK 需要 CoreNFC 才能运行（无论您是否使用 NFC）。从 Xcode 12 开始，存在一个错误，即模拟器中缺少libnfshared.dylib 。有关此问题的解决方案，请参阅 Stack Overflow。
注意：如果您禁用 NFC 功能，Apple 可能会要求您提供视频来演示 NFC 的使用情况，因为无论运行时配置如何，与 NFC 相关的代码都是 SDK 二进制文件的一部分。当我们正在努力解决此问题时，您可以同时联系 Onfido 的客户支持以获取视频。
SDK 使用用户设备的摄像头（用于文档和面部捕捉）和麦克风（用于视频和动作捕捉）。您需要在应用程序的Info.plist文件中包含以下键：
NSCameraUsageDescriptionNSMicrophoneUsageDescription< key >NSCameraUsageDescription</ key >
< string >Required for document and face capture</ string >
< key >NSMicrophoneUsageDescription</ key >
< string >Required for video capture</ string >注意：提交应用程序需要所有密钥。
该 SDK 可通过 Swift Package Manager 获取，您可以通过添加以下包存储库 URL 将其包含在您的项目中：
dependencies: [
. package ( url : " https://github.com/onfido/onfido-ios-sdk.git " , . branch ( " master " ) )
] 该 SDK 也可在 CocoaPods 上使用，您可以通过将以下内容添加到 Podfile 中将其包含在您的项目中：
pod 'Onfido'运行pod install获取 SDK。
该 SDK 可在 GitHub Releases 选项卡中找到，您可以在其中下载压缩框架。您可以在此处找到最新版本。
Onfido.xcframework的压缩 zip 文件Onfido.xcframework工件移至您的项目文件夹中Onfido.xcframework添加到 iOS 应用程序目标的General选项卡中的Embedded binaries部分如果您的应用程序不是基于 Swift，那么您必须在项目内创建一个新的 Swift 文件。需要此文件来强制 Xcode 打包 Onfido iOS SDK 运行所需的 Swift 运行时库。
创建一个包含以下内容的 Swift 文件：
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 " )
}在项目配置中将Always Embed Swift Standard Libraries设置为Yes 。
️ 以下 SDK 初始化文档适用于使用 Onfido Studio 编排的身份验证工作流程。对于手动定义和配置验证步骤的集成，请参阅下面的高级流程自定义部分。
iOS SDK 具有多个初始化和自定义选项，可为您的集成提供灵活性，同时保持易于集成。
Onfido Studio 是用于创建高度可重用的身份验证工作流程以与 Onfido SDK 结合使用的平台。有关使用工作流程的介绍，请参阅我们的入门指南或 Onfido Studio 产品指南。
SDK 会话由特定于会话的workflow_run_id编排，该会话本身源自workflow_id （给定工作流的唯一标识符）。
有关如何生成workflow_run_id的详细信息，请参阅Onfido API参考中的POST /workflow_runs/端点定义。
请注意，在 SDK 上下文中，
workflow_run_id属性称为workflowRunId。
在定义工作流程和创建身份验证时，我们强烈建议针对特定用户保存applicant_id以供重复使用。如果您希望对同一个人运行多个身份验证，或者在用户返回并恢复验证流程的情况下，这有助于跟踪用户。
SDK 使用 SDK 令牌进行身份验证。创建工作流程运行时，Onfido Studio 在 API 返回的工作流程运行负载中生成并公开 SDK 令牌。
Studio 的 SDK 令牌只能与为其生成的特定工作流程运行一起使用，并且有效期为五周。
注意：您绝不能在应用程序的前端使用 API 令牌，因为恶意用户可能会在您的源代码中发现它们。您应该只在您的服务器上使用它们。
要使用 SDK，您需要使用生成的 SDK 令牌和工作流运行 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 result最近的护照、国民身份证和居留证都包含可使用近场通信 (NFC) 进行访问的芯片。 Onfido SDK 提供了一组屏幕和功能来提取此信息、验证其真实性并提供验证结果作为文档报告的一部分。
从 Onfido iOS SDK 版本 29.1.0 开始，NFC 默认启用，并且当文档和设备都支持 NFC 时向最终用户提供。
有关如何配置 NFC 和支持的文档列表的更多信息，请参阅 NFC 文档报告指南。
此功能需要您的应用程序目标具有Near Field Communication Tag Reading功能。如果您之前没有添加过，请按照 Apple 文档中的步骤操作。
要支持 NFC PACE 文档，您需要编辑应用程序权限：
Near Field Communication Tag Reader Session Formats键下的新条目Password Authenticated Connection Establishment (PACE)< key >com.apple.developer.nfc.readersession.formats</ key >
< array >
< string >PACE</ string >
< string >TAG</ string >
</ array >您需要在应用程序的Info.plist文件中包含以下键：
< key >NFCReaderUsageDescription</ key >
< string >Required to read ePassports</ string >Info.plist文件中，才能正确读取 NFC 标签。 <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>
要使用 Onfido Studio 配置 NFC，您可以在工作流程构建器中使用以下选项之一：
optional ）：如果可能，将尝试 NFC 读取要在代码中配置 NFC，请在使用上述选项配置OnfidoConfig时调用withNFC()函数（请参阅下面的高级流程自定义部分）。
️ 当使用代码根据required配置 NFC 时，与 Studio 不同，SDK 不会过滤掉不支持 NFC 的文档类型，为了最终用户获得最佳体验，仅公开此处列出的支持 NFC 的文档类型，或者更喜欢使用 Studio
iOS SDK 支持自定义 SDK 流程中使用的颜色、字体和字符串。
要自定义 SDK 的外观，您可以将所需的 CSS 值传递给WorkflowConfiguration对象根中的Appearance对象。
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>;请参阅 SDK 自定义文档，了解可在此属性中设置的支持的 UI 选项的详细信息。
iOS SDK支持深色主题定制。默认情况下，用户的活动设备主题将自动应用到 Onfido SDK。但是，您可以选择在运行时退出动态主题切换，而是在构建时静态设置主题，如下所示。在这种情况下，无论用户的设备主题如何，流程将始终以选定的主题显示。
interfaceStyle允许您分别通过.dark和.light强制浅色或深色模式。默认情况下，它设置为.unspecified ，这将遵循系统的界面风格。
注意：以前的属性supportDarkMode现已弃用。请改用interfaceStyle 。
例如，要将界面风格设置为.dark ，可以使用以下代码：
let appearance = Appearance ( )
appearance . setUserInterfaceStyle ( . dark ) ONAppearance *appearance = [ONAppearance new ];
[appearance setUserInterfaceStyle: UIUserInterfaceStyleDark];要应用外观，您可以使用以下方法：
let configBuilder = OnfidoConfig . builder ( )
configBuilder . withAppearance ( appearance ) ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withAppearance: appearance];Onfido SDK 允许两个联合品牌选项，这些选项会影响 Onfido 屏幕底部 Onfido 徽标的显示。
cobrand {Object} - 可选
将品牌添加到页脚水印的最有效方法是使用enterpriseFeatures下的cobrand属性。该属性采用text参数。
let companyName = " MyCompany "
let enterpriseFeatures = EnterpriseFeatures . builder ( )
. withCobrandingText ( companyName )
. build ( ) NSString *companyName = @" MyCompany " ;
ONEnterpriseFeaturesBuilder *enterpriseFeatures = [ONEnterpriseFeatures builder ];
[enterpriseFeatures withCobrandingText: companyName];
[enterpriseFeatures build ];请注意：文本联合品牌必须由 Onfido 启用。请联系您的解决方案工程师或客户成功经理以激活该功能。
logoCobrand {Object} - 可选
作为cobrand的替代方案，您可以指定要在enterpriseFeatures下的logoCobrand属性中定义的一组图像。您必须提供用于“暗”模式的图像的路径和用于“亮”模式的单独图像的路径。两个图像的分辨率必须为 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 ];请注意：徽标联合品牌必须由 Onfido 启用。请联系您的解决方案工程师或客户成功经理以激活该功能。
要应用联合品牌，请将企业功能对象添加到OnfidoConfig ：
let configBuilder = OnfidoConfig . builder ( )
configBuilder . withEnterpriseFeatures ( enterpriseFeatures ) ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withEnterpriseFeatures: enterpriseFeatures];Onfido SDK 支持并维护 40 多种语言的翻译。
SDK 中使用的字符串可以通过在您的应用程序中为所需语言添加Localizable.strings并使用配置生成器上的withCustomLocalization()方法配置流程来自定义。
- ( void ) withCustomLocalization {
[ self . configBuilder withCustomLocalization ] ; // will look for localizable strings in your Localizable.strings file
}有关 Onfido 支持的语言列表，请参阅我们的 SDK 定制文档。
注意：如果未选择语言，SDK 将检测并使用最终用户的设备语言设置。如果设备的语言不受支持，SDK 将默认为英语 ( en_US )。
SDK 还可以针对 Onfido 目前不支持的区域设置以自定义语言显示。您可以提供完整或部分翻译。对于任何没有翻译的密钥，将使用支持的默认语言。
添加自定义翻译时，您必须添加Localizable.strings文件中包含的整套键。
您可以根据需要使用翻译后的密钥命名字符串文件，但必须将文件名作为withCustomLocalization()方法的参数提供给 SDK：
withCustomLocalization(andTableName: "MY_CUSTOM_STRINGS_FILE") (Swift)[configBuilder withCustomLocalizationWithTableName:@"MY_CUSTOM_STRINGS_FILE"]; （目标-C）此外，您可以指定从中读取字符串文件的包：
withCustomLocalization(andTableName: "MY_CUSTOM_STRINGS_FILE", in: myBundle) (Swift)[configBuilder withCustomLocalizationWithTableName:@"MY_CUSTOM_STRINGS_FILE" in: myBundle]; （目标-C）笔记：
要请求新的语言翻译，或对所提供的翻译提供反馈或建议，您可以联系 Onfido 的客户支持
当 Onfido SDK 会话结束时，可能会触发一系列回调函数。
有关用于用户分析和返回提交媒体的高级回调，请参阅本文档的高级回调部分。
要接收已完成工作流程的结果，您应该将回调传递给OnfidoFlow实例。提供以下代码作为示例：
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| 属性 | 笔记 |
|---|---|
| 。成功 | 当工作流中的所有交互式任务完成时触发的回调。成功后，如果您配置了 Webhook，系统将向您的后端发送一条通知，确认工作流程运行已完成。您不需要使用后端创建支票，因为这是由工作流程直接处理的 |
| .错误（错误） | 发生错误时触发的回调 |
| 。取消 | 当用户提前退出工作流时触发的回调。原因可以是.userExit或.consentDenied |
作为OnfidoResponse.error(Error)的一部分返回的Error对象的类型为OnfidoFlowError 。它是一个具有多种情况的枚举，具体取决于错误类型。
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
}
}虽然 SDK 负责捕获和上传用户的媒体和数据，但身份验证报告本身是根据使用 Onfido Studio 创建的工作流程生成的。
有关使用 Onfido Studio 和我们的 SDK 创建身份验证的分步演练，请参阅我们的快速入门指南。
如果您的应用程序使用本文档高级自定义部分中定义的选项初始化 Onfido iOS SDK，您可以使用 Onfido API 手动创建检查并检索报告结果。您还可以将 Webhooks 配置为在生成报告结果时异步收到通知。
本节“高级定制”是指在不使用 Onfido Studio 的情况下初始化 Onfido iOS SDK 的过程。此过程需要手动定义验证步骤及其配置。
这些流程步骤参数与workflowRunId互斥，需要另一种方法来实例化客户端并启动流程。
请注意，不建议执行此初始化过程，因为大多数新功能都是专门针对 Studio 工作流程发布的。
SDK 使用 SDK 令牌进行身份验证。由于每个 SDK 令牌必须特定于给定的申请人和会话，因此每次初始化 Onfido iOS SDK 时都必须生成新令牌。
| 范围 | 笔记 |
|---|---|
applicant_id | 必需的 SDK实例的申请者。 |
application_id | 必需的 在开发过程中设置的应用程序 ID（对于 iOS“应用程序包 ID”）。对于 iOS，这通常采用 com.your-company.app-name形式。请确保使用有效的application_id ，否则您将收到 401 错误。 |
有关如何手动生成 SDK 令牌的详细信息，请参阅 Onfido API 参考中的POST /sdk_token/定义。
注意：您绝不能在应用程序的前端使用 API 令牌，因为恶意用户可能会在您的源代码中发现它们。您应该只在您的服务器上使用它们。
expireHandler管理SDK令牌过期手动生成 SDK 令牌时，请务必注意它们会在 90 分钟后过期。
考虑到这一点，我们建议您在 SDK 令牌配置函数中使用可选的expireHandler参数来生成并在过期时传递新的 SDK 令牌。这确保了即使在 SDK 令牌过期后，SDK 仍能继续其流程。
例如：
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];
}];添加 SDK 依赖项并拥有申请人 ID 后，您可以手动配置 SDK 流程步骤：
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
}要自定义 SDK 的外观，您可以将所需的 CSS 值传递给OnfidoConfig.builder()对象根目录中的Appearance对象。
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>;要应用外观，您可以使用以下方法：
let configBuilder = OnfidoConfig . builder ( )
configBuilder . withAppearance ( appearance ) ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withAppearance: appearance];请参阅 SDK 自定义文档，了解可在此属性中设置的支持的 UI 选项的详细信息。
您可以通过向 SDK 流程添加步骤来自定义 SDK 的流程。
可能的步骤包括：
| 步 | 描述 |
|---|---|
withWelcomeStep | 向用户显示带有初步说明的欢迎屏幕。自定义选项包括对向用户显示的文本元素和说明的修改。 |
withDocumentStep | 一组屏幕，用于控制通过照片捕获或上传用户文档。许多自定义选项可用于定义呈现给用户的文档列表和整体捕获体验。 |
withFaceStep | 控制用户自拍照、视频或动作捕捉的一组屏幕。自定义选项允许选择捕获变体。 |
withProofOfAddressStep | 用户选择签发国家和文件类型以验证其地址的屏幕。 |
这一步是SDK的介绍界面。它介绍了该过程并让用户为他们需要完成的步骤做好准备。
虽然此屏幕是可选的，但我们仅建议您在已有自己的身份验证欢迎屏幕的情况下将其删除。
您可以通过调用 Swift 中的configBuilder.withWelcomeStep()或 Objective-C 中的[configBuilder withWelcomeStep]显示欢迎屏幕。
