Harmony integration

Limitations

• The face verification app must run on Harmony Next 4.1 or later.

• Debugging in emulator mode is not supported.

• We recommend integrating this SDK on mobile phones. It is not optimized for tablets and may have compatibility issues.

Permissions

The Harmony SDK requires the following permissions:

Dependency configuration

Method 1: Dependency through the OpenHarmony package repository (Recommended)

Pull published HAR packages directly from the OpenHarmony package repository. This method eliminates local artifact management and requires only version number changes for upgrades.

1. In the entry/oh-package.json5 file, declare the directly referenced modules in the dependencies node:

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

   Note

   • You only need to explicitly declare modules that are directly imported in your source code. For example, @antdigital/aliyunfacade automatically brings in livenessverify and ocrverify as transitive dependencies, so you do not need to list them here.

   • The oh-package.json5 file in the root directory does not require the overrides field.

2. Run the following command to complete the installation:

   ohpm install

Method 2: Local HAR integration

1. Download and unzip the Harmony SDK.

   The SDK is a Harmony har package.

2. Place the SDK build artifacts in the libs/ folder under the project root directory. The directory structure example is as follows:

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

3. In the root directory oh-package.json5 file, add the overrides field to force dependency resolution to local HAR packages:

   {
     "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. In entry/oh-package.json5, declare the dependencies. You can keep the remote version number string (the system will prioritize the overrides rule to pull from local), or directly use file: relative paths.

5. Run the following command to complete the installation:

   ohpm install

API reference

The Harmony SDK includes three core APIs: initialization (init and initIPv6), getting meta information (getMetaInfos), and starting verification (verify).

Verification results and error codes

The verify API returns the verification result in a ZimResponse object, which is defined as follows:

/*
 * Result response
 */
export class ZimResponse {
 /**
 * Main result code
 */
 public code: string;

 /**
 * Sub-result code
 */
 public subCode: string;

 /**
 * Error reason
 */
 public msg: string;

 /**
 * Video evidence path
 */
 public videoPath: string;
}

For more information about subCode error codes, see Client-side error codes for financial-grade services - Harmony.

API obfuscation configuration

To avoid functional issues caused by API obfuscation, review the configuration in the har package's obfuscation.txt file. Do not remove this file. Also, add the following configuration to the obfuscation-rules.txt file in your application's main project:

ctx
userAppKey
options
securityInitListener
initRaw
getSessionRaw
getSessionIdRaw
setInitStatusRaw
getInitStatusRaw
setOptionsRaw

Sample code

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 = 'Start authentication';
  @State certifyID: string = ''

  build() {
    Row() {
      Column() {
        // The certifyID is obtained from the return value of the InitFaceVerify API on the server. You must pass MetaInfo to the server each time you obtain it.
        // Note: Each certifyID is valid for only 30 minutes.
        TextInput({ placeholder: 'Enter 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();
            // Enable SDK full-screen display. The default value is true.
            params.set(ZimConstant.KEY_NEED_FULL_SCREEN, 'true');
            // Enable SDK dialog box display. The default value is 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 package

Enable the secure camera feature

Starting from version 1.3.2, the Harmony SDK supports the secure camera feature. To use this feature, you must enable the following configurations for your app on the official Harmony website:

• Trusted Application Service

  Sample email application format for Trusted Application Service

  [Your Business Name] is applying to use the Trusted Application Service. The application materials are as follows:

  Developer ID: [Your Developer ID]

  Company Name: [Your Company Name] Co., Ltd.

  App Name: com.xxxxxx ([Your App Name])

  Requested Service: Trusted Application Service

  Use Case: Enhanced security for real person authentication, including liveness detection and face verification.

• App and Device Status Check

• Security Check Service

For specific instructions, see the official Harmony documentation: Enable the Device Security service.