开发准备
CPU 平台设置
目前 SDK 支持 armeabi-v7a 和 arm64-v8a,为了防止在其他 CPU 平台上 SDK Crash,我们建议在您的 App 的 build.gradle 里加上 abiFilter,如下所示:
defaultConfig {ndk {//设置支持的so库框架abiFilters 'armeabi-v7a', 'arm64-v8a',}}
配置流程
接入配置
意愿核身 SDK(WbCloudFaceLiveSdk、WbCloudFaceWillSdk)最低支持到 Android API 19: Android 4.4 (KitKat) ,请在构建项目时注意。
意愿核身 SDK 将以 AAR 文件的形式提供。另外 意愿核身 SDK 同时需要依赖云公共组件 WBCloudNormal,同样也是以 AAR 文件的形式提供。
需要添加下面文档中所示的依赖(将提供的 AAR 文件加入到 app 工程的 libs 文件夹下面,并且在 build.gradle 中添加下面的配置):
android{//...repositories {flatDir {dirs 'libs' //this way we can find the .aar file in libs folder}}}//添加依赖dependencies {//1. 云刷脸SDKimplementation(name: 'WbCloudFaceLiveSdk-v4.5.5.0-3b725d95', ext: 'aar')//2. 云common SDKimplementation(name: 'WbCloudNormal-v5.1.3-0f08e6d', ext: 'aar')//3.意愿性 SDKimplementation(name: 'WbCloudFaceWillSdk-v1.0.0-3b725d95', ext: 'aar')}
混淆配置
混淆规则已经嵌入 sdk 内,此处不另外提供。
接口调用
1. 标准模式 SDK 接口调用方法
SDK 代码调用的入口为
com.tencent.cloud.huiyansdkface.facelight.api.WbCloudFaceVerifySdk
这个类。 public class WbCloudFaceVerifySdk{/*** 该类为一个单例,需要先获得单例对象再进行后续操作*/public static synchronized WbCloudFaceVerifySdk getInstance() {// ...}/*** 在使用SDK前先初始化,传入需要的数据data* 由 WbCloudFaceVerifyLoginListener返回是否登录SDK成功* 关于传入数据data见后面的说明*/public void initWillSdk(Context context,Bundle data,WbCloudFaceVerifyLoginListener loginListerner){// ...}/*** 登录成功后,调用此函数拉起sdk页面。* 由 FaceVerifyResultForSecureListener返回刷脸结果。*/public void startWbFaceVerifySdk(Context ctx,WbCloudFaceVerifyResultListener listener) { // ...}
WbCloudFaceVerifySdk.initSdk() 的第二个参数用来传递数据.可以将参数打包到 data(Bundle) 中,必须传递的参数包括:
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 对象)。
2. 登录接口
/*** 登录回调接口*/public interface WbCloudFaceVerifyLoginListener {void onLoginSuccess();void onLoginFailed(WbFaceError error);}
3. 返回第三方接口
/*** 退出SDK,返回第三方的回调,同时返回识别结果*/public interface WbCloudFaceVerifyResultListener {/*** @PARAM result 刷脸结果*/void onFinish(WbFaceVerifyResult result);}
识别结果类
WbFaceVerifyResult 是 SDK 用来给合作方传递身份识别结果的对象,在 WbCloudFaceVerifyResultListener 回调中作为参数返回给合作方 App。WbFaceVerifyResult 对象的各个字段意义如下表所示:
字段名 | 类型 | 字段含义 | 说明 |
isSuccess | boolean | 人脸核身是否成功 | True 代表人脸核身对比成功;false 代表人脸核身失败,具体的失败原因请参考 WbFaceError 对象说明 |
sign | String | 签名 | 供 App 校验人脸核身结果的安全性 |
liveRate | String | 活体检测分数 | - |
similarity | String | 人脸比对分数 | “仅活体检测” 类型不提供此分数 |
userImageString | String | 用户人脸核身图片 | 经过 Base64 编码后的用户人脸核身图片,仅用户成功通过验证时返回 |
WbFaceError | 自定义对象 | 人脸核身错误 | 人脸核身成功时为 null |
WbFaceWillModeResult | 自定义对象 | 意愿性结果信息 | - |
WbFaceError 对象说明
WbFaceError 是 SDK 用来给合作方传递人脸核身错误信息的对象,在 WbCloudFaceVerifyLoginListener 回调和 WbFaceVerifyResult 对象中作为参数返回给合作方 App。WbFaceError 对象的各个字段意义如下表所示,各个字段的内容取值详情请参见 SaaS 服务 错误码。
字段名 | 类型 | 字段含义 | 说明 |
domain | String | 错误发生的阶段 | 只有当domain=WBFaceErrorDomainCompareServer时表示用户完成了刷脸,可以通过接口去拉取刷脸结果。其他domain表示用户刷脸中途退出或命中了风控逻辑,后端无法查询到刷脸结果 |
code | String | 错误码 | - |
desc | String | 错误描述 | 如有需求,可以展示给用户 |
reason | String | 错误信息内容 | 错误的详细实际原因,主要用于定位问题 |
WbFaceWillModeResult 对象说明
WbFaceWillModeResult 是 SDK 用来给合作方传递意愿性表达综合信息的对象,在 WbCloudFaceVerifyResultListener 中的 WbFaceVerifyResult 对象中作为参数返回给合作方 App。WbFaceWillModeResult 对象的各个字段意义如下表所示,各个字段的内容取值详情请参见 SaaS 服务 错误码。
字段名 | 类型 | 字段含义 | 说明 |
faceCode | String | 人脸识别结果码 | - |
faceMsg | String | 人脸识别结果信息 | - |
willCode | String | ASR 结果码 | - |
willMsg | String | ASR 结果信息 | - |
videoPath | String | 意愿性存证视频存储地址 | 如果打开了本地存储意愿性视频开关,将在此处返回意愿性视频地址 |
接口参数说明
InputData 对象说明
InputData 是用来给 SDK 传递一些必须参数所需要使用的对象(WbCloudFaceVerifySdk.initWillSdk() 的第二个参数),合作方需要往里塞入SDK 需要的一些数据以便启动刷脸 SDK。
其中 InputData 对象中的各个参数定义如下表,请合作方按下表标准传入对应的数据。
参数 | 说明 | 类型 | 长度(字节) | 是否必填 |
faceId | 刷脸 id 号,由合作方向人脸识别后台拉取获得 | String | - | 是 |
agreementNo | 订单号,合作方订单的唯一标识 | String | 32 | 是 |
openApiAppId | 业务流程唯一标识,即 WBappid,可参考 获取 WBappid 指引在人脸核身控制台内申请 | String | 8 | 是 |
openApiAppVersion | 接口版本号,默认填 1.0.0 | String | 20 | 是 |
openApiNonce | 32 位随机字符串,每次请求需要的一次性 nonce | 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 默认不录制视频存证。如果合作方需要视频存证,可以通过该字段进行设置。设置代码如下:
# 在MainActivity中单击某个按钮的代码逻辑://先将必填的InputData放入Bundle中data.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);//设置是否录制视频进行存证,默认不录制存证。//此处设置为录制存证data.putBoolean(WbCloudFaceContant.RECORD_WILL_VIDEO, true);
是否对录制视频进行检查
说明
如果上一节的 是否录制视频存证 的设置为录制存证,则目前该字段有效,否则不录制视频的话,也不会对视频进行检查,设置无效。
在 SDK 使用过程中,发现视频录制在性能不太好的手机上可能会报错,导致刷脸中断,影响用户体验。
为了减少因为录制视频原因导致的刷脸中断问题,SDK 默认设置对录制的视频不作检测。如果合作方对刷脸安全有进一步的更加严格的要求,可以考虑打开这一选项。但打开这个字段可能导致某些低性能手机上用户刷脸不能进行,请慎重考虑。设置代码如下:
# 在MainActivity中单击某个按钮的代码逻辑://先将必填的InputData放入Bundle中data.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);//设置是否对录制的视频进行检测,默认不检测//此处设置为检测data.putBoolean(WbCloudFaceContant.CHECK_WILL_VIDEO, true);
错误码描述
SDK 在登录以及返回人脸服务结果时,如果发生错误或者识别失败会返回 WBFaceError 对象,该对象的字段结构意义见 接口参数说明,其中各个字段的内容如下:
WBFaceErrorDomainParams
Code(错误码) | Description(描述) | Reason(详细实际原因) |
11000 | 传入参数为空 | 传入的xx为空 |
11001 | 传入的 keyLicence | 不可用 传入的 keyLicence 不可用 |
11002 | 报文加解密失败 | 报文加解密失败 |
WBFaceErrorDomainLoginNetwork
Code(错误码) | Description(描述) | Reason(详细实际原因) |
21100 | 网络异常 | 登录时网络异常(请求未到达后台) |
21200 | 网络异常 | 登录时后台返回参数有误(请求到达后台) |
WBFaceErrorDomainLoginServer
Code(错误码) | Description(描述) | Reason(详细实际原因) |
其他错误码 | 透传后台错误码 | 例如签名问题等 |
WBFaceErrorDomainGetInfoNetwork
Code(错误码) | Description(描述) | Reason(详细实际原因) |
31100 | 网络异常 | 获取活体类型/光线/意愿性表达资源,网络异常(请求未到达后台) |
31200 | 网络异常 | 获取活体类型/光线/意愿性表达资源,后台返回参数有误(请求到达后台) |
WBFaceErrorDomainNativeProcess
Code(错误码) | Description(描述) | Reason(详细实际原因) |
41000 | 用户取消 | 回到后台/单击 home/左上角/上传时左上角取消 |
41001 | 无法获取唇语数据 | 获取数字活体的数字有问题 |
41002 | 权限异常,未获取权限 | 相机 |
41003 | 相机运行中出错 | - |
41004 | 视频录制中出错 | 不能存/启动失败/结束失败 |
41005 | 请勿晃动人脸,保持姿势 | 未获取到最佳图片 |
41006 | 视频大小不满足要求 | 视频大小不满足要求 |
41007 | 超时 | 预检测/动作活体 |
41008 | 检测中人脸移出框外 | 活体/数字/反光 |
41009 | 光线活体本地错误 | - |
41010 | 风险控制超出次数 | 用户重试太多次 |
41011 | 没有检测到读数声音 | 数字活体过程中没有发声 |
41012 | 初始化模型失败,请重试 | 初始化算法模型失败 |
41013 | 初始化 sdk 异常 | WbCloudFaceVerifySdk 未被初始化 |
41014 | 简单模式本地加密失败 | 编码转换异常/加解密编码失败 |
41101 | 音频录制中出错 | 意愿性录音失败 |
41102 | 没有检测到麦克风声音 | 意愿性检测音量过低 |
41103 | 播报音频文件加载失败 | 意愿性播放音频失败 |
WBFaceErrorDomainCompareNetwork
Code(错误码) | Description(描述) | Reason(详细实际原因) |
51100 | 网络异常 | 对比时,网络异常(请求未到达后台) |
51200 | 网络异常 | 对比时,后台返回参数有误(请求到达后台) |
WBFaceErrorDomainCompareServer
Code(错误码) | Description(描述) | Reason(详细实际原因) |
其他错误码 | 透传后台错误码 | - |
接入示例
权威库网纹图片比对、自带对比源对比接入示例:
# 在MainActivity中单击某个按钮的代码逻辑://先填好数据Bundle data = new Bundle();WbCloudFaceVerifySdk.InputData inputData = new WbCloudFaceVerifySdk.InputData(faceId,agreementNo,openApiAppId,openApiAppVersion,openApiNonce,userId,userSign,verifyMode,keyLicence);data.putSerializable(WbCloudFaceContant.INPUT_DATA, inputData);//设置选择的比对类型 默认为权威库网纹图片对比//此处设置权威库网纹图片对比data.putString(WbCloudFaceContant.COMPARE_TYPE, WbCloudFaceContant.ID_CRAD);//初始化 SDK,得到是否登录 SDK 成功的结果,由 WbCloudFaceVerifyLoginListener 返回登录结果//【特别注意】建议对拉起人脸识别按钮做防止重复点击的操作//避免用户快速点击导致二次登录,二次拉起刷脸等操作引起问题WbCloudFaceVerifySdk.getInstance().initWillSdk(DemoActivity.this, data, new WbCloudFaceVerifyLoginListener() {@Overridepublic void onLoginSuccess() {//登录成功,拉起 sdk 页面,由 FaceVerifyResultListener 返回刷脸结果WbCloudFaceVerifySdk.getInstance().startWbFaceVerifySdk(DemoActivity.this, new WbCloudFaceVerifyResultListener() {@Overridepublic void onFinish(WbFaceVerifyResult result) {if (result != null) {if (result.isSuccess()) {Log.d(TAG, "刷脸成功!");} else {Log.d(TAG, "刷脸失败!");}}//刷脸结束后,及时释放资源WbCloudFaceVerifySdk.getInstance().release();}});}@Overridepublic void onLoginFailed(WbFaceError error) {Log.d(TAG, "登录失败!");//刷脸结束后,及时释放资源WbCloudFaceVerifySdk.getInstance().release();}});
详细接入代码,请参考 SDK 附的 KnowYourCustomerDemo 工程。