Onfido-Release 13.2.0

Onfido-Release 13.2.0

测试已测试
Lang语言 Obj-CObjective C
许可证 自定义
发布最后发布2019年8月

Anurag AjwaniBart ZiembaOnfido 维护。



  • Onfido, Ltd

Onfido

Version
Build Status
License
Platform

目录

概述

此 SDK 提供了一组用于 iOS 应用的屏幕和工具,允许捕获身份证件和面部照片,以便与 Onfido 进行身份验证。该 SDK 提供了多项优势,帮助您为您的客户提供最佳的入职/身份验证体验

  • 精心设计的 UI,可指导您的客户完成整个拍照过程
  • 模块化设计,帮助您无缝将拍照过程集成到您的应用程序流程中
  • 先进图像质量检测技术,确保捕获的图像质量满足 Onfido 身份验证过程的要求,保证最佳成功率
  • 直接将图像上传到 Onfido 服务,以简化集成*

注意:SDK 只负责捕获和上传照片。您仍然需要访问 Onfido API 来创建和管理检查。

Capture Document and face

入门

  • SDK 支持 iOS 8.0 及以上版本
  • SDK 支持 Swift 3.2.2 和 Swift 4.0.2

1. 获取令牌

为了开始集成,您需要 API 令牌移动 SDK 令牌。您可以使用我们的 沙盒 环境测试您的集成,您将在您的 Onfido 控制台 中找到这两个沙盒令牌。

警告:必须 使用 移动 SDK 令牌,而不是 API 令牌 来配置 SDK 本身。

2. 应用程序权限

Onfido SDK 使用设备的相机。您需要在应用程序的 Info.plist 文件中包含 NSCameraUsageDescriptionNSMicrophoneUsageDescription 键。

<key>NSCameraUsageDescription</key>
<string>Required for document and facial capture</string>
<key>NSMicrophoneUsageDescription</key>
<string>Required for video capture</string>

注意:两个键都将需要用于应用程序提交。

3. 添加 SDK 依赖项

SDK 可在 Cocoapods 上获取,您可以通过在 Podfile 中添加以下内容将其包含到项目中

pod 'Onfido'

运行 pod install 以获取 SDK。

4. 创建申请人

在开始流程之前,您必须创建一个 Onfido 申请人

对于文件或面部检查,所需的最低申请人信息为 firstNamelastName

您必须从您的服务器创建申请人

$ 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 上传的所有文件或实时照片都将与该申请人关联。

5. 创建 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
    })

6. 启动流程

let onfidoRun = try! onfidoFlow.run()

self.present(onfidoRun, animated: true, completion: nil) //`self` should be your view controller

重要注意:请确保在流程完成之前保持对OnfidoFlow对象的强引用,否则流程无法正确运行。

恭喜!您已成功启动流程。继续阅读下一节,了解如何

  • 处理回调
  • 自定义SDK
  • 创建检查

处理回调

为了从流程中接收结果,您应该在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可以有以下值

  1. (已弃用) OnfidoResult.applicant:在流程结束后,您想查看其负载以找到申请人ID。只有在拥有此ID的情况下才能创建检查。
  2. OnfidoResult.documentOnfidoResult.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
}

面部结构类似于文档,但是caseOnfidoResult.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时,以下内容是必需的

  • 移动SDK令牌
  • 申请人
  • 至少一个捕获步骤

否则,在调用OnfidoConfig.Builder实例上的build()函数时,您可能会遇到以下错误

  • OnfidoConfigError.missingToken,当未提供或提供的令牌为空字符串时
  • OnfidoConfigError.missingApplicant,当未提供申请人实例时
  • OnfidoConfigError.missingSteps,当未提供步骤时
  • OnfidoConfigError.multipleApplicants,当提供了申请人及申请人ID时

自定义 SDK

您可以通过在配置时指定要捕获和上传的步骤来自定义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()

1. 获取API令牌

所有API请求都必须在请求头中包含API令牌。您可以在您的Onfido控制台中找到您的API令牌(请勿与移动SDK令牌混淆)。

有关详细信息,请参阅API文档中的认证部分。测试时,应使用沙盒而不是实时令牌。

2. 创建检查

您需要通过向创建检查端点发起请求,使用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以在结果准备就绪时接收通知。

最后,由于您正在使用沙盒令牌进行测试,请注意结果是预先设定的。您可以在此处了解更多关于沙盒响应的信息。

3. 设置webhooks

有关详细信息,请参阅API文档中的Webhooks部分。

迁移

您可以在MIGRATION.md文件中找到迁移指南。

更多信息

应用商店提交

开发过程中可以使用pod 'Onfido',但这将导致无法提交到应用商店。请在您的Podfile中使用pod 'Onfido-Release'以提交到应用商店。

有关我们这样做的原因的更多信息,请查看我们的常见问题解答

示例应用

我们包含了一个示例应用来展示如何集成Onfido SDK。请查看SampleApp目录。

支持

请通过GitHub打开一个问题。请尽可能详细说明。请记住不要在问题中提交您的令牌。还要检查已关闭的问题,以查看它是否之前已经提出并得到解答。

如果您有任何包含敏感信息的问题,请通过电子邮件发送带有主题行中ISSUE:开头的电子邮件到[email protected]

版权所有 2017 Onfido,有限公司。保留所有权利。