Onfido 30.4.1

Onfido 30.4.1

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

ios-sdk-ciTestfido 维护。



Onfido 30.4.1

  • 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 本身时使用 移动 SDK 令牌 而不是 API 令牌

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 中添加以下内容将 SDK 包含到项目中

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,用于标识申请人。您将把申请人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

错误处理

响应处理错误

返回的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时需要以下要求

  • 移动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. 创建检查

您需要通过向创建检查端点发送请求来创建一个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以在结果准备好时通知您。

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

3. 设置webhook

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

迁移

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

更多信息

App Store提交

在开发过程中可以使用pod 'Onfido',但这样会导致App Store提交失败。请在您的Podfile中使用pod 'Onfido-Release'以进行App Store提交。

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

示例应用

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

支持

请通过GitHub提交一个问题。请尽可能详细。请记住不要将令牌提交到问题中。此外,请检查已关闭的问题,以查看它是否已被以前提出和解答过。

如果您有任何包含敏感信息的问题,请发送一封电子邮件至[email protected],邮件主题以ISSUE:开头。

版权所有2017 Onfido, Ltd. 保留所有权利。