此 SDK 为 iOS 应用程序提供一个即插即用的屏幕和工具集,允许捕获身份证明文件和面部照片,用于与 Onfido 进行身份验证。SDK 提供了一系列优点,帮助您为您的客户创造最佳的入住/身份验证体验
*注意:SDK 仅负责捕获和上传照片。您仍然需要访问 Onfido API 来创建和管理检查。
为了开始集成,您需要 API 令牌 和 移动 SDK 令牌。您可以使用我们的 沙盒 环境测试您的集成,这两个沙盒令牌将在您的 Onfido 控制台 中找不到。
警告:您 必须 在配置 SDK 本身时使用 移动 SDK 令牌 而不是 API 令牌
Onfido SDK 使用设备相机。您需要在应用程序的 Info.plist
文件中具有 NSCameraUsageDescription
和 NSMicrophoneUsageDescription
键
<key>NSCameraUsageDescription</key>
<string>Required for document and facial capture</string>
<key>NSMicrophoneUsageDescription</key>
<string>Required for video capture</string>
注意:两个键都将用于应用程序提交。
SDK 可在 Cocoapods 上找到,您可以通过在 Podfile 中添加以下内容将 SDK 包含到项目中
pod 'Onfido'
运行 pod install
以获取 SDK。
在开始流程之前,您必须创建一个 Onfido 申请者。
对于文档或面部检查,所需的最低申请者详细信息包括 firstName
和 lastName
。
您必须从您的服务器创建申请人
$ curl https://api.onfido.com/v2/applicants \
-H 'Authorization: Token token=YOUR_API_TOKEN' \
-d 'first_name=Theresa' \
-d 'last_name=May'
JSON响应中有一个包含UUID的字段id
,用于标识申请人。您将把申请人ID传递到SDK中,并且SDK该实例上传的所有文档或现场照片将与该申请人关联。
添加SDK作为依赖项并且您有申请人ID后,您可以配置SDK
let config = try! OnfidoConfig.builder()
.withToken("YOUR_TOKEN_HERE")
.withApplicantId("APPLICANT_ID_HERE")
.withDocumentStep()
.withFaceStep(ofVariant: .photo)
.build()
let onfidoFlow = OnfidoFlow(withConfiguration: config)
.with(responseHandler: { results in
// Callback when flow ends
})
let onfidoRun = try! onfidoFlow.run()
self.present(onfidoRun, animated: true, completion: nil) //`self` should be your view controller
重要提示:请确保在流程完成之前始终保持对OnfidoFlow
对象的强引用,否则流程将无法正确执行。
恭喜!您已成功启动流程。继续阅读下一部分,了解如何
要接收流程结果,您应将回调传递给OnfidoFlow
的实例。通常,在成功的情况下,您会在您的后端服务器上创建一个检查。
传递给回调的结果对象可能包括以下属性:.success([OnfidoResult])
、.error(Error)
和.cancel
。
let responseHandler: (OnfidoResponse) -> Void = { response in
switch response {
case let .error(error):
// Some error happened
case let .success(results):
// User completed the flow
// You can create your check here
case .cancel:
// Flow cancelled by the user
}
}
成功是当用户到达流程的末尾。
[OnfidoResult]
是一个列表,包含多个结果。这些结果具有不同的枚举值,每个枚举值都有一个与之关联的值(也称为有效负载)。此枚举值OnfidoResult
可以有以下值
OnfidoResult.applicant
:要创建检查,您需要查看其有效负载以找到申请人ID。只有有了这个ID,您才能创建检查。OnfidoResult.document
和OnfidoResult.face
:如果想要以某种方式处理或预览捕获,则其有效负载相关信息适用。继续阅读,了解如何提取每个OnfidoResult
枚举值的有效负载。
如何处理申请人结果
let applicant: Optional<OnfidoResult> = results.filter({ result in
if case OnfidoResult.applicant = result { return true }
return false
}).first
if let applicantUnwrapped = applicant, case OnfidoResult.applicant(let applicantResult) = applicantUnwrapped {
/* applicantResult
Onfido api response to the creation of the applicant
More details: https://documentation.onfido.com/#create-applicant
*/
print(applicantResult.id)
// At this point you have all the necessary information to create a check
}
您需要一个申请人ID来创建检查,请参阅创建检查。
在正常情况下,您不需要检查捕获的结果本身,因为SDK会为您处理文件上传。
但是,如果您想查看有关文件和面部捕获的信息,您可以按照如下方式访问结果对象
let document: Optional<OnfidoResult> = results.filter({ result in
if case OnfidoResult.document = result { return true }
return false
}).first
if let documentUnwrapped = document, case OnfidoResult.document(let documentResponse) = documentUnwrapped {
/* documentResponse
Onfido API response to the upload of the document
More details: https://documentation.onfido.com/#upload-document
*/
print(documentResponse.id)
// use documentResponse.href to fetch the captured image if required
}
面部遵循类似于文件的类似结构,但是case
是OnfidoResult.face
而不是OnfidoResult.document
。
返回的Error
对象是作为OnfidoResponse.error(Error)
一部分的,类型为OnfidoFlowError
。它是一个枚举,有多种情况,具体取决于错误类型。
注意:不是所有属于OnfidoFlowError
的情况都将传递给OnfidoResponse.error
,有一个情况会以异常形式返回错误,请参阅运行异常和配置错误。
switch response {
case let OnfidoResponse.error(error):
switch error {
case OnfidoFlowError.cameraPermission:
// It happens if the user denies permission to the sdk during the flow
case OnfidoFlowError.failedToWriteToDisk:
// It happens when the SDK tries to save capture to disk, maybe due to a lack of space
case OnfidoFlowError.microphonePermission:
// It happens when the user denies permission for microphone usage by the app during the flow
case OnfidoFlowError.upload(let OnfidoApiError):
// It happens when the SDK receives an error from a API call see [https://documentation.onfido.com/#errors](https://documentation.onfido.com/#errors) for more information
case OnfidoFlowError.exception(withError: let error, withMessage: let message):
// It happens when an unexpected error occurs, please contact [[email protected]](mailto:[email protected]?Subject=ISSUE%3A) when this happens
default: // necessary because swift
}
}
在初始化SDK时可能会出现异常,您可以使用下面的do/catch
来处理
do {
let onfidoRun = try self.onfidoFlow!.run()
self.present(onfidoRun, animated: true, completion: nil)
}
catch let error {
switch error {
case OnfidoFlowError.cameraPermission:
// do something about it here
case OnfidoFlowError.microphonePermission:
// do something about it here
case OnfidoFlowError.deviceHasNoCamera:
// do something about it here
default:
// should not happen, so if it does, log it and let us know
}
}
配置Onfido iOS SDK时需要以下要求
否则,在调用OnfidoConfig.Builder实例上的build()
函数时可能会遇到以下错误
OnfidoConfigError.missingToken
,当没有或字符串为空的令牌提供时OnfidoConfigError.missingApplicant
,当没有提供申请人实例时OnfidoConfigError.missingSteps
,当没有提供步骤时OnfidoConfigError.multipleApplicants
,当提供了申请人和申请人ID时通过配置时指定要捕获和上传的步骤,可以自定义SDK。
您可以指定捕获用户的文件和/或面部。
面部步骤有两个变体
FaceStepVariant.photo
用于面部照片捕获FaceStepVariant.video
用于面部视频捕获let config = try! OnfidoConfig.builder()
.withToken("YOUR_TOKEN_HERE")
.withApplicantId(applicantId)
.withDocumentStep()
.withFaceStep(ofVariant: .photo) // specify the face capture variant here
.build()
文档步骤可以进一步配置,以从特定国家捕获单一类型的文档。支持的文档类型有:
DocumentType.passport
DocumentType.drivingLicence
DocumentType.nationalIdentityCard
DocumentType.residencePermit
假设您希望仅从英国捕获驾驶执照。以下代码展示了如何实现此操作:
let config = try! OnfidoConfig.builder()
.withToken("YOUR_TOKEN_HERE")
.withApplicantId(applicantId)
.withDocumentStep(ofType: .drivingLicence, andCountryCode: "GBR")
.withFaceStep(ofVariant: .photo) // specify the face capture variant here
.build()
所有API请求都必须在请求数据头中包含API令牌。您可以在您的Onfido仪表板中找到您的API令牌(不要与移动SDK令牌混淆)。
有关详细信息,请参阅API文档中的身份验证部分。对于测试,您应使用沙箱,而不是实时令牌。
您需要通过向创建检查端点发送请求来创建一个express检查,使用SDK 回调中可用的申请人id。如果您只需要验证文档,您只需在检查中包含一个文档报告。另一方面,如果您需要验证文档和面部,还需要包含一个面部相似度报告。
$ curl https://api.onfido.com/v2/applicants/YOUR_APPLICANT_ID/checks \
-H 'Authorization: Token token=YOUR_API_TOKEN' \
-d 'type=express' \
-d 'reports[][name]=document' \
-d 'reports[][name]=facial_similarity'
注意:您也可以以JSON格式提交POST请求。
您将立即收到包含检查id的响应。由于文档和面部相似度报告并不总是立即返回实际结果,您需要设置一个webhook以在结果准备好时通知您。
最后,由于您正在使用沙箱令牌进行测试,请注意,结果是预先确定的。有关沙箱响应的更多信息,请在此处了解。
有关详细信息,请参阅API文档中的webhook部分。
您可以在MIGRATION.md文件中找到迁移指南
在开发过程中可以使用pod 'Onfido'
,但这样会导致App Store提交失败。请在您的Podfile中使用pod 'Onfido-Release'
以进行App Store提交。
有关我们为何这样做的原因的更多信息,请查看我们的常见问题解答
我们包含了一个示例应用来展示如何与Onfido SDK集成。请查看SampleApp目录。
请通过GitHub提交一个问题。请尽可能详细。请记住不要将令牌提交到问题中。此外,请检查已关闭的问题,以查看它是否已被以前提出和解答过。
如果您有任何包含敏感信息的问题,请发送一封电子邮件至[email protected],邮件主题以ISSUE:
开头。
版权所有2017 Onfido, Ltd. 保留所有权利。