测试已测试 | ✗ |
Lang语言 | Obj-CObjective C |
许可证 | 自定义 |
发布最后发布 | 2019年8月 |
由 Anurag Ajwani、Bart Ziemba、Onfido 维护。
此 SDK 提供了一组用于 iOS 应用的屏幕和工具,允许捕获身份证件和面部照片,以便与 Onfido 进行身份验证。该 SDK 提供了多项优势,帮助您为您的客户提供最佳的入职/身份验证体验
注意:SDK 只负责捕获和上传照片。您仍然需要访问 Onfido API 来创建和管理检查。
为了开始集成,您需要 API 令牌 和 移动 SDK 令牌。您可以使用我们的 沙盒 环境测试您的集成,您将在您的 Onfido 控制台 中找到这两个沙盒令牌。
警告:您 必须 使用 移动 SDK 令牌,而不是 API 令牌 来配置 SDK 本身。
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 中添加以下内容将其包含到项目中
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
字段,该 UUID 用于标识申请人。您将传递申请人 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
。
作为OnfidoResponse.error(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 {
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文档中的认证部分。测试时,应使用沙盒而不是实时令牌。
您需要通过向创建检查端点发起请求,使用SDK 回调中可用的申请人ID来创建一个express检查。如果您只是验证文件,只需将文件报告作为检查的一部分即可。另一方面,如果您还需要用文件和面部验证,您还需要包括面部相似度报告。
$ 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文档中的Webhooks部分。
您可以在MIGRATION.md文件中找到迁移指南。
开发过程中可以使用pod 'Onfido'
,但这将导致无法提交到应用商店。请在您的Podfile中使用pod 'Onfido-Release'
以提交到应用商店。
有关我们这样做的原因的更多信息,请查看我们的常见问题解答
我们包含了一个示例应用来展示如何集成Onfido SDK。请查看SampleApp目录。
请通过GitHub打开一个问题。请尽可能详细说明。请记住不要在问题中提交您的令牌。还要检查已关闭的问题,以查看它是否之前已经提出并得到解答。
如果您有任何包含敏感信息的问题,请通过电子邮件发送带有主题行中ISSUE:
开头的电子邮件到[email protected]
版权所有 2017 Onfido,有限公司。保留所有权利。