调用接口

最近更新时间:2019-07-26 15:18:52

调用详情参见 Demo 工程以及头文件 WBOCRService.h

1. 在使用 OCR SDK 的类中引入 WBOCRService.h

#import <WBOCRService/WBOCRService.h>

@interface ViewController ()

// TODO:

@end

2. 实例化 SDK

WBOCRService 是一个单例类 ,通过如下方法来实例化这个类:

#import <WBOCRService/WBOCRService.h>

3. 启动 OCR SDK 服务

实例化 WBOCRService 后,调用 start 方法启动 SDK,start 方法的头文件声明如下:

- (void)startOCRServiceWithConfig:(nullable WBOCRConfig *)config
                        version:(nonnull NSString *)version
                          appId:(nonnull NSString *)appId
                          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;
  • start 方法参数说明:

    • config 是一个配置参数,nullable,用来对 SDK 做一些配置,详情请参见后文的 config 参数。
    • version 表示 webank OpenAPI 的版本号,由腾讯服务分配,没有特别说明请输入1.0.0。
    • appId 腾讯服务分配的 app_id。
    • nonce SDK 鉴权用参数,一次性有效。
    • userId 表示每个用户唯一的标识,由腾讯服务分配。
    • sign SDK 鉴权用参数,从接入方后台获取。
    • orderNo 订单号,这个参数用来查询识别结果用,接入方必须保证这个参数的唯一性,该参数长度不得超过32位,订单号中尽量不要包含特殊字符。
    • startSucceed SDK 启动成功回调,当用户鉴权通过的时候会走到这个回调。
    • recognizeSucceed SDK 识别成功回调,可以通过这个回调来获取识别结果信息。
    • failed SDK 发生异常,退出时候的回调,可以通过这个回调获取失败信息。
  • config 参数说明(“身份证 / 银行卡识别”的配置参数)
    config 是个 WBOCRConfig 实例,通过 WBOCRConfig * config = [WBOCRConfig sharedConfig]来实例化,其中部分参数需要着重关注:

    • SDKType 参数决定本次使用的 OCR 服务类型,SDK 目前提供身份证人像面识别、身份证国徽面识别、身份证两面识别和银行卡识别四种类型的服务,例如用户可以通过 config.SDKType = WBOCRSDKTypeIDCardFrontSide;来选择使用身份证人像面识别服务。

      • WBOCRSDKTypeNoraml:标准模式,SDK 调起成功后,先进入拍摄准备页面,待正反两面识别完成之后,将本次识别结果返回到第三方 App。
      • WBOCRSDKTypeFontSide:人像面识别模式,SDK 调起成功后,直接进入拍摄识别页面,识别身份证人像面,识别完成之后,将本次识别结果返回第三方 App。
      • WBOCRSDKTypeBackSide:国徽面识别模式,SDK 调起成功后,直接进入拍摄识别页面,识别身份证国徽面,识别完成之后,将本次识别结果返回第三方 App。
      • WBOCRSDKTypeBankCard:银行卡识别模型。
    • needBothSidesRecognized,只有当上面的 SDKType 参数选择的是 WBOCRSDKTypeIDCardNormal 的时候, needBothSidesRecognized 参数才起作用,它的功能是控制 SDK 识别完成的逻辑。

      • 当 needBothSidesRecognized 参数为 YES 的时候,用户需要全部完成人像面和国徽面识别后,才能单击 “成功退出 SDK ”。
      • 当 needBothSidesRecognized 参数为 NO 的时候,用户仅需要完成人像面识别,就可以 “成功退出 SDK”。
        这里 “成功退出 SDK” 的含义,是指 SDK 通过 recognizeSucceed 回调退出。
    • config 里面还有很多 readonly 参数,这些参数和本次识别相关,开发者可以按需在这些接口获取。

4. 处理 SDK 的回调信息

开发者通过 start 方法的 startSucceed、recognizeSucceed 和 failed 三个 block 来接收 SDK 回调信息。

  • startSucceed(成功进入 SDK 回调)
    进入这个回调,说明当前用户已经通过 SDK 鉴权,应用成功进入 SDK 界面了。
  • recognizeSucceed(识别成功,即将退出 SDK 回调)
    进入这个回调,说明 SDK 已经识别成功,即将退出,回到 App 中的界面,这里面有两个参数 resultModel 和 extension。
    • resultModel 是对识别结果的封装,如果当前识别的是身份证,就会返回一个 WBIDCardInfoModel 类型的实例;如果当前识别的是银行卡,返回的是一个 WBBankCardInfoModel 类型的实例。关于每个字段的详细含义,请参考 WBOCRService.h 头文件。
    • extension 是一个扩展字段,备用,目前版本为空,不需要处理。
  • failed(SDK 异常,即将退出 SDK 回调)
    进入这个回调,说明 SDK 发生异常,SDK 即将退出,可以通过这个回调获取失败信息,这里面有两个参数 error 和 extension。
    • error 是一个 NSError 类型的实例,里面会封装错误码和错误描述,下面代码展示了一条错误码为 200101 的 error 信息,详情请参见 错误码描述
      NSError *error = [NSError errorWithDomain:@"com.webank.ocr.error" code:200101 userInfo:@{NSLocalizedDescriptionKey:@"用户取消操作"}];
    • extension 是一个扩展字段,备用,目前版本为空,不需要处理。