接入文档

接口调用

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

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; //签名信息
注意:

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

EXBankCardResult 代表 SDK 返回的识别银行卡的结果,该类属性如下所示:

public String ocrId;//识别的唯一标识
public String bankcardNo;//识别的银行卡号
public String bankcardValidDate;//识别的银行卡的有效期
public String orderNo;//订单号
public String warningMsg;   //识别的警告信息
public String warningCode;  //识别的警告码
public Bitmap bankcardNoPhoto;//识别的银行卡的卡号图片

登录回调接口

/**
  * 登录回调接口
  */
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);
}

银行卡识别结果类

银行卡识别结果封装在 EXBankCardResult 类中,通过WbCloudOcrSDK.getInstance().getBankCardResult()获得,该类属性如下所示:

public String ocrId;//ocrId
public String bankcardNo;//卡号
public String bankcardValidDate;//有效期
public String orderNo;//订单号
public String warningMsg;//告警信息
public String warningCode;//告警码
public Bitmap bankcardNoPhoto; //卡号切边图
public String bankcardFullPhoto;//银行卡图片存放路径

接口参数说明

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. WBOCRSDKTypeBankSide 
     * @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);
}

银行卡识别结果类

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

public String ocrId;//ocrId
public String bankcardNo;//卡号
public String bankcardValidDate;//有效期
public String orderNo;//订单号
public String warningMsg;//告警信息
public String warningCode;//告警码
public Bitmap bankcardNoPhoto; //卡号切边图
public String bankcardFullPhoto;//银行卡图片存放路径

个性化参数设置

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

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

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

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

个性化设置接入示例

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundle 中
  data.putSerializable(WbCloudOcrSDK.INPUT_DATA, inputData);
  //设置扫描识别的时间上限,默认 20 秒,此处设置为 20 秒
  data.putLong(WbCloudOcrSDK.SCAN_TIME, 20000);
目录