接口调用

最近更新时间:2019-07-09 14:58:05

SDK 接口调用方法

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

public class WbCloudFaceVeirfySdk {

/**
* 该类为一个单例,需要先获得单例对象再进行后续操作
   */
public static WbCloudFaceVeirfySdk 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.init()的第二个参数用来传递数据,可以将参数打包到data(Bundle)中,必须传递的参数包括以下内容(参数详情请参见 接口参数说明):

//这些都是WbCloudFaceVerifySdk.InputData对象里的字段,是需要传入的数据信息
String faceId;  //此次刷脸用户标识,合作方需要向人脸识别后台拉取获得,详见获取faceId接口
String agreementNo;  //订单号
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; //签名信息

//刷脸类别:动作活体 FaceVerifyStatus.Mode.MIDDLE
//          数字活体 FaceVerifyStatus.Mode.ADVANCED
//          光线活体 FaceVerifyStatus.Mode.REFLECT
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.init()的第二个参数),合作方需要加入 SDK 需要的一些数据,以便启动人脸核身 SDK。InputData 对象中的各个参数定义如下表,请合作方按下表标准传入对应的数据。

参数 说明 类型 长度(字节) 是否必填
faceId 刷脸id号,由合作方向人脸识别后台拉取获得 String -
agreementNo 订单号,合作方订单的唯一标识 String 32
clientIp 用户 IP 信息
格式:“IP=xxx.xxx.xxx.xxx”
示例:“IP=58.60.124.0”
String 30
gps 用户 GPS 信息
格式:“lgt=xxx;lat=xxx”
示例:“lgt=22.5044;lat=113.9537”
String 30
openApiAppId 腾讯云线下对接分配的 AppID String 腾讯云线下对接决定
openApiAppVersion 接口版本号,默认填:1.0.0 String 20
openApiNonce 32位随机字符串,每次请求需要的一次性 nonce String 32
openApiUserId User Id,每个用户唯一的标识 String 30
openApiSign 合作方后台服务器通过 ticket 计算出来的签名信息 String 40
verifyMode 人脸核身类型
动作活体: FaceVerifyStatus.Mode.MIDDLE
数字活体:FaceVerifyStatus.Mode.ADVANCED
光线活体:FaceVerifyStatus.Mode.REFLECT
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 提供权威数据源比对、自带比对源比对、仅活体检测,合作方可以选择传入参数控制对比类型。

  • 权威数据源比对
    合作方必须要先在获 取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); 
  • 仅活体检测
    合作方无需获取 faceId,也无需上送任何用户比对源信息,SDK 仅仅对用户进行活体检测。设置的代码如下:

    # 在MainActivity中单击某个按钮的代码逻辑:
    //先将必填的InputData放入Bundle中
    data.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);
    //设置选择的比对类型  仅活体检测
    data.putString(WbCloudFaceContant.COMPARE_TYPE, WbCloudFaceContant.NONE);

是否录制视频存证

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

个性化设置接入示例

# 在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.COMPARE_TYPE, WbCloudFaceContant.ID_CARD);
//是否需要录制上传视频 默认需要,此处设置为不需要 
 data.putBoolean(WbCloudFaceContant.VIDEO_UPLOAD, false);
  //是否对录制视频进行检查,默认不检查,此处设置为检查
  data.putBoolean(WbCloudFaceContant.VIDEO_CHECK, true);
    //设置是否打开闭眼检测,默认不检测,此处设置为检测
  data.putBoolean(WbCloudFaceContant.ENABLE_CLOSE_EYES, true);