目录

@hms.core.account.realName (Identity Verification Service)

Module Overview

The @hms.core.account.realName module provides the identity verification capability of Account Kit. It enables face-based identity verification, allowing you to verify the HUAWEI ID user identity through facial recognition. When you need to perform high-risk operations based on the current HUAWEI ID, you can use this capability to launch the face-based identity verification screen. Account Kit will verify the current device user's identity by matching their facial features against the facial information associated with the HUAWEI ID.

Since: 5.0.0(12)

This API is temporarily unavailable.

Modules to Import

import { realName } from '@kit.AccountKit';

FacialRecognitionVerificationRequest

Request for face-based identity verification. As an input parameter of startFacialRecognitionVerification, it needs to include the identity verification token, which is used to match the user's facial features with the information associated with the HUAWEI ID.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.AuthenticationServices.HuaweiID.RealNameVerify

Since: 5.0.0(12)

Name Type Read-Only Optional Description
verificationToken string No No Identity verification token, which is obtained by calling the API provided by the OpenRealName service for real-name information verification. The value contains 1 to 2048 characters.
state string No Yes

state parameter in the request body. You can set this parameter to a string of digits (0–9), letters (a–z or A–Z), dots (.), colons (:), slashes (/), and underscores (_). The length limit is 1 to 255 characters. The verification rule is ^[0-9a-zA-Z:/\.\-_]{1,255}$. This parameter will be compared with the state parameter in the response body to check whether the request corresponds to the current session, thereby preventing cross-site attacks.

You are advised to use nonces and perform consistency verification. util.generateRandomUUID() is recommended.

Example:

import { realName } from '@kit.AccountKit';
import { util } from '@kit.ArkTS';

const request: realName.FacialRecognitionVerificationRequest = {
  verificationToken: 'xxx', // Call the real-name information verification API of the OpenRealName service to obtain this token.
  state: util.generateRandomUUID() // You are advised to use generateRandomUUID to generate the state, which can be used for consistency comparison to prevent cross-site attacks.
};

FacialRecognitionVerificationResult

Response to face-based identity verification request. It is the return value of startFacialRecognitionVerification upon successful face-based identity verification.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.AuthenticationServices.HuaweiID.RealNameVerify

Since: 5.0.0(12)

Name Type Read-Only Optional Description
facialRecognitionVerificationToken string Yes No Face-based identity verification token, which is returned after successful verification. The value contains 1 to 2048 characters.
state string Yes Yes

state parameter returned in the response body. The value is a string of digits (0–9), letters (a–z or A–Z), dots (.), colons (:), slashes (/), and underscores (_). The length limit is 1 to 255 characters. The verification rule is ^[0-9a-zA-Z:/\.\-_]{1,255}$. This state will be compared with state in the request body to check whether the request corresponds to the current session, thereby preventing cross-site attacks.

You are advised to use nonces and perform consistency verification. util.generateRandomUUID() is recommended.

RealNameErrorCode

Enumerates error codes related to identity verification service APIs provided by Account Kit.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.AuthenticationServices.HuaweiID.RealNameVerify

Since: 5.0.0(12)

Name Value Description
NETWORK_ERROR 1002500001 The network is unavailable.
ACCOUNT_NOT_LOGGED_IN 1002500002 The user has not signed in with their HUAWEI ID.
PACKAGE_FINGERPRINT_CHECK_ERROR 1002500003 The certificate fingerprint of the app fails to be verified.
PERMISSION_CHECK_ERROR 1002500004 The app does not have the required permissions.
USER_CANCELED 1002500005 The user cancels verification.
INTERNAL_ERROR 1002500006 Internal error.
REAL_NAME_UNSUPPORTED 1002500008 The HUAWEI ID does not support identity verification.
REAL_NAME_VERIFICATION_ERROR 1002500009 Failed to validate the identity verification channel.
FACE_NOT_MATCH 1002500011 The user's face does not match the facial image used as proof of identity.
REAL_NAME_NOT_EXIST 1002500012 The real-name information associated with the HUAWEI ID is not found.
NAME_AND_ID_NUMBER_NOT_MATCH 1002500013 The name does not match the ID card number.
TOO_MANY_ATTEMPTS 1002500014 Too many identity verification attempts. Try again 24 hours later.
VERIFICATION_TOKEN_INCORRECT 1002500015 The verificationToken parameter is invalid.
DEVICE_NOT_SUPPORTED 1002500016 The device does not support this API.

startFacialRecognitionVerification

startFacialRecognitionVerification(context: common.Context, request: FacialRecognitionVerificationRequest): Promise<FacialRecognitionVerificationResult>

Verifies the HUAWEI ID user identity through facial recognition. You can call this API to launch the facial verification screen, which allows users to remain active for an extended period. When the HUAWEI ID user's facial features are successfully matched, a success object is returned asynchronously through a promise. To use this API, the HUAWEI ID user must have completed identity verification and facial verification.

This API is currently not available for child accounts.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.AuthenticationServices.HuaweiID.RealNameVerify

Device behavior differences: This API is supported on phones, PCs/2-in-1 devices, and tablets. On other devices, it returns error code 801.

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
context common.Context Yes

Context.

The following contexts are supported for apps: UIAbilityContext and UIExtensionContext. Apps cannot use UIExtensionContext in non-full-screen components such as sheets, pop-ups, and sub-windows.

The following context is supported for atomic services: UIAbilityContext.
request FacialRecognitionVerificationRequest Yes Object for requesting face-based identity verification, which must contain information such as the token.

Returns

Type Description
Promise<FacialRecognitionVerificationResult> Promise used to return the FacialRecognitionVerificationResult object. If this object is returned, face-based identity verification is successful. You can compare the state values in this object and the request object to check whether the request corresponds to the current session, thereby preventing cross-site attacks.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801

Capability not supported. Function startFacialRecognitionVerification can not work correctly due to limited device capabilities.

Applicable versions: 5.1.1(19)+
1002500001 The network is unavailable.
1002500002 The user has not logged in with HUAWEI ID.
1002500003 Failed to check the fingerprint of the application bundle.
1002500004 The application does not have the required permissions.
1002500005 The user canceled the verification of the HUAWEI ID.
1002500006 Internal error.
1002500008 Real-name verification is not supported for the HUAWEI ID.
1002500011 Your face does not match your facial image as proof of identity.
1002500012 No real-name information is found for the HUAWEI ID.
1002500013 Your name and ID number do not match.
1002500014 Too many real-name verification attempts.
1002500015 The verificationToken parameter is incorrectly set.
1002500016 This device does not support this API.

Example:

import { realName } from '@kit.AccountKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { util } from '@kit.ArkTS';

const request: realName.FacialRecognitionVerificationRequest = {
  verificationToken: 'xxx', // Call the real-name information verification API of the OpenRealName service to obtain this token.
  state: util.generateRandomUUID() // You are advised to use generateRandomUUID to generate the state, which can be used for consistency comparison to prevent cross-site attacks.
};
hilog.info(0x0000, 'testTag', `verifyFacialRecognitionWithPromise params ${request}`);
// The following provides only code snippets. Use it in the custom component instance and pass a valid context object.
realName.startFacialRecognitionVerification(this.getUIContext().getHostContext(), request).then(data => {
  const verifyResult = data as realName.FacialRecognitionVerificationResult;
  // Process verifyResult.
  hilog.info(0x0000, 'testTag', 'Succeeded in verifying facial recognition.');
}).catch((error: BusinessError<Object>) => {
  dealAllError(error);
});

// Handle the error.
function dealAllError(error: BusinessError<Object>): void {
  hilog.error(0x0000, 'testTag',
    `Failed to verify facial recognition. Code: ${error.code}, message: ${error.message}`);
  // In scenarios involving UI interactions, it is advised to guide users with the following error code prompts.
  if (error.code === realName.RealNameErrorCode.ACCOUNT_NOT_LOGGED_IN) {
    // Not signed in with a HUAWEI ID. Sign in with a HUAWEI ID and try again.
  } else if (error.code === realName.RealNameErrorCode.NETWORK_ERROR) {
    // Network error. Check the network connection and try again.
  } else if (error.code === realName.RealNameErrorCode.USER_CANCELED) {
    // The user cancels the face-based identity verification.
  } else {
    // Face-based identity verification failed. Try again later.
  }
}