开发准备
权限
SDK 需要用到相机权限、麦克风权限和网络权限,如下示例:
"requestPermissions": [{"name": "ohos.permission.INTERNET",},{"name": "ohos.permission.GET_NETWORK_INFO"},{"name": "ohos.permission.GET_WIFI_INFO"},{"name": "ohos.permission.CAMERA","reason": "face verify","usedScene": {"abilities": ["EntryAbility",],"when": "inuse"}},{"name": "ohos.permission.MICROPHONE","usedScene": {"abilities": ["EntryAbility",],"when": "inuse"},"reason": "face verify"}]
CPU平台配置
当前 Harmony NEXT 手机都是64位手机,目前 SDK 只支持 armeabi-v8a 平台。
配置流程
注意:
以下文章出现 “刷脸” 一词均可以表示为 “意愿核身”。
接入配置
SDK(WbCloudFaceVerifySdk-xx.har, 具体版本号以SDK交付件为准)最低支持到 5.0.0(12) ,请在构建项目时注意。
刷脸 SDK 将以 HAR 文件的形式提供。
将提供的 HAR 文件添加到工程的libs目录下,并且在 oh-package.json5 中添加下面的配置,请注意大小写:
"dependencies": {"wbcloudfaceverifysdk": "file:../libs/WbCloudFaceVerifySdk-xxx.har"}
接口调用
本章将展示 SDK 核心接口的调用方法。具体的代码示例参考交付 Demo(demo/entry/src/main/ets/pages/DemoPage.ets)。
注意:
以下文章出现 “刷脸” 一词均可以表示为 “意愿核身”。
SDK 接口调用方法
SDK 代码调用的入口为:WbCloudFaceVerifySdk 这个类。
export class WbCloudFaceVerifySdk {/*** 该类为一个单例,需要先获得单例对象再进行后续操作*/public static getInstance(): WbCloudFaceVerifySdk {…}/*** 在使用SDK前先初始化,传入需要的数据WbFaceVerifyConfig* 由 WbCloudFaceVerifyLoginCallback返回是否登录SDK成功* 关于传入WbFaceVerifyConfig见后面的说明*/public initWillSdk(context: Context, config: WbFaceVerifyConfig, loginCallback: WbCloudFaceVerifyLoginCallback) {…}/*** 登录成功后,调用此函数拉起sdk页面。* 由 WbCloudFaceVerifyResultCallback返回刷脸结果。*/public startWbFaceVerifySdk(context: Context, resultCallback: WbCloudFaceVerifyResultCallback) {…}/*** 拿到刷脸结果后,释放资源, 防止内存泄漏* 【注意】请务必在拿到刷脸结果后释放资源,否则可能会发生丢失回调的情况!*/public release() {…}}
WbCloudFaceVerifySdk.initSdk() 的第二个参数 config: WbFaceVerifyConfig 用来传递 SDK 初始化必需数据和 SDK 配置项参数。
export class WbFaceVerifyConfig {//sdk初始化必需数据public inputData: InputData;//是否开启日志,默认不打开sdk日志,//【注意】上线请务必关闭sdk日志!public isEnableLog: boolean = false;}
必须传递的参数包括(参考要求详见本页接口参数说明的描述):
//这些都是InputData对象里的字段,是需要传入的数据信息export class InputData {//此次刷脸用户标识,合作方需要向意愿识别后台拉取获得,详见获取faceId接口public faceId: string;//订单号public orderNo: string;//APP_IDpublic appId: string;//openapi Versionpublic version: string;//32位随机字符串public nonce: string;//User idpublic userId: string;//签名信息public sign: string;////在意愿核身控制台内申请public licence: string;}
接口参数说明
InputData 对象说明
InputData 是用来给 SDK 传递必须参数所需要使用的对象,合作方需要往里塞入SDK 需要的一些数据以便启动刷脸 SDK。
其中 InputData 对象中的各个参数定义如下表,请合作方按下表标准传入对应的数据。
参数 | 说明 | 类型 | 长度(字节) | 是否必填 |
faceId | 刷脸id号,由合作方向意愿识别后台拉取获得 | String | - | 是 |
orderNo | 订单号,合作方订单的唯一标识 | String | 32 | 是 |
appId | String | 8 | 是 | |
version | 接口版本号,默认填1.0.0 | String | 20 | 是 |
nonce | 32 位随机字符串,每次请求需要的一次性 nonce | String | 32 | 是 |
userId | User Id,每个用户唯一的标识 | String | 30 | 是 |
sign | String | 40 | 是 | |
licence | 在意愿核身控制台内申请 | String | 以实际申请为准 | 是 |
个性化参数设置(可选)
WbCloudFaceVerifySdk.initSdk() 里 WbFaceVerifyConfig,除了必须要传的 InputData 对象之外,还可以由合作方为其传入一些个性化参数,量身打造更契合自己 App 的 SDK。如果合作方未设置这些参数,则以下所有参数按默认值设置。(暂不支持,后续 SDK 版本将逐步更新)
核身结果返回
SDK 结果分别由以下两个回调返回:
如果您只需要获取刷脸结果,不需要拉取视频和照片,您可以信任前端 SDK 核身结果,返回中isSuccess字段True代表意愿核身对比成功;false代表意愿核身失败。核身SDK和核身后台服务之间通信采用加密方式,可以有效防止结果篡改。
/*** 登录回调接口 返回登录 sdk 是否成功*/export interface WbCloudFaceVerifyLoginCallback {onLoginSuccess: () => void;onLoginFail: (error: WbFaceError) => void;}/*** 刷脸结果回调接口*/export interface WbCloudFaceVerifyResultCallback {onFinish: (result: WbFaceVerifyResult) => void;}
WBFaceVerifyResult 对象说明
WbFaceVerifyResult 是 SDK 用来给合作方传递身份识别结果的对象,在WbCloudFaceVerifyResultListener回调中作为参数返回给合作方 App。WbFaceVerifyResult 对象的各个字段意义如下表所示:
字段名 | 类型 | 字段含义 | 说明 |
isSuccess | boolean | 意愿核身是否成功 | True代表意愿核身对比成功;false代表意愿核身失败,具体的失败原因请参考WbFaceError对象说明 |
sign | String | 签名 | 供 App 校验意愿核身结果的安全性 |
liveRate | String | 活体检测分数 | - |
similarity | String | 意愿比对分数 | “仅活体检测” 类型不提供此分数 |
WbFaceError | 自定义对象 | 意愿核身错误 | 意愿核身成功时为 null |
WbFaceError 对象说明
WbFaceError 是 SDK 用来给合作方传递意愿核身错误信息的对象,在WbCloudFaceVerifyLoginListener回调和 WbFaceVerifyResult 对象中作为参数返回给合作方 App。WbFaceError 对象的各个字段意义如下表所示,各个字段的内容取值详情请参见 SaaS 服务错误码。
字段名 | 类型 | 字段含义 | 说明 |
domain | String | 错误发生的阶段 | 只有当domain=WBFaceErrorDomainCompareServer时表示用户完成了刷脸,可以通过接口去拉取刷脸结果。其他domain表示用户刷脸中途退出或命中了风控逻辑,后端无法查询到刷脸结果 |
code | String | 错误码 | - |
desc | String | 错误描述 | 如有需求,可以展示给用户 |
reason | String | 错误信息内容 | 错误的详细实际原因,主要用于定位问题 |
错误码描述
注意:
以下文章出现 “刷脸” 一词均可以表示为 “意愿核身”。
SDK 在登录以及返回意愿服务结果时,如果发生错误或者识别失败会返回 WBFaceError 对象,该对象的字段结构意义见 接口参数说明,其中各个字段的内容如下:
WBFaceErrorDomainParams
Code(错误码) | Description(描述) | Reason(详细实际原因) |
13000 | 传入参数为空 | 传入的 xx为空 |
13001 | 传入的keyLicence不可用 | 传入的keyLicence不可用 |
13002 | 报文加解密失败 | 报文加解密失败 |
WBFaceErrorDomainLoginNetwork
Code(错误码) | Description(描述) | Reason(详细实际原因) |
23100 | 网络异常 | 登录时网络异常(请求未到达后台) |
23200 | 网络异常 | 登录时后台返回参数有误(请求到达后台) |
WBFaceErrorDomainLoginServer
Code(错误码) | Description(描述) | Reason(详细实际原因) |
其他错误码 | 透传后台错误码 | 例如签名问题等等 |
WBFaceErrorDomainGetInfoNetwork
Code(错误码) | Description(描述) | Reason(详细实际原因) |
33100 | 网络异常 | 获取活体类型/光线资源,网络异常(请求未到达后台) |
33200 | 网络异常 | 获取活体类型/光线资源,后台返回参数有误(请求到达后台) |
WBFaceErrorDomainNativeProcess
Code(错误码) | Description(描述) | Reason(详细实际原因) |
43000 | 用户取消 | 回到后台/单击home/左上角/上传时左上角取消 |
43001 | 无法获取唇语数据 | 获取数字活体的数字有问题 |
43002 | 权限异常,未获取权限 | 相机 |
43003 | 相机运行中出错 | - |
43004 | 视频录制中出错 | 不能存/启动失败/结束失败 |
43005 | 请勿晃动人脸,保持姿势 | 未获取到最佳图片 |
43006 | 视频大小不满足要求 | 视频大小不满足要求 |
43007 | 超时 | 预检测/动作活体 |
43008 | 检测中人脸移出框外 | 活体/数字/反光 |
43009 | 光线活体本地错误 | - |
43010 | 风险控制超出次数 | 用户重试太多次 |
43011 | 没有检测到读数声音 | 数字活体过程中没有发声 |
43012 | 初始化模型失败,请重试 | 初始化算法模型失败 |
43013 | 初始化sdk异常 | WbCloudFaceVerifySdk未被初始化 |
43014 | 简单模式本地加密失败 | 编码转换异常/加解密编码失败 |
WBFaceErrorDomainCompareNetwork
Code(错误码) | Description(描述) | Reason(详细实际原因) |
53100 | 网络异常 | 对比时,网络异常(请求未到达后台) |
53200 | 网络异常 | 对比时,后台返回参数有误(请求到达后台) |
WBFaceErrorDomainCompareServer
Code(错误码) | Description(描述) | Reason(详细实际原因) |
其他错误码 | 透传后台错误码 | - |
接入示例
权威库网纹图片比对、自带对比源对比接入示例:
# 在DemoPage中单击某个按钮的代码逻辑://先填好数据let inputData = new InputData(orderNo,this.appId,'1.0.0',this.nonce,this.userId,sign,this.licence,faceId)//设置必需参数let wbFaceVerifyConfig = new WbFaceVerifyConfig(inputData);//是否打开sdk日志开关wbFaceVerifyConfig.isEnableLog = true;WbCloudFaceVerifySdk.getInstance().initWillSdk(getContext(), wbFaceVerifyConfig, {onLoginSuccess: () => {DemoLog.i(this.TAG, `onLoginSuccess:`)WbCloudFaceVerifySdk.getInstance().startWbFaceVerifySdk(getContext(), {onFinish: (_result: WbFaceVerifyResult) => {DemoLog.i(this.TAG, `WbCloudFaceVerifySdk onFinish`)//todo 处理刷脸结果……//处理完后释放sdk//【特别注意】请在拿到sdk结果后对sdk进行释放,不要在页面结束时释放,避免未能获取刷脸回调结果的情况WbCloudFaceVerifySdk.getInstance().release();}})},onLoginFail: (error: WbFaceError) => {DemoLog.e(this.TAG, `onLoginFailed:JSON.stringify(error)`)//todo 处理登录错误逻辑……//【特别注意】请在拿到sdk结果后对sdk进行释放,不要在页面结束时释放,避免未能获取刷脸回调结果的情况WbCloudFaceVerifySdk.getInstance().release();}})