接入文档

接口调用

最近更新时间:2020-11-23 10:45:47

SDK 中需要使用 camera,需要在 Info.plist中为 NSCameraUsageDescription 添加描述信息。

1. 概述

OCR SDK 对外提供以下两类证件的识别能力:

  • 身份证识别
  • 银行卡识别

2. SDK 头文件说明

SDK 一共对外暴露了 4 个头文件,如下所示:

├── Headers
│   ├── WBBankCardInfoModel.h
│   ├── WBIDCardInfoModel.h
│   ├── WBOCRConfig.h
│   ├── WBOCRService.h

这些头文件可以大致分为三类:

  • 模型类(WBBankCardInfoModel、WBDriverLicenseModel、WBIDCardInfoModel 和 WBVehicleLicenseModel),这些模型类分别对应银行卡、驾驶证、身份证和行驶证的识别结果字段。
  • 配置类(WBOCRConfig),这个类提供了 SDK 的配置选项。
  • 入口类(WBOCRService),这个类提供 SDK 的入口和回调。

2.1 模型类说明

模型类对外暴露识别结果,以身份证识别为例,WBIDCardInfoModel 类的实例返回身份证识别结果,结果中包含如下字段:

•    idcard 公民身份号码
•    name 姓名
•    sex 性别
•    nation 民族
•    address 住址
•    birth 出生
•    authority 签发机关
•    validDate 有效期限
•    frontFullImg 国徽面截图
•    backFullImg 人像面截图
•    orderNo 订单号,和本次业务相关
•    sign 签名信息
•    warning 识别结果警告信息
•    multiWarning 多重告警码,人像面是frontMultiWarning,国徽面对应backMultiWarning
•    clarity  图片清晰度,人像面是frontClarity,国徽面对应backClarity

开发者按需获取需要的信息。
其余证件识别与之类似,详情参考类头文件的字段注释。

2.2 配置类说明

WBOCRConfig 对外提供配置接口,下面的内容逐一介绍其核心接口。
WBOCRConfig 是一个单例,开发者必须通过制定的初始化方法 sharedConfig 初始化。
SDK一共支持四类证件识别,提供 8 种识别模式,通过 SDKType 这个参数配置 :

/// * @brief  OCR SDK 提供三大类证件的识别能力:身份证、银行卡、行驶证和驾驶证。
///
/// WBOCRSDKType 定义 SDK 不同的识别模式,下面分为四大类来描述这些模式:
/// 1. 身份证识别(识别身份证人像面和国徽面)
///     - WBOCRSDKTypeNoraml  : 身份证识别标准模式,在 SDK 中完成人像面 + 国徽面识别,识别完成之后,将本次识别结果返回第三方APP
///     - WBOCRSDKTypeFontSide: 身份证人像面识别模式,在 SDK 中完成人像面识别,识别完成之后,将本次识别结果返回第三方APP
///     - WBOCRSDKTypeBackSide: 身份证国徽面识别模式,在 SDK 中完成国徽面识别,识别完成之后,将本次识别结果返回第三方APP
///
/// 2. 银行卡识别(识别银行卡卡号面)
///     - WBOCRSDKTypeBankCard:银行卡识别模式,SDK调起成功后,直接进入银行卡识别,识别完成之后,将本次识别结果返回第三方APP

当 SDKType 为 WBOCRSDKTypeIDCardNormal / WBOCRSDKTypeVehicleLicenseNormal 的时候,可以通过 needBothSidesRecognized 参数进一步配置 SDK。

 * @brief needBothSidesRecognized 参数当 SDKType 为 `WBOCRSDKTypeIDCardNormal`  时候起作用,default NO
 *
 * @detail 当参数设置为 YES 时,SDK需要将证件两面都识别成功之后,才能点击“完成”按钮退出SDK
 *         当参数设置为 NO  时,SDK只需要身份证人像面识别成功,就可以点击“完成”按钮退出SDK
 */
@property (nonatomic) BOOL needBothSidesRecognized;

2.3 入口类说明

WBOCRService 是 SDK 的入口类,需要通过制定的初始化方法 sharedService 进行初始化。

/**
 * @brief WBOCRService 单例方法,通过调用该方法实例化 WBOCRService对象
 *
 * @return WBOCRService对象
 */
+ (nonnull instancetype) sharedService;
  • NONCE 类型的 ticket,其有效期为120秒,且一次性有效,即每次启动 SDK 刷脸都要重新请求 NONCE ticket,重新算 sign。同时建议合作方做前端保护,防止用户连续点击,短时间内频繁启动 SDK。
  • 初始化完成之后,传入指定的参数,可以调起 SDK,入口方法如下:
/**
 * @brief 调起SDK入口方法

 * @param config           配置参数
 * @param version         openAPI接口版本号,由腾讯服务统一分配
 * @param appId             appId,由腾讯服务分配的
 * @param license         license,由腾讯服务分配的
 * @param nonce             每次请求需要的一次性nonce,一次有效
 * @param userId            每个用户唯一的标识
 * @param sign              签名信息,有接入方后台提供,一次有效
 * @param orderNo           订单号,长度不能超过32位的字符串
 * @param startSucceed      SDK启动成功回调
 * @param recognizeSucceed  识别成功回调,即将退出SDK
 * @param failed            SDK发生异常退出后回调,即将退出SDK
 *
 */
- (void)startOCRServiceWithConfig:(nullable WBOCRConfig *)config
                          version:(nonnull NSString *)version
                            appId:(nonnull NSString *)appId
                          license:(nonnull NSString *)license
                            nonce:(nonnull NSString *)nonce
                           userId:(nonnull NSString *)userId
                             sign:(nonnull NSString *)sign
                          orderNo:(nonnull NSString *)orderNo
                     startSucceed:(nonnull WBOCRServiceStartSucceedBlock)startSucceed
                 recognizeSucceed:(nonnull WBOCRServiceRecognizeSuccessBlock)recognizeSucceed
                           failed:(nonnull WBOCRServiceFailedBlock)failed;

该类还提供了一个 readonly 字段,用来读取当前 SDK 的版本号。

/**
 * @brief sdk版本号,readonly参数
 */
@property (nonatomic,readonly,nonnull) NSString *sdkVersion;

3. 接入示例

具体接入示例,请参考 demo 工程。

4. 识别结果处理

SDK 入口方法提供了三个回调 block:startSucceed、recognizeSucceed 和 failed ,通过这几个 block 来捕获识别结果或者异常状况。

4.1 startSucceed(成功进入 SDK 回调)

进入这个回调,说明当前用户已经通过 SDK 鉴权,应用成功进入 SDK 界面了。

4.2 recognizeSucceed(识别成功,即将退出 SDK 回调)

进入这个回调,说明 SDK 已经识别成功,即将退出,回到 App 中的界面,这里面有两个参数 resultModel 和 extension。

  • resultModel 是对识别结果的封装,如果当前识别的是身份证,就会返回一个 WBIDCardInfoModel 类型的实例;如果当前识别的是银行卡,返回的是一个 WBBankCardInfoModel 类型的实例。关于每个字段的详细含义,请参考 WBOCRService.h 头文件。
  • extension 是一个扩展字段,备用,目前版本为空,不需要处理。

4.3 failed(SDK 异常,即将退出 SDK 回调)

进入这个回调,说明 SDK 发生异常,SDK 即将退出,可以通过这个回调获取失败信息,这里面有两个参数 error 和 extension。

  • error 是一个 NSError 类型的实例,里面会封装错误码和错误描述,下面代码展示了一条错误码为200101的 error 信息,具体的错误码对照表请参考 OCR iOS 错误码 文档。
    NSError *error = [NSError errorWithDomain:@"com.webank.ocr.error" code:200101 userInfo:@{NSLocalizedDescriptionKey:@"用户取消操作"}];
  • extension 是一个扩展字段,备用,目前版本为空,不需要处理。