接口调用

最近更新时间:2019-07-09 14:49:22

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);
}
  • WbCloudOcrSdk.init() 的第二个参数用来传递数据.可以将参数打包到 data(Bundle) 中,必须传递的参数包括:
//这些都是WbCloudOcrSdk.InputData对象里的字段,是需要传入的数据信息
String orderNo;  //订单号
String clientIp; //用户 ip 信息,格式为”ip=xxx.xxx.xxx.xxx;”
                          // 示例:”ip=58.60.124.0”
String gps; //用户 gps 信息, 格式为”lgt=xxx;lat=xxx;”
                  //示例:“lgt=22.5044;lat=113.9537“
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 sign;//签名
public  String orderNo; //订单号
public String ocrId;//识别的唯一标识

接口参数说明

InputData 是用来给 SDK 传递一些必须参数所需要使用的对象(WbCloudOcrSdk.init() 的第二个参数),合作方需要往里塞入 SDK 需要的一些数据以便启动 OCR SDK。
其中 InputData 对象中的各个参数定义如下表,请合作方按下表标准传入对应的数据。

参数 说明 类型 长度 是否必填
orderNo 订单号,合作方订单的唯一标识 String 32
openApiAppId 腾讯服务分配的app_id String 由腾讯服务分配
openApiAppVersion 接口版本号,默认填 1.0.0 String 20
openApiNonce 32位随机字符串,每次请求需要的一次性 nonce String 32
openApiUserId User Id,每个用户唯一的标识 String 30
openApiSign 合作方后台服务器通过 ticket 计算出来的签名信息 String 40
clientIp 用户 IP 信息
格式:“ip=xxx.xxx.xxx.xxx;”
示例:“ip=58.60.124.0”
String 30
gps 用户 GPS 信息
格式:“lgt=xxx;lat=xxx;”
示例:“gt=22.5044;lat=113.9537”
String 30

个性化参数设置

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);