Harmony NEXT 意愿核身接入

最近更新时间:2024-12-06 18:12:12

我的收藏

开发准备

权限

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_ID
public appId: string;
//openapi Version
public version: string;
//32位随机字符串
public nonce: string;
//User id
public userId: string;
//签名信息
public sign: string;
////在意愿核身控制台内申请
public licence: string;
}
关于接口调用的示例可参考 接入示例

接口参数说明

InputData 对象说明

InputData 是用来给 SDK 传递必须参数所需要使用的对象,合作方需要往里塞入SDK 需要的一些数据以便启动刷脸 SDK。
其中 InputData 对象中的各个参数定义如下表,请合作方按下表标准传入对应的数据。
参数
说明
类型
长度(字节)
是否必填
faceId
刷脸id号,由合作方向意愿识别后台拉取获得
String
-
orderNo
订单号,合作方订单的唯一标识
String
32
appId
业务流程唯一标识,即wbappid,可参考 获取WBappid 指引在意愿核身控制台内申请
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();
}
})