接入文档

接口调用

最近更新时间:2020-11-23 10:20:33

SDK 接口分为标准模式和自定义模式:

  • 标准模式:SDK 对接口进行封装并且实现了识别页面,合作方只需要调用接口,即可以快速拉起 SDK,接收结果回调。接入简单,适合快速接入。
  • 自定义模式:由合作方自定义识别页面送入相机识别数据到 SDK,SDK 返回每帧识别结果给回合作方。适合深度定制页面需求。

标准模式 SDK 接口调用方法

  • SDK 代码调用的入口为 com.webank.mbank.ocr.WbCloudOcrSDK
public class WbCloudOcrSDK{

/**
* 该类为一个单例,需要先获得单例对象再进行后续操作
   */
       public static synchronized WbCloudOcrSDK getInstance() {
       //    ...
       }
/**
* 在使用SDK前先初始化,传入需要的数据data
*由 OcrLoginListener返回是否登录SDK成功
* 关于传入数据data见后面的说明
*/
public void init(Context context,Bundle data,OcrLoginListener loginListerner){
//    ...
}
   /**
     * 登录成功后,调用此函数拉起sdk页面
     * @param context                  拉起SDK的上下文
     * @param idCardScanResultListener 返回到第三方的接口
     * @param type                     进入SDK的模式,参数是枚举类型
     */
    Public void startActivityForOcr(Context context,IDCardScanResultListener,WBOCRTYPEMODE type){
    // ...
 }
/**
  * 登录回调接口
  */
public interface OcrLoginListener {
        void onLoginSuccess();
        void onLoginFailed(String errorCode, String errorMsg);
    }

/**
  * 退出SDK,返回第三方的回调,同时返回ocr识别结果
  */
public interface IDCardScanResultListener{
        /**
         * @RARAM exidCardResult   SDK返回的识别结果的错误码  
* @RARAM exidCardResult   SDK返回的识别结果的错误信息    
         */
        void onFinish(String errorCode, String errorMsg);
}
  • NONCE 类型的 ticket,其有效期为120秒,且一次性有效,即每次启动 SDK 刷脸都要重新请求 NONCE ticket,重新算 sign。同时建议合作方做前端保护,防止用户连续点击,短时间内频繁启动 SDK。
  • WbCloudOcrSdk.init() 的第二个参数用来传递数据.可以将参数打包到 data(Bundle) 中,必须传递的参数包括:
//这些都是WbCloudOcrSdk.InputData对象里的字段,是需要传入的数据信息
String orderNo;  //订单号
String openApiAppId;  //APP_ID 
String openApiAppVersion;  //openapi  Version
String openApiNonce; //32位随机字符串
String openApiUserId; //user id
String openApiSign; //签名信息

以上参数被封装在 WbCloudOcrSdk.InputData 对象中(它是一个 Serializable 对象)。

  • WbCloudOcrSdk.startActivityForOcr() 的第三个参数 type 是个枚举类 WBOCRTYPEMODE,决定第三方登录成功后以哪种模式进行身份证识别。
/**
  * 调OCR 的模式
  */
public enum WBOCRTYPEMODE {
WBOCRSDKTypeNormal,//标准模式,先进入准备界面再进入扫描身份证界面
WBOCRSDKTypeFrontSide,//人像面模式,直接进入身份证人像面识别
WBOCRSDKTypeBackSide,//国徽面模式,直接进入身份证国徽面识别
}
  • 登录接口
/**
  * 登录回调接口
  */
public interface OcrLoginListener {
        void onLoginSuccess();//登录成功
          /**
           * @PARAM errorCode 登录失败错误码
           * @PARAM errorMsg  登录失败错误信息
           */        
         void onLoginFailed(String errorCode, String errorMsg);
    }
  • 返回第三方接口
/**
  * 退出SDK,返回第三方的回调,同时返回ocr识别结果
  */
public interface IDCardScanResultListener{
        /**
         * 退出SDK,返回第三方的回调,同时返回ocr识别结果
         * @param errorCode        返回错误码,识别成功返回 0
         * @param errorMsg        返回错误信息,和错误码相关联         */
        void onFinish(String errorCode, String errorMsg);
}

身份证识别结果类

身份证识别结果, 封装在 EXIDCardResult 类中,通过 WbCloudOcrSDK.getInstance().getResultReturn() 获得,该类属性如下所示:

public int type;//拉起SDK的模式所对应的int 值,也就是startActivityForOcr 方法中WBOCRTYPEMODE type的枚举值value
    // 识别人像面返回的信息
    public String cardNum;  //身份证号码
    public String name;//姓名
    public String sex;//性别
    public String address;//住址
    public String nation;//民族
    public String birth;//出生年月日
    public String frontFullImageSrc;// 人像面图片存放路径
public String frontWarning;//人像面告警码


    //识别国徽面返回的信息
    public String office;//签发机关
    public String validDate;//有效期限
    public String backFullImageSrc;//国徽面图片存放路径
public String backWarning;//国徽面告警码

//每次网络请求都会返回的信息
public String multiwarning;//多重告警码
public String clarity;//清晰度得分
public String sign;//签名
public  String orderNo; //订单号
public String ocrId;//识别的唯一标识

接口参数说明

NONCE 类型的 ticket,其有效期为120秒,且一次性有效,即每次启动 SDK 刷脸都要重新请求 NONCE ticket,重新算 sign。同时建议合作方做前端保护,防止用户连续点击,短时间内频繁启动 SDK。
InputData 是用来给 SDK 传递一些必须参数所需要使用的对象(WbCloudOcrSdk.init() 的第二个参数),合作方需要往里塞入 SDK 需要的一些数据以便启动 OCR SDK。
其中 InputData 对象中的各个参数定义如下表,请合作方按下表标准传入对应的数据。

参数 说明 类型 长度 是否必填
orderNo 订单号,合作方订单的唯一标识 String 32
openApiAppId 腾讯服务分配的 app_id String 由腾讯服务分配
openApiAppVersion 接口版本号,默认填 1.0.0 String 20
openApiNonce 与服务端生成签名的随机数保持一致 String 32
openApiUserId User Id,每个用户唯一的标识 String 30
openApiSign 合作方后台服务器通过 ticket 计算出来的签名信息 String 40

自定义模式 SDK 接口调用方法

SDK 代码调用的入口为com.webank.mbank.ocr. WbCloudOcrSimpleSDK这个类。

public class WbCloudOcrSimpleSDK {

/**
* 该类为一个单例,需要先获得单例对象再进行后续操作
   */
       public static synchronized WbCloudOcrSimpleSDK getInstance() {
       //    ...
       }

/**
     * 初始化自定义识别模式Ocr SDK
     * @param context 必填,上下文
     * @param orderNo 必填,订单号,32位字符串,合作方订单的唯一标识
     * @param appId   必填,腾讯服务分配的 app_id
     * @param version 必填,默认填 1.0.0
     * @param nonce   必填,每次请求需要的一次性 nonce,32位随机字符串
     * @param userId  必填,每个用户唯一的标识
     * @param sign    必填,合作方后台服务器通过 ticket 计算出来的签名信息
     * @param simpleOcrLoginResult  初始化自定义识别模式ocr结果回调
     */
    public void init(Context context, String orderNo, String appId, String version, String nonce, String userId, String sign
          , WbCloudSimpleOcrLoginResult simpleOcrLoginResult) { 
//    ...
}

/**
     * 登录成功后,调用此函数对相机数据流进行识别,用户可自定义UI,通过回调返回识别结果
     *
     * @param data   相机流
     * @param isPortrait    识别界面是否竖屏
     * @param previewWidth     预览画面宽度
     * @param previewHeight    预览画面高度
     * @param type   待识别的数据类型,枚举类
    * 人像面模式:WbCloudOcrSDK.WBOCRTYPEMODE.WBOCRSDKTypeFrontSide
    * 国徽面模式:WbCloudOcrSDK.WBOCRTYPEMODE.WBOCRSDKTypeBackSide 
     * @param rect                     识别区域
     * @param progressListener          进程回调
     * @param warningListener           警告回调
     * @param recognizedResultListener 识别结果回调
     */ 
public void startRecoginizeSampleBuffer(
byte[] data, 
boolean isPortrait, 
int previewWidth, 
final int previewHeight,
WbCloudOcrSDK.WBOCRTYPEMODE type,
Rect rect,
    WbCloudSimpleOcrProgressListener progressListener,
    WbCloudSimpleOcrWarningListener warningListener,
    WbCloudOcrRecognizedResultListener recognizedResultListener) {
    // ...
 }

/**
  * 自定义识别模式登录回调接口
  */
public interface WbCloudSimpleOcrLoginResult {
    void onLoginSuccess();
    void onLoginFailed(String errorCode, String errorMsg);
}

/**
 * 当前帧的识别效果回调
 * 用于提示用户信息,帮助调整证件
 */
public interface WbCloudSimpleOcrProgressListener {
    /**
     * 
     * @param isClear   当前帧是否清晰
     * @param hasBorder  当前帧是否检测到证件边框
     * @param getCloser   当前帧是否需要距离相机镜头更靠近一点
     */
    void onRecognizingProcess(boolean isClear, boolean hasBorder, boolean getCloser);
}

/**
 * 当前帧识别的警告结果回调
 * 用于提示用户操作
 */
public interface WbCloudSimpleOcrWarningListener {
    void onWarning(WbCloudOcrError error);
}

/**
 * 当前帧识别结果回调
 * 识别结果
 */
public interface WbCloudOcrRecognizedResultListener {
    /**
     * 
     * @param isSuccess  是否识别成功
     * @param error      如果识别失败,返回错误原因对象
     * @param recoResult  如果识别成功,返回识别结果对象
     */
    void onFinish(boolean isSuccess, WbCloudOcrError error, Object recoResult);
}

登录接口

/**
  * 自定义识别模式登录回调接口
  */
public interface WbCloudSimpleOcrLoginResult {
void onLoginSuccess();
    /**
           * @PARAM errorCode 登录失败错误码
           * @PARAM errorMsg  登录失败错误信息
       */
    void onLoginFailed(String errorCode, String errorMsg);
}

### 返回第三方接口
/**
 * 当前帧的识别效果回调
 * 用于提示用户信息,帮助调整证件
 */
public interface WbCloudSimpleOcrProgressListener {
    /**
     * 
     * @param isClear   当前帧是否清晰
     * @param hasBorder  当前帧是否检测到证件边框
     * @param getCloser   当前帧是否需要距离相机镜头更靠近一点
     */
    void onRecognizingProcess(boolean isClear, boolean hasBorder, boolean getCloser);
}

/**
 * 当前帧识别的警告结果回调
 * 用于提示用户操作
 */
public interface WbCloudSimpleOcrWarningListener {
    void onWarning(WbCloudOcrError error);
}

/**
 * 当前帧识别结果回调
 * 识别结果
 */
public interface WbCloudOcrRecognizedResultListener {
    /**
     * 
     * @param isSuccess  是否识别成功
     * @param error      如果识别失败,返回错误原因对象
     * @param recoResult  如果识别成功,返回识别结果对象
     */
    void onFinish(boolean isSuccess, WbCloudOcrError error, Object recoResult);
}

身份证识别结果类

身份证识别结果, 封装在 EXIDCardResult 类中,通过 WbCloudOcrRecognizedResultListener 回调,当 isSuccess 为 true 时由 Object recoResult 可获得,该类属性如下所示:

public int type;//拉起 SDK 的模式所对应的 int 值,也就是 WBOCRTYPEMODE type 的枚举值 value
    // 识别人像面返回的信息
    public String cardNum;  //身份证号码
    public String name;//姓名
    public String sex;//性别
    public String address;//住址
    public String nation;//民族
    public String birth;//出生年月日
    public String frontFullImageSrc;// 人像面图片存放路径
public String frontWarning;//人像面告警码


    //识别国徽面返回的信息
    public String office;//签发机关
    public String validDate;//有效期限
    public String backFullImageSrc;//国徽面图片存放路径
public String backWarning;//国徽面告警码

//每次网络请求都会返回的信息
public String multiWarning;//多重告警码
   public String clarity;//清晰度得分
   public String sign;//签名
  public  String orderNo; //订单号
  public String ocrId;//识别的唯一标识

个性化参数设置

WbCloudOcrSdk.init() 里 Bundle data,除了必须要传的 InputData 对象之外,还可以由合作方传入一些个性化参数,量身打造更契合自己 App 的 SDK。如果合作方未设置这些参数,则以下所有参数按默认值设置。

设置 SDK 的界面标题栏背景色

合作方可以设置进入 SDK 的准备界面的标题栏背景色(仅对标准模式此设置才有效)。SDK 默认显示准备界面的标题栏背景颜色是白色 (#ffffff),但第三方可对其个性化设置。设置代码如下:

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundle 中
  data.putSerializable(WbCloudFaceVerifySdk.INPUT_DATA, inputData);
  //设置标题栏背景色,如果不设置则默认展示;设置了则以设置为准
  //此处设置进入 SDK 的第一个界面的标题栏背景色为蓝色(#409eff)
  data.putString(WbCloudOcrSDK.TITLE_BAR_COLOR, "#409eff");

设置 SDK 的界面标题栏内容

合作方可以设置进入 SDK 的准备界面的标题栏文字内容(仅对标准模式此设置才有效)。SDK 默认显示第一个界面的标题栏文字内容是身份证识别,但第三方可对其个性化设置。设置代码如下:

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData放入 Bundle 中
  data.putSerializable(WbCloudFaceVerifySdk.INPUT_DATA, inputData);
  //设置标题栏文字内容,如果不设置则默认展示;设置了则以设置为准
  //此处设置进入 SDK 的第一个界面的标题栏文字内容为居民身份证识别
   data.putString(WbCloudOcrSDK.TITLE_BAR_CONTENT, "居民身份证识别");

设置 SDK 的水印文字内容

合作方可以设置进入 SDK 的第一个界面上的水印文字内容。 SDK 默认显示第一个界面的水印文字内容是仅供内部业务使用,但第三方可对其个性化设置。设置时需要注意:水印文字长度不超过8个,且只支持汉字,若长度超过8个,SDK 会自动截取前8个汉字。设置代码如下:

# 在MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放 入Bundle 中
  data.putSerializable(WbCloudFaceVerifySdk.INPUT_DATA, inputData);
  //设置水印文字内容,如果不设置则默认展示;设置了则以设置为准
  //此处设置进入 SDK 的第一个界面的水印文字内容为仅供本次业务使用 
  data.putString(WbCloudOcrSDK.WATER_MASK_TEXT, "仅供本次业务使用");

设置 SDK 的扫描识别的时间上限

合作方可以设置 SDK 的扫描识别时间的上限。 SDK 打开照相机进行扫描识别的时间上限默认是20秒,20秒内若扫描识别成功则返回到 SDK 的第一个界面,否则直到20秒直接退出扫描界面。第三方可对其个性化设置,设置的时间上限不能超过60秒,建议第三方采用默认值,不要修改这个参数。设置代码如下:

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundle 中
  data.putSerializable(WbCloudFaceVerifySdk.INPUT_DATA, inputData);
  //设置 SDK 扫描识别身份证的时间上限,如果不设置则默认 20 秒;设置了则以设置为准
  //此处设置 SDK 的扫描识别时间的上限为 20 秒
   data.putLong(WbCloudOcrSDK.SCAN_TIME, 20000);

设置 SDK 识别是否校验身份证正反面

合作方可以设置 SDK 是否校验正反面都识别成功,此设置只适用于标准模式。

  • 标准模式下传“2”则会对身份证正反面识别进行强校验,即正反面都识别成功才能单击【完成】。
  • 传或传其他则默认不会对身份证正反面识别进行强校验。
    设置代码如下:
    在 MainActivity 中单击某个按钮的代码逻辑:
    //先将必填的 InputData 放入 Bundle 中
    data.putSerializable(WbCloudFaceVerifySdk.INPUT_DATA, inputData);
    //设置 SDK 是否校验身份证正反面都识别成功,如果不设置则默认不校验;设置了则以设置为准
    //此处设置 SDK在标准模式下对身份证人像面、国徽面识别进行强校验
    OCR_FLAG参数值为 “1”、null 时,人像面必须识别,国徽面可选识别 
    OCR_FLAG参数值为 “2” 时,人像面、国徽面都必须识别)
    data.putString(WbCloudOcrSDK.OCR_FLAG, "2");

个性化设置接入示例

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundle 中
  data.putSerializable(WbCloudOcrSDK.INPUT_DATA, inputData);
  //个性化参数设置,此处均设置为与默认不同
  //设置 SDK 标题栏背景颜色,默认白色,此处设置为蓝色(仅对标准模式有效)  data.putString(WbCloudOcrSDK.TITLE_BAR_COLOR, "#409eff");
  //设置 SDK 标题栏文字内容,默认展示身份证识别,此处设置为居民身份证识别(仅对标准模式有效)   
data.putString(WbCloudOcrSDK.TITLE_BAR_CONTENT, "居民身份证识别");
  //设置 SDK 水印文字内容,默认仅供内部业务使用,此处设置为仅供本次业务使用(仅对标准模式有效)
  data.putString(WbCloudOcrSDK.WATER_MASK_TEXT, "仅供本次业务使用");
  //设置扫描识别的时间上限,默认 20 秒,此处设置为 20 秒
  data.putLong(WbCloudOcrSDK.SCAN_TIME, 20000);
目录