Harmony接入

使用限制

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

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

权限说明

Harmony SDK权限说明如下：

依赖配置

1. 下载Harmony SDK并解压。

   该SDK为Harmony的har包。

2. 将HAR文件复制到存放HAR包的工程目录中。

   建议参考鸿蒙官方文档放至libs目录下，在工程根目录的oh-package.json5添加认证包的版本依赖树管理，示例如下：

   

3. 修改项目工程中的oh-package.json5文件，在dependencies中添加AliyunFacade、AuthBase、LivenessVerify、OcrVerify、AliyunFaceGuard依赖包，示例如下：

   说明

   代码示例中xxx表示版本号，使用过程中，请替换为SDK包中文件的实际版本号。

   {
     ....
     "dependencies": {
       "AliyunFacade" : "file:./libs/AliyunFacade-xxx.har",
       "AuthBase" : "file:./libs/AuthBase-xxx.har",
       "LivenessVerify" : "file:./libs/LivenessVerify-xxx.har",
       "OcrVerify": "file:./libs/OcrVerify-xxx.har",
       "AliyunFaceGuard": "file:./libs/AliyunFaceGuard-xxx.har"
       ....
     }
   }

接口说明

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

初始化SDK

• 描述：调用该函数完成SDK内部初始化。请务必做延迟初始化配置，确保在用户同意《隐私权政策》后，在人脸识别业务场景中初始化SDK。

• 函数原型：

  public init(context: Context, params?: HashMap<string, string>): number
  public initIPv6(context: Context, params?: HashMap<string, string>): number

  说明

  请根据实际情况选用IPv4或者IPv6网络环境进行业务调用。

• 参数说明：

  名称	类型	说明
  context	Context	当前Ability的Context。
  params	HashMap<string, string>	自定义参数，可不传。

• 返回值：Number类型。0表示初始化无异常。

获取metaInfos

• 描述：移动端环境信息会发送至业务服务器端，业务服务器端将这些信息作为参数之一（MetaInfos）调用服务端初始化认证接口，从而获取认证报文，用于后续认证环节。

• 函数原型：

  public static getMetaInfos(context: Context, params?: HashMap<string, string>): string

• 参数说明：

  名称	类型	说明
  context	Context	当前Ability的Context
  params	HashMap<string, string>	自定义参数，可不传。

• 返回值：String类型，以JSON格式返回当前移动设备端环境以及SDK信息。

  {
   "deviceType": "harmony",
   "osVersion": "2",
   "osFullName": "2.1.6.1(Beta1)",
   "deviceModel": "NOH-AN00",
   "appName": "com.dtf.faceverify",
   "appVersion": "1.0.0",
   "nfcSupport": "N",
   "bioMetaInfo": "7.1.2:393216,0",
   "apdidToken": "",
   "sdkVersion": "1.1.0",
   "securityVersion": "",
   "zimVer": "",
   "voiceSdkVersion": ""
  }

发起认证

• 描述：调用该函数发起实人认证。

• 函数原型：

  public static verify(context: UIContext | Context, callBack: ZimCallBack, params?: HashMap<string, string>): void

• 参数说明：

  名称	类型	说明
  context	UIContext 或 Context	当前Ability的UIContext或Context。 重要 请优先传递UIContext，可避免Harmony系统兼容性的问题。
  certifyID	String	认证ID。您可以通过服务端发起申请请求接口（InitFaceVerify）获取该参数。
  callBack	ZimCallBack	认证结果的回调接口，定义如下： export interface ZimCallBack { onComplete: (response: ZimResponse) => void; encrypt: (content: string) => string; } ZIMResponse类的定义，请参见下文认证结果及错误码。
  params	HashMap<string, string>	自定义参数，需要根据要求传入数据。params取值，请参见表 2. params取值说明。

  表 1. ZimCallBack接口回调说明

  方法	说明	示例值
  onComplete	SDK认证结果回调	参考ZimResponse类定义

  表 2. params取值说明

  取值	说明	示例值
  ext_params_key_use_message_box	当刷脸认证过程中出现异常情况，是否使用SDK内部的弹框提示。取值： true：SDK先弹框提示，确定之后，返回错误code。 false：不弹提示框，直接返回错误code，客户业务应用App自行决定如何提示。	true
  ext_params_key_open_full_screen	进入SDK认证后是否开启全屏显示，SDK默认会开启全屏显示以保证显示正常。设置单次有效。 true：开启全屏显示。 false：关闭全屏显示。	true
  ext_params_key_use_video	是否返回活体认证视频。取值： true：可在response.videoPath或在服务端查询接口获取视频路径。 false：不返回活体认证视频（默认）。	true或者false

• 返回值：无。

认证结果及错误码

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

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

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

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

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

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

接口混淆配置

为避免接口被混淆而造成功能异常，请查看har包中obfuscation.txt文件中的配置，请勿移除该文件。

示例代码

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

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

  build() {
    Row() {
      Column() {
        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代码包

下载最新版本Harmony Demo。