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_IDString openApiAppVersion; //openapi VersionString openApiNonce; //32位随机字符串String openApiUserId; //user idString openApiSign; //签名信息//刷脸类别:分级活体 FaceVerifyStatus.Mode.GRADEFaceVerifyStatus.Mode verifyMode;String keyLicence; //在人脸核身控制台内申请
注意
以上参数被封装在 WbCloudFaceVerifySdk.InputData 对象中(它是一个 Serializable 对象)。
接入示例
接入示例
接口参数说明
接口参数说明
InputData 对象说明
NONCE 类型的 ticket,其有效期为120秒,且一次性有效,即每次启动 SDK 刷脸都要重新请求 NONCE ticket,重新算 sign。同时建议合作方做前端保护,防止用户连续点击,短时间内频繁启动 SDK。
InputData 是用来给 SDK 传递一些必须参数所需要使用的对象(WbCloudFaceVerifySdk.initSdk() 的第二个参数),合作方需要传入 SDK 需要的一些数据以便启动刷脸 SDK。
其中 InputData 对象中的各个参数定义如下表,请合作方按下表标准传入对应的数据。
参数 | 说明 | 类型 | 长度(字节) | 是否必填 |
faceId | 刷脸 ID 号,获取方式请参见 合作方后台上传身份信息 | String | - | 是 |
agreementNo | 订单号,合作方订单的唯一标识 | String | 32 | 是 |
openApiAppId | 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 | 在人脸核身控制台申请的 SDKlicense | String | 以实际申请为准 | 是 |
个性化参数设置(可选)
WbCloudFaceVerifySdk.initSdk()
里Bundle data
,除了必须要传的 InputData 对象之外,还可以由合作方为其传入一些个性化参数,量身打造更契合自己 App 的 SDK。如果合作方未设置这些参数,则以下所有参数按默认值设置。设置 SDK 支持境外调用
SDK 默认不支持境外调用。如果合作方需支持境外调用,可以通过该字段进行设置。设置代码如下:
# 优先使用境外域名,默认false,不使用# 请注意:如果合作方可以分辨国内或者境外ip,建议境外ip开启这个配置,国内ip访问不进行配置data.putBoolean(WbCloudFaceContant.IS_ABROAD, true);
选择 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 样式。目前 SDK 有黑色模式和白色模式两种,默认显示白色模式。设置代码如下:
# 在 MainActivity 中单击某个按钮的代码逻辑://先将必填的 InputData 放入 Bundle中data.putSerializable((WbCloudFaceContant.INPUT_DATA, inputData);//对 sdk 样式进行设置,默认为白色模式//此处设置为白色模式data.putString(WbCloudFaceContant.COLOR_MODE, WbCloudFaceContant.WHITE);
SDK 还支持自定义皮肤,支持定制刷脸过程中各个组件的色值,因涉及可设置元素较多,此处可以参考接入 demo。使用自定义皮肤时需要设置:
# 在 MainActivity 中单击某个按钮的代码逻辑://先将必填的 InputData 放入 Bundle中data.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。自定义提示语分为短提示(不长于17个字符)和长提示(不长于70个字符)。如果不设置,默认无。如果超过字数限制,将会被截断显示。
自定义短提示分为验证阶段提示和上传阶段提示,可以分开设置。位置可以选择位于预览圆框的上方或者下方。默认自定义短提示位于预览圆框下方。若设置自定义短提示位于预览圆框上方的话,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_TOPdata.putInt(WbCloudFaceContant.CUSTOMER_TIPS_LOC,WbCloudFaceContant.CUSTOMER_TIPS_LOC_TOP);
自定义长提示位于整个验证页面的下方,存在于整个刷脸流程中,不能设置位置和时机。
设置代码如下:
# 在 MainActivity 中单击某个按钮的代码逻辑://先将必填的 InputData 放入 Bundle中data.putSerializable((WbCloudFaceContant.INPUT_DATA, inputData);//整个识别过程中合作方定制长提示语(不超过70个字符)data.putString(WbCloudFaceContant.CUSTOMER_LONG_TIP, customerLongTip);
合作方还可以自定义 SDK 退出二次确认弹窗的文字内容,包括提示标题,提示内容,确认键文案和取消键文案。设置代码如下:
# 在 MainActivity 中单击某个按钮的代码逻辑://先将必填的 InputData 放入 Bundle中data.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 放入 Bundle 中data.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);//设置是否录制视频进行存证,默认不录制存证。//此处设置为录制存证data.putBoolean(WbCloudFaceContant.VIDEO_UPLOAD, true);
是否对录制视频进行检查
说明
如果在“是否录制视频存证”步骤的设置为录制存证,则目前该字段有效;否则,设置为不录制存证,也不会对视频进行检查,设置无效。
在 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. PLAY_VOICE, true);
个性化设置接入示例
# 在 MainActivity 中单击某个按钮的代码逻辑://先将必填的 InputData 放入 Bundle 中data.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);//个性化参数设置,此处均设置为与默认相反//默认设置为简体中文,此处设置为英文data.putString(WbCloudFaceContant.LANGUAGE,WbCloudFaceContant.LANGUAGE_EN);//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);