接入文档

有奖征文|投稿上云技术实践,赢取价值5000元大奖> HOT

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 页面。
     * 由 startWbFaceVerifySdk 返回刷脸结果。
     */
public void startWbFaceVerifySdk(Context ctx,
WbCloudFaceVerifyResultListener listener) {    // ...
}
/**
 * 释放资源,防止内存泄漏。收到刷脸结果后即可调用
 */
public void release() {
}

  • NONCE 类型的 ticket,其有效期为120秒,且一次性有效,即每次启动 SDK 刷脸都要重新请求 NONCE ticket,重新算 sign。同时建议合作方做前端保护,防止用户连续点击,短时间内频繁启动 SDK。
  • 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.GRADE     
FaceVerifyStatus.Mode verifyMode;
String keyLicence;   //在人脸核身控制台内申请

注意:

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

接入示例

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

接口参数说明

InputData 对象说明

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

参数 说明 类型 长度(字节) 是否必填
faceId 刷脸 ID 号,由合作方向人脸识别后台拉取获得 String -
agreementNo 订单号,合作方订单的唯一标识 String 32
openApiAppId 业务流程唯一标识,即 wbappid,可参考 获取 WBappid 指引在人脸核身控制台内申请 String 8
openApiAppVersion 接口版本号,默认填:1.0.0 String 20
openApiNonce 与服务端生成签名的随机数保持一致 String 32
openApiUserId User Id,每个用户唯一的标识 String 30
openApiSign 获取方式请参考 生成 SDK 接口调用步骤使用签名 String 40
verifyMode 刷脸类型:分级模式 FaceVerifyStatus.Mode.GRADE FaceVerifyStatus.Mode -
keyLicence 在人脸核身控制台内申请 String 以实际申请为准

个性化参数设置(可选)

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

选择 SDK 提示语言类型

合作方可以选择 SDK 显示提示语的语言类型,默认简体中文,可以选择繁体中文,英语,日语,韩语,泰语和印尼语。设置代码如下:

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundle 中
  data.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);
  //简体中文  WbCloudFaceContant.LANGUAGE_ZH_CN
  //繁体中文  WbCloudFaceContant.LANGUAGE_ZH_HK
  //英语  WbCloudFaceContant.LANGUAGE_EN
  //印尼语  WbCloudFaceContant.LANGUAGE_ID
  //日语  WbCloudFaceContant.LANGUAGE_JA
  //韩语  WbCloudFaceContant.LANGUAGE_KO
   //泰语 WbCloudFaceContant.LANGUAGE_TH
//默认设置为简体中文,此处设置为英文
data.putString(WbCloudFaceContant.LANGUAGE,WbCloudFaceContant.LANGUAGE_EN);
特别注意,在设置了国际化语言的情况下,SDK 不会播放语音,也不显示结果页,自定义退出框也无效。同时合作方设定的自定义提示语也需要合作方传入相应语种的提示语。

是否显示刷脸成功页面

合作方可以控制是否显示 SDK 自带的刷脸成功页面。 SDK 默认不显示刷脸成功页面,如需设置显示,设置代码如下:

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

是否显示刷脸失败原因页

合作方可以控制是否显示 SDK 自带的刷脸失败页面。 SDK 默认不显示刷脸失败页面,如需设置显示,设置代码如下:

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

SDK 样式选择

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

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

SDK 还支持自定义皮肤,支持定制刷脸过程中各个组件的色值,因涉及可设置元素较多,此处可以参考接入 demo。使用自定义皮肤时需要设置:

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

可配置的颜色值如下:

# 在App的colors.xml中设置:
   <!--供客户定制颜色值,可修改仅自己需要修改的颜色,其余复制粘贴demo示例即可-->
    <!--请注意,根据客户定制的需求,有些色值除了需要在用户app的colors里加上以下所有配置之外,还需要同步增加mipmaps和drawble的xml文件-->
    <!--详情见下面说明,所有的定制res都以wbcf_custom开头,用户可以参考demo使用-->

    <!--授权页面还有一张背景图需要设置,请在mipmap文件夹里替换-->
    <!--授权页面titlebar背景颜色-->
    <color name="wbcf_custom_auth_title_bar">#ffffff</color>
    <!--授权页面titlebar返回键颜色-->
    <color name="wbcf_custom_auth_back_tint">#ffffff</color>
    <!--授权页面背景颜色-->
    <color name="wbcf_custom_auth_bg">#ffffff</color>
    <!--授权页面标题颜色-->
    <color name="wbcf_custom_auth_title">#1d2232</color>
    <!--授权页面文字颜色-->
    <color name="wbcf_custom_auth_text">#a5a7ad</color>
    <!--授权页面协议名称颜色-->
    <color name="wbcf_custom_auth_name_text">#1d2232</color>
    <!--授权页面按钮文字颜色-->
    <color name="wbcf_custom_auth_btn_text">#80ffffff</color>
    <!--授权页面被选中按钮背景色,需要配合drawable/wbcf_custom_auth_btn_checked.xml使用-->
    <color name="wbcf_custom_auth_btn_checked_bg">#1e2642</color>
    <!--授权页面未选中按钮背景色,需要配合drawable/wbcf_custom_auth_btn_unchecked.xml使用-->
    <color name="wbcf_custom_auth_btn_unchecked_bg">#9ca1ae</color>

    <!--识别页面背景色-->
    <color name="wbcf_custom_verify_bg">#ffffff</color>
    <!--识别页面初始化圆框-->
    <color name="wbcf_custom_initial_border">#33ffffff</color>
    <!--识别页面有脸时圆框颜色-->
    <color name="wbcf_custom_border">#ffb155</color>
    <!--识别页面有脸时提示文字颜色-->
    <color name="wbcf_custom_tips_text">#1d2232</color>
    <!--识别页面人脸不符合条件时圆框颜色-->
    <color name="wbcf_custom_border_error">#fa5a5a</color>
    <!--识别页面人脸不符合条件时提示文字颜色-->
    <color name="wbcf_custom_tips_text_error">#fa5a5a</color>
    <!--识别页面用户自定义提示文字颜色-->
    <color name="wbcf_custom_customer_tip_text">#5d646d</color>
    <!--识别页面长提示文字颜色-->
    <color name="wbcf_custom_long_tip_text">#777A84</color>
    <!--识别页面长提示背景颜色,需要配合drawable/wbcf_custom_long_tip_bg.xml使用-->
    <color name="wbcf_custom_long_tip_bg">#fafafa</color>

    <!--弹窗背景颜色-->
    <color name="wbcf_custom_dialog_bg">#ffffff</color>
    <!--弹窗标题文字颜色-->
    <color name="wbcf_custom_dialog_title_text">#363C62</color>
    <!--弹窗内容文字颜色-->
    <color name="wbcf_custom_dialog_text">#363C62</color>
    <!--弹窗右边按钮文字颜色-->
    <color name="wbcf_custom_dialog_right_text">#363C62</color>
    <!--弹窗左边按钮文字颜色-->
    <color name="wbcf_custom_dialog_left_text">#363C62</color>

    <!--如果不使用sdk的结果页面,则可以忽略以下配置-->
    <!--结果页面还有一张成功图和一张失败图需要设置,请在mipmap文件夹里替换-->
    <!--结果页面背景颜色-->
    <color name="wbcf_custom_result_bg">#ffffff</color>
    <!--结果页面标题颜色-->
    <color name="wbcf_custom_result_title">#1d2232</color>
    <!--结果页面原因文字颜色-->
    <color name="wbcf_custom_result_reason_text">#a5a7ad</color>
    <!--结果页面退出按钮文字颜色-->
    <color name="wbcf_custom_result_quit_btn_text">#777A84</color>
    <!--结果页面取消按钮背景颜色,需要配合drawable/wbcf_custom_result_cancel_btn.xml使用-->
    <color name="wbcf_custom_cancel_btn_bg">#ffffff</color>
    <!--结果页面完成按钮背景颜色,需要配合drawable/wbcf_custom_result_yes_btn.xml使用-->
    <color name="wbcf_custom_yes_btn_bg">#1e2642</color>

合作方个性化提示定制(国际化语言模式下不支持)

合作方可以设置定制的提示语,通过配置传给 SDK。自定义提示语分为短提示(不长于17个字符)和长提示(不长于70个字符)。如果不设置,默认无。如果超过字数限制,将会被截断显示。
自定义短提示分为验证阶段提示和上传阶段提示,可以分开设置。位置可以选择位于预览圆框的上方或者下方。默认自定义短提示位于预览圆框下方。若设置自定义短提示位于预览圆框上方的话,sdk过程提示将自动调整到圆框下方。
设置代码如下:

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundledata.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);

自定义长提示位于整个验证页面的下方,存在于整个刷脸流程中,不能设置位置和时机。
设置代码如下:

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundledata.putSerializable((WbCloudFaceContant.INPUT_DATA, inputData);
//整个识别过程中合作方定制长提示语(不超过70个字符)
  data.putString(WbCloudFaceContant.CUSTOMER_LONG_TIP, customerLongTip);

合作方还可以自定义 SDK 退出二次确认弹窗的文字内容,包括提示标题,提示内容,确认键文案和取消键文案。设置代码如下:

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundledata.putSerializable((WbCloudFaceContant.INPUT_DATA, inputData);
//退出确认弹窗定制提示标题
  data.putString(WbCloudFaceContant.DIALOG_TITLE, dialogTitle);
  //退出确认弹窗定制提示内容
  data.putString(WbCloudFaceContant.DIALOG_TEXT, dialogText);
  //退出确认弹窗定制确认键文案
  data.putString(WbCloudFaceContant.DIALOG_YES, dialogYes);
   //退出确认弹窗定制取消键文案
   data.putString(WbCloudFaceContant.DIALOG_NO, dialogNo);

比对类型选择

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

  • 权威库网纹图片比对类型
    合作方必须要先在获取 faceId 的接口里送入用户的姓名与身份证号信息,得到相应的 faceId 后,再送入 SDK,供 SDK 与权威库网纹图片进行比对。不需要额外设置对比类型。

  • 自带比对源比对类型
    合作方在获取 faceId 的接口里送入用户提供对比源数据,获取 faceId 后送入 SDK 进行对比。合作方可以上送两类照片,一类是网纹照,一类是高清照;不需要额外设置对比类型。

是否录制视频存证

SDK 默认不录制视频存证。如果合作方需要视频存证,可以通过该字段进行设置。设置代码如下:

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

是否对录制视频进行检查

说明:

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

  • 在 SDK 使用过程中,发现视频录制在性能不太好的手机上可能会报错,导致刷脸中断,影响用户体验。
  • 为了减少录制视频导致的人脸核身中断问题,SDK 默认设置对录制的视频不作检测。
  • 如果合作方对人脸核身安全有更加严格的要求,可以考虑打开这一选项。但打开这个字段可能导致某些低性能手机上用户人脸核身不能进行,请慎重考虑。设置代码如下:

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

是否播放语音提示(国际化语言模式下不支持)

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

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

个性化设置接入示例

# 在 MainActivity 中单击某个按钮的代码逻辑:
  //先将必填的 InputData 放入 Bundledata.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);
  //个性化参数设置,此处均设置为与默认相反
     //默认设置为简体中文,此处设置为英文
data.putString(WbCloudFaceContant.LANGUAGE,WbCloudFaceContant.LANGUAGE_EN);
  //是否显示成功结果页,默认不显示,此处设置为显示
  data.putBoolean(WbCloudFaceContant.SHOW_SUCCESS_PAGE, true);
  //是否展示刷脸失败页面,默认不显示,此处设置为显示
  data.putBoolean(WbCloudFaceContant.SHOW_FAIL_PAGE, true);
//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. PLAY_VOICE, false);

目录