Harmony接入

使用限制

• 刷脸应用必须运行在Harmony Next 4.1及以上版本。

• 不支持模拟器模式调试。

• 建议使用手机端集成，SDK未适配平板可能存在兼容性问题。

权限说明

Harmony SDK权限说明如下：

依赖配置

方式一：通过 OpenHarmony 三方库中心仓依赖（推荐）

直接从 OpenHarmony 三方库中心仓拉取已发布的 HAR 包。该方式无需本地管理产物，版本升级仅需修改版本号。

1. 在 entry/oh-package.json5 文件的 dependencies 节点中声明直接引用的模块：

   {
     "name": "entry",
     "version": "1.0.0",
     "dependencies": {
       "@antdigital/authbase": "2.3.48-26051508",
       "@antdigital/aliyunfacade": "2.3.48-26051508"
     }
   }

   说明

   • 仅需显式声明源码中直接 import 的模块。例如，@antdigital/aliyunfacade 会通过传递依赖自动引入 livenessverify 和 ocrverify，无需在此处重复列出。

   • 根目录下的 oh-package.json5 文件无需配置 overrides 字段。

2. 执行以下命令完成安装：

   ohpm install

方式二：本地 HAR 集成

1. 下载Harmony SDK并解压。

   该SDK为Harmony的har包。

2. 将 SDK 构建产物放置于工程根目录的 libs/ 文件夹下，目录结构示例如下：

   libs/
   ├── authbase.har
   ├── livenessverify.har
   ├── ocrverify.har
   └── aliyunfacade.har

3. 在根目录 oh-package.json5 文件中添加 overrides 字段，强制将依赖解析为本地 HAR 包：

   {
     "modelVersion": "5.0.0",
     "name": "facedemo",
     "version": "1.0.0",
     "dependencies": {},
     "devDependencies": {
       "@ohos/hypium": "1.0.11"
     },
     "overrides": {
       "@antdigital/authbase": "file:./libs/authbase.har",
       "@antdigital/livenessverify": "file:./libs/livenessverify.har",
       "@antdigital/ocrverify": "file:./libs/ocrverify.har",
       "@antdigital/aliyunfacade": "file:./libs/aliyunfacade.har"
     }
   }

4. 在 entry/oh-package.json5 中声明依赖项。版本号可保留远程版本号字符串（系统会优先应用 overrides 规则从本地拉取），或直接使用 file: 相对路径。

5. 执行以下命令完成安装：

   ohpm install

接口说明

Harmony SDK包含初始化（init、initIPv6）、获取MetaInfos（getMetaInfos）和开始认证（verify）3个核心接口。

认证结果及错误码

认证结果通过ZIMResponse类返回，定义如下：

/*
 * 结果返回
 */
export class ZimResponse {
 /**
 * 结果码主码
 */
 public code: string;

 /**
 * 结果码子码
 */
 public subCode: string;

 /**
 * 错误原因
 */
 public msg: string;

 /**
 * 留证视频路径
 */
 public videoPath: string;
}

更多subCode错误码信息，请参见金融级客户端错误码详情 - Harmony。

接口混淆配置

为避免接口被混淆而造成功能异常，请查看har包中obfuscation.txt文件中的配置，请勿移除该文件。同时在应用的主工程打包添加如下混淆配置文件 obfuscation-rules.txt 添加如下配置：

ctx
userAppKey
options
securityInitListener
initRaw
getSessionRaw
getSessionIdRaw
setInitStatusRaw
getInitStatusRaw
setOptionsRaw

示例代码

import { ZimConstant, ZimFacade, ZimResponse } from '@alipay/aliyunfacade';
import { HashMap } from '@kit.ArkTS';
import { JSONUtil, StringUtil } from '@alipay/authbase';

@Entry
@Component
struct Index {
  @State message: string = '发起认证';
  @State certifyID: string = ''

  build() {
    Row() {
      Column() {
        // certifyID需要从服务端InitFaceVerify接口的返回值中获取，每次获取需要将MetaInfo传给服务端。
        // 注意每个certifyID仅有30分钟有效期，过期后不能使用。
        TextInput({ placeholder: '请输入certifyID', text: this.certifyID })
          .onChange((value: string) => {
            this.certifyID = value;
          })
          .margin({ left: 20, right: 20 })
        Button(this.message)
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
          .onClick((event: ClickEvent) => {
            let params: HashMap<string, string> = new HashMap();
            // SDK 全屏显示，默认为true
            params.set(ZimConstant.KEY_NEED_FULL_SCREEN, 'true');
            // SDK 展示对客弹窗信息，默认为true
            params.set(ZimConstant.KEY_USE_MESSAGE_BOX, 'true');
            ZimFacade.verify(this.getUIContext(), this.certifyID, {
              onComplete: (response: ZimResponse) => {
                let result: HashMap<string, string> = new HashMap();
                result.set('code', response.code);
                result.set('subCode', response.subCode);
                result.set('msg', response.msg);
                result.set('certifyID', this.certifyID);
                this.certifyID = '';
                if (response.faceImage) {
                  result.set('faceImage', 'data:image/jpg;base64,' + StringUtil.base64Uint8Array(response.faceImage))
                } else {
                  result.set('faceImage', '');
                }
                let showParams: string = JSONUtil.parseMapToString(result);
                console.log("Aliyun", showParams);
              }
            }, params)
          })
          .margin({ top: 10 })
      }
      .width('100%')
    }
    .height('100%')
  }

  aboutToAppear(): void {
    ZimFacade.init(getContext());
  }
}

Demo代码包

开启安全摄像头能力

HarmonySDK 从 1.3.2 版本开始支持安全摄像头能力。此能力需要针对 APP 在 Harmony 官网开启如下配置：

• 可信应用服务

  可信应用服务邮件申请格式参考

  xxxx业务申请使用可信应用服务。可信应用服务申请材料清单如下：

  Developer ID：xxxxx

  公司名称： xxxxx有限公司

  应用名称：com.xxxxxx（xxxxx应用）

  申请使用的服务：可信应用服务

  使用该服务的场景：实人活体刷脸安全增强

• 应用设备状态检测

• 安全检测服务

具体操作方法，请参考Harmony官方文档：开通Device Security服务。