接入文档

接口调用

最近更新时间:2020-09-21 15:56:54

SDK 接口调用方法

SDK 代码调用的入口为 WbCloudFaceVerifySdk 这个类。

public class WbCloudFaceVerifySdk {

/**
* 该类为一个单例,需要先获得单例对象再进行后续操作
   */
public static WbCloudFaceVerifySdk getInstance(){
//    ...
}
/**
* 在使用 SDK 前先初始化,传入需要的数据 data
*(适用于权威数据源比对和自带对比源比对 模式)
* 由 WbCloudFaceVerifyLoginListener 返回是否登录 SDK 成功
* 关于传入数据 data 见后面的说明
*/
public void initSdk(Context context,Bundle data,
WbCloudFaceVerifyLoginListener loginListerner){
//    ...
}

/**
* 在使用 SDK 前先初始化,传入需要的数据 data(适用于仅活体比对模式)
* 由 WbCloudFaceVerifyLoginListener 返回是否登录 SDK 成功
* 关于传入数据 data 见后面的说明
*/
public void init(Context context,Bundle data,
WbCloudFaceVerifyLoginListener loginListerner){
//    ...
}
    /**
     * 登录成功后,调用此函数拉起 sdk 页面。
     * 由 FaceVerifyResultForSecureListener 返回刷脸结果。
     */
public void startWbFaceVerifySdk(Context ctx,
WbCloudFaceVerifyResultListener listener) {    // ...
}

WbCloudFaceVerifySdk.initSdk()的第二个参数用来传递数据,可以将参数打包到data(Bundle)中,必须传递的参数包括以下内容(参数详情请参见 接口参数说明):

//这些都是 WbCloudFaceVerifySdk.InputData 对象里的字段,是需要传入的数据信息
String faceId;  //此次刷脸用户标识,合作方需要向人脸识别后台拉取获得,详见获取 faceId 接口
String agreementNo;  //订单号
String openApiAppId;  //APP_ID 
String openApiAppVersion;  //openapi  Version
String openApiNonce; //32位随机字符串
String openApiUserId; //user id
String openApiSign; //签名信息

//刷脸类别:光线活体 FaceVerifyStatus.Mode.REFLECTION
//         动作活体 FaceVerifyStatus.Mode.ACT
FaceVerifyStatus.Mode verifyMode;
String keyLicence;   //给合作方派发的licence
注意:

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

SDK 结果分别由以下两个回调返回:

/**
  * 登录回调接口  返回登录 sdk 是否成功
  */
public interface WbCloudFaceVerifyLoginListener {
        void onLoginSuccess();
        void onLoginFailed(WbFaceError error);
    }

/**
  * 刷脸结果回调接口
  */
public interface WbCloudFaceVerifyResultListener {
        void onFinish(WbFaceVerifyResult result);

接口参数说明

InputData 对象说明

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

参数 说明 类型 长度(字节) 是否必填
faceId 刷脸 ID 号,由合作方向人脸识别后台拉取获得 String -
agreementNo 订单号,合作方订单的唯一标识 String 32
openApiAppId 腾讯云线下对接分配的 AppID String 腾讯云线下对接决定
openApiAppVersion 接口版本号,默认填:1.0.0 String 20
openApiNonce 与服务端生成签名的随机数保持一致 String 32
openApiUserId User Id,每个用户唯一的标识 String 30
openApiSign 合作方后台服务器通过 ticket 计算出来的签名信息 String 40
verifyMode 人脸核身类型
光线活体:FaceVerifyStatus.Mode.REFLECTION
动作活体是:FaceVerifyStatus.Mode.ACT
FaceVerifyStatus.Mode -
keyLicence 腾讯云线下对接分配的 Licence String 腾讯云线下对接决定

WbFaceVerifyResult 对象说明

WbFaceVerifyResult 是 SDK 用来给合作方传递身份识别结果的对象,在 WbCloudFaceVerifyResultListener 回调中作为参数返回给合作方 App。WbFaceVerifyResult 对象的各个字段意义如下表所示:

字段名 类型 字段含义 说明
isSuccess boolean 人脸核身是否成功 -
sign String 签名 供 App 校验人脸核身结果的安全性
liveRate String 活体检测分数 -
similarity String 人脸比对分数 “仅活体检测” 类型不提供此分数
userImageString String 用户人脸核身图片 经过 Base64 编码后的用户人脸核身图片,仅用户成功通过验证时返回
WbFaceError 自定义对象 人脸核身错误 人脸核身成功时为 null

WbFaceError 对象说明

WbFaceError 是 SDK 用来给合作方传递人脸核身错误信息的对象,在 WbCloudFaceVerifyLoginListener 回调和 WbFaceVerifyResult 对象中作为参数返回给合作方 App。WbFaceError 对象的各个字段意义如下表所示,各个字段的内容取值详情请参见 错误码

字段名 类型 字段含义 说明
domain String 错误发生的阶段 -
code String 错误码 -
desc String 错误描述 如有需求,可以展示给用户
reason String 错误信息内容 错误的详细实际原因,主要用于定位问题

接入示例

详情请参见 Android 光线活体 + 人脸比对 接入示例

个性化参数设置(可选)

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

是否显示人脸核身成功页面

合作方可以控制是否显示 SDK 自带的人脸核身成功页面。 SDK 默认显示人脸核身成功页面,但第三方可以关闭不显示,直接回到自己的业务场景或者自定义的成功页面。设置代码如下:

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的InputData放入Bundle中
  data.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);
  //是否展示刷脸成功页面,如果不设置则默认展示;设置了则以设置为准
  //此处设置为不显示刷脸成功页
  data.putBoolean(WbCloudFaceContant.SHOW_SUCCESS_PAGE, false);

是否显示人脸核身失败原因页

合作方可以控制是否显示 SDK 自带的人脸核身失败原因页。SDK 默认显示人脸核身失败原因页,但第三方可以关闭显示,直接回到自己的业务场景或者自定义的失败页面。设置代码如下:

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundle 中
  data.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);
  //是否展示刷脸失败原因页,如果不设置则默认展示;设置了则以设置为准
  //此处设置为不显示刷脸成功页
  data.putBoolean(WbCloudFaceContant.SHOW_FAIL_PAGE, false);

SDK 样式选择

合作方可以选择 SDK 样式。目前 SDK 有黑色模式和白色模式两种,默认显示黑色模式。设置代码如下:

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundle中
  data.putSerializable((WbCloudFaceContant.INPUT_DATA, inputData);
  //对 sdk 样式进行设置,默认为黑色模式
  //此处设置为白色模式
  data.putString(WbCloudFaceContant.COLOR_MODE, WbCloudFaceContant.WHITE);

合作方个性化提示定制

合作方可以设置定制的提示语,通过配置传给 SDK,可以配置人脸识别时的提示语及上传人脸信息时的提示语,如果不设置,默认无。
合作方还可以对自定义提示语的位置进行设置,默认是在识别框下方,如有需求也可以设置到上方。
设置代码如下:

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundle中
 data.putSerializable((WbCloudFaceContant.INPUT_DATA, inputData);
 //定制合作方个性化提示语
//此处将设置人脸采集时的个性化提示语
data.putString(WbCloudFaceContant.CUSTOMER_TIPS_LIVE, “扫描人脸后与您身份证进行对比”);  
//此处将设置上传人脸时的个性化提示语
data.putString(WbCloudFaceContant. CUSTOMER_TIPS_UPLOAD, “已提交审核,请等待结果”);  
//设置合作方定制提示语的位置,默认为识别框的下方
 //识别框的下方: WbCloudFaceContant.CUSTOMER_TIPS_LOC_BOTTOM
 //识别框的上方:WbCloudFaceContant.CUSTOMER_TIPS_LOC_TOP
data.putInt(WbCloudFaceContant.CUSTOMER_TIPS_LOC,WbCloudFaceContant.CUSTOMER_TIPS_LOC_TOP);

比对类型选择

SDK 提供权威数据源比对、自带比对源比对,合作方可以选择传入参数控制对比类型。

  • 权威数据源比对
    合作方必须要先在获 取 faceId 的接口里送入用户的姓名与身份证号信息,得到相应的 faceId 后,再送入 SDK,供 SDK 与权威数据源进行比对,设置代码如下:

    注意:

    SDK 默认类型为权威数据源比对,不需要额外设置。

    # 在 MainActivity 中单击某个按钮的代码逻辑:
    //先将必填的 InputData 放入 Bundle 中
    //权威数据源比对必须输入相应的 faceId
    data.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);
    //设置选择的比对类型  权威数据源对比(无需格外设置,默认选项)
    data.putString(WbCloudFaceContant.COMPARE_TYPE, WbCloudFaceContant.ID_CARD);
  • 自带比对源比对

    • 合作方在获取 faceId 的接口里送上对比源数据,获取 faceId 后送入 sdk 进行对比,可以上送网纹照或者高清照。
    • 照片需要经过 Base64 编码后,转化为 String 来上送。
    • 图片大小不可超过2MB,经过编码后的图片 String 大小不可超过3MB。
    • 上送照片类型与上送照片 String 两者缺一不可,否则将不使用上送的数据源。

    上送的代码设置如下:

    # 在 MainActivity 中单击某个按钮的代码逻辑:
    //先将必填的 InputData 放入 Bundle 中
    //自带对比源对比需要输入相应的 faceId
    data.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);
    //设置选择的比对类型  自带比对源比对
    data.putString(WbCloudFaceContant.COMPARE_TYPE, WbCloudFaceContant.SRC_IMG); 

是否录制视频存证

SDK 为了进一步确保人脸核身的安全性,默认会录制用户人脸核身视频做存证。如果合作方不需要录制视频存证,可以通过该字段进行设置,关闭 SDK 录制视频存证。设置代码如下:

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundle 中
  data.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);
  //设置是否录制视频进行存证,默认录制存证。
  //此处设置为不录制存证
  data.putBoolean(WbCloudFaceContant.VIDEO_UPLOAD, false);

是否对录制视频进行检查

说明:

如果在 “是否录制视频存证” 步骤的设置为录制存证,则目前该字段有效;否则,设置为不录制存证,也不会对视频进行检查,设置无效。

  • SDK 为了进一步确保人脸核身的安全性,不论是简单还是中级模式都有录制用户人脸核身视频做存证。但其实在简单/中级模式中,起到识别作用的并不是视频文件。在 SDK 使用过程中,视频录制在性能不太好的手机上可能会报错,导致人脸核身中断,影响用户体验。
  • 为了减少录制视频导致的人脸核身中断问题,SDK 默认设置对录制的视频不作检测。
  • 如果合作方对人脸核身安全有更加严格的要求,可以考虑打开这一选项。但打开这个字段可能导致某些低性能手机上用户人脸核身不能进行,请慎重考虑。设置代码如下:
# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundle 中
  data.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);
  //设置是否对录制的视频进行检测,默认不检测
  //此处设置为检测
  data.putBoolean(WbCloudFaceContant.VIDEO_CHECK, true);

是否开启闭眼检测

SDK 预检测期间提供闭眼检测功能,默认关闭。合作方可以根据自身需求选择是否开启,设置代码如下:

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundle 中
  data.putSerializable(WbCloudFaceVerifySdk.INPUT_DATA, inputData);
  //设置是否打开闭眼检测,默认不检测
  //此处设置为检测
  data.putBoolean(WbCloudFaceContant.ENABLE_CLOSE_EYES, true);

是否播放语音提示

SDK 默认打开语音提示。合作方可以根据自身需求选择是否关闭,设置代码如下:

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundle 中
  data.putSerializable(WbCloudFaceVerifySdk.INPUT_DATA, inputData);
  //设置是否打开语音提示,默认打开
  //此处设置为关闭
  data.putBoolean(WbCloudFaceContant. PLAY_VOICE, false);

个性化设置接入示例

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundle 中
  data.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);
  //个性化参数设置,此处均设置为与默认相反
  //是否显示成功结果页,默认显示,此处设置为不显示
  data.putBoolean(WbCloudFaceContant.SHOW_SUCCESS_PAGE, false);
  //是否展示刷脸失败页面,默认展示,此处设置为不显示
  data.putBoolean(WbCloudFaceContant.SHOW_FAIL_PAGE, false);
//sdk样式设置,默认为黑色
//此处设置为白色
 data.putString(WbCloudFaceContant.COLOR_MODE, WbCloudFaceContant.WHITE);
    //定制合作方个性化提示语
  //此处将设置人脸采集时的个性化提示语
data.putString(WbCloudFaceContant.CUSTOMER_TIPS_LIVE, “扫描人脸后与您身份证进行对比”);  
//此处将设置上传人脸时的个性化提示语
data.putString(WbCloudFaceContant. CUSTOMER_TIPS_UPLOAD, “已提交审核,请等待结果”);  
//设置合作方定制提示语的位置,默认为识别框的下方
 //识别框的下方: WbCloudFaceContant.CUSTOMER_TIPS_LOC_BOTTOM
 //识别框的上方:WbCloudFaceContant.CUSTOMER_TIPS_LOC_TOP
//此处设置为识别框的上方
data.putInt(WbCloudFaceContant.CUSTOMER_TIPS_LOC,WbCloudFaceContant.CUSTOMER_TIPS_LOC_TOP);
//设置选择的比对类型  默认为权威数据源对比
//此处设置权威数据源比对
  data.putString(WbCloudFaceContant.COMPARE_TYPE, WbCloudFaceContant.ID_CARD);
//是否需要录制上传视频 默认需要,此处设置为不需要 
 data.putBoolean(WbCloudFaceContant.VIDEO_UPLOAD, false);
  //是否对录制视频进行检查,默认不检查,此处设置为检查
  data.putBoolean(WbCloudFaceContant.VIDEO_CHECK, false);
    //设置是否打开闭眼检测,默认不检测,此处设置为检测
  data.putBoolean(WbCloudFaceContant.ENABLE_CLOSE_EYES, true);
    //设置是否打开语音提示,默认打开,此处设置为关闭
  data.putBoolean(WbCloudFaceContant. PLAY_VOICE, false);
目录