HarmonyOS-服务端接入指南
前言
【本文】方案集成指南适用于需要集成APP方案，实现权威库核验、自传照片人脸比对、仅活体检测这3个业务需求时来参考。百度人脸实名认证APP方案默认开启风控功能，即使用人脸识别V4系列API接口接受SDK端传入本地环境扫描的设备指纹及安全信息，对SDK端进行设备风险识别，辨别是否为⻛险设备、并返回识别结果。此方案可有效防御黑产批量虚拟机、病毒侵入等攻击手段，降低第三方黑产攻破概率，提升业务安全性。
快速定位
1. 文档说明
| 文档名称 | 人脸实名认证APP方案 6.4版本集成文档 |
|---|---|
| 所属平台 | HarmonyOS |
| 提交日期 | 2024-09-03 |
2. 版本说明
| 名称 | 版本号 |
|---|---|
| 名镜方案 | 6.4.0 |
| 系统支持 | HarmonyOS NEXT.0.0.36 |
3. SDK说明
| 文件名称 | 版本号 | 说明 |
|---|---|---|
| lib_Enhance.har | 人脸实名认证SDK业务逻辑封装 | 包含人脸采集、安全风控等功能 |
4. 配置包名和签名
- 从百度云控制台下载鸿蒙Demo之后，需要在build-profile.json5中配置好宿主应用的签名信息，更新宿主应用的所有签名信息material
5. SDK集成与授权
- 首先在app工程中增加3. SDK说明中的依赖库资源
- 其次将百度云控制台创建应用时获取的人脸授权文件(idl-license.face-harmony)、大数据风控密钥文件(idl-key.face-android)、本地配置文件(local_config.json)、质量控制配置文件(quality_config.json)放置于rawfile目录下。
- 最后参考控制台下载的工程以及相关接口说明完成SDK集成。
6. 人脸相关接口
6.1 人脸初始化接口（SDK）
初始化接口调用
| 返回值 | API | 描述 |
|---|---|---|
| void | init(context: Context, licenseKey: string, licenseName: string, keyName: string, faceInitCallback: FaceInitCallback) | 人脸初始化接口 |
入参说明
| 参数 | 类型 | 说明 |
|---|---|---|
| context | Context | 上下文 |
| licenseKey | String | 授权Key |
| licenseName | String | 授权文件名称 |
| keyName | String | 加解密文件名称 |
onCallback回调说明
| 参数 | 类型 | 含义 | 值 |
|---|---|---|---|
| resultCode | int | 错误码 | 1000为成功，其他为失败，详情参考resultCode错误码说明 |
| resultMsg | String | 详情见resultCode错误码说明 |
resultCode错误码说明
| resultCode | resultMsg | 自查方案 |
|---|---|---|
| 1001 | License未初始化 | 请按照集成文档说明完成SDK初始化 |
| 1002 | License数据解密失败 | 请检查License文件是否正确 |
| 1003 | Licesen数据格式错误 | 请检查license文件内容有被修改过 |
| 1004 | License-Key校验错误 | 请检查工程代码初始化参数中的licenseId，和控制台下载工程里面的licenseId是否匹配 |
| 1006 | 鸿蒙应用指纹校验错误 | 请检查工程所使用的签名文件，和控制台填写的签名信息是否匹配 |
| 1008 | 鸿蒙bundleName应用名称校验错误 | 请检查工程代码中的bundleName（包名）和控制台填写的鸿蒙包名信息是否匹配 |
| 1009 | 过期时间不正确 | 请提交工单或者线下联系百度产研人员 |
| 1011 | 授权已过期 | 请查看当前设备时间是否已不在授权文件有效期内 |
| 1012 | 本地文件读取失败 | 请检查授权文件名称以及路径 |
| 1013 | 本地鉴权失败 | 1）请检查工程代码中的bundleName（包名）和控制台填写的鸿蒙包名是否匹配；2）请检查工程所使用的签名文件，和控制台填写的签名信息是否匹配 |
| 1014 | 本地时间校验错误 | 请检查当前设备时间是否早于实际时间 |
6.3 人脸信息加密采集接口
- 包含本地质量和本地活体，本地质量可以确保采集到的人脸图像符合各条件校验（满足姿态角、光照、模糊度、遮挡等校验），本地活体分静默活体、炫瞳活体、动作活体三种。
- 此处最终采集到的数据经过加密处理，需要配合服务端的 人脸实名认证V4 或 人脸对比V4 或 在线图片活体V4 来使用。分别用来实现「权威数据源身份信息核验」、「本地图片无源比对」以及「仅活体检测」，适用于不同的业务场景需要。
- sKey、xDeviceId、data 为此接口的成功回调结果信息，作为上述3个服务端接口重要字段入参
| 返回值 | API | 描述 |
|---|---|---|
| void | startFaceCollect(params: HashMap<string, Object>, faceServiceCallbck: FaceServiceCallbck) | 人脸采集接口 |
onCallback回调说明
| 参数 | 类型 | 含义 | 值 |
|---|---|---|---|
| resultCode | int | 错误码 | 0为成功，其他为失败，详情参考实名认证resultCode错误码说明 |
| resultMap | HashMap | 回调结果Map | 详情见下表 |
resultMap key值列表说明：
| Key值 | 类型 | 含义 |
|---|---|---|
| resultMsg | String | 详情见resultCode错误码说明 |
| sKey | String | 安全相关：sKey |
| xDeviceId | String | 安全相关：xDeviceId |
| data | String | 安全相关数据 |
7. 人脸释放接口（SDK）
在完成加密信息采集后，用于释放SDK，实现对采集功能、模型的释放，减小内存。
| 返回值 | API | 描述 |
|---|---|---|
| void | release() | 人脸释放接口 |
权限
| 名称 | 说明 | 必选 |
|---|---|---|
| 需要动态申请的权限 | ||
| ohos.permission.CAMERA | 拍照权限 | 是 |
| 不需要动态申请的权限 | ||
| ohos.permission.INTERNET | 允许访问网络 | 是 |
常见问题
如何获取鸿蒙应用指纹
（1）方法1，测试证书
- “应用指纹”signatureInfo.fingerprint是鸿蒙应用签名证书(.cer文件)的SHA-256hash值，当前支持获取本应用的“应用指纹”。示例代码如下：
import { bundleManager } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
let bundleFlags = bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_SIGNATURE_INFO;
try {
bundleManager.getBundleInfoForSelf(bundleFlags).then((data) => {
hilog.info(0x0000, 'testTag', 'getBundleInfoForSelf successfully. Data: %{public}s', JSON.stringify(data));
//data里可以获取到signatureInfo，即应用的签名证书信息
}).catch((err: BusinessError) => {
hilog.error(0x0000, 'testTag', 'getBundleInfoForSelf failed. Cause: %{public}s', err.message);
});
} catch (err) {
let message = (err as BusinessError).message;
hilog.error(0x0000, 'testTag', 'getBundleInfoForSelf failed: %{public}s', message);
}（2）方法2，测试证书+发布证书
- 在项目级build-profile.json5文件中，signingConfigs字段内的profile的值即为签名文件的存储路径。
- 打开该签名文件（后缀为.p7b），打开后在文件内搜索“-certificate”，将“-----BEGIN CERTIFICATE-----”和“-----END CERTIFICATE-----”以及中间的信息拷贝到新的文本中，注意换行并去掉换行符，保存为一个新的.cer文件，如命名为xxx.cer。：
- 使用keytool工具（在DevEco Studio安装目录下的jbr/bin文件夹内），执行如下命令通过.cer文件获取证书指纹的SHA256值。
keytool -printcert -file xxx.cer - 将证书指纹中SHA256的内容去掉冒号，即为最终要获得的签名指纹。
verify_token的详细说明
（1）access_token 有效期为 30 天，重复生成 access_token 的话，对之前的不影响，依旧能使用；access_token 与verify_token 是包含关系，即 verify_token 是由 access_token生成的，如果一个 verify_token 是和一个不匹配的 access_token 使用，会提示“Token无效或者已过期”
（2）verify_token 的核验有效期为 2 小时，在有效期内可以进行了核验动作，如果超过了 2 小时没有使用该 token 进行核验的话会提示“Token无效或者已过期”
（3） verify_token 核验完毕后（核验成功，或设置了认证未通过时URL失效），无法再进行核验，如果再次进行核验，会提示“Token无效或者已过期”
（4） verify_token 核验完毕后（核验成功，或设置了认证未通过时URL失效），支持对后验接口的查询，有效期均为 3 天，3 天后再次查询后验接口，会提示“Token无效或者已过期”
获取认证人脸、查询认证结果、核验及计费信息获取接口持续返回错误码18，提示openapi限制，且有返回logid
答：检查APP方案依赖的“人脸实名认证V4”、“人脸对比V4”、“在线图片活体检测V4” 三项付费接口，是否有免费额度，或者直接开通后付费，以消除该报错提示。开通后，再进行重试。