目录

@hms.core.account.extendService (Enhanced Service)

Module Overview

The @hms.core.account.extendService module delivers enhanced Account Kit capabilities beyond basic sign-in and authorization, offering apps more comprehensive account management and security verification capabilities. Its two core functionalities are identity verification and launching the account center.

You can use the verifyAccount and startAccountCenter APIs provided by the @hms.core.account.extendService module to implement the preceding capabilities.

Since: 4.0.0(10)

This service is available only to system apps currently.

Modules to Import

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

IdType

Enumerates the ID types of a HUAWEI ID user. Currently, IdType.UNION_ID and IdType.OPEN_ID are supported.

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 4.1.0(11).

System capability: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

Since: 4.0.0(10)

Name Value Description
USER_ID 1

UID of a HUAWEI ID user.

Note: This parameter is available only to system apps.
OPEN_ID 2 OpenID of a HUAWEI ID user. For details about the format requirements, please refer to Formats of OpenID and UnionID.
UNION_ID 3 UnionID of a HUAWEI ID user. For details about the format requirements, please refer to Formats of OpenID and UnionID.

RiskLevel

Enumerates risk levels.

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 4.1.0(11).

System capability: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

Since: 4.0.0(10)

Name Value Description
LOW 1 Low risk.
HIGH 2 High risk.

VerifyRequest

Defines the identity verification request. As an input parameter of the verifyAccount API, VerifyRequest contains the user's basic identity information for identity comparison with the HUAWEI ID user signed in on the device. You can set properties such as the scenario ID and risk level to control the number of verifications and the verification methods. Account Kit will launch the corresponding identity verification screen based on these properties.

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 4.1.0(11).

System capability: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

Since: 4.0.0(10)

Name Type Read-Only Optional Description
idType IdType No No ID type of a HUAWEI ID user. For non-system apps, only IdType.UNION_ID and IdType.OPEN_ID are supported currently.
idValue string No No

UnionID or OpenID of a HUAWEI ID. The ID type is specified by the idType property. The value contains 1 to 256 characters.

The UnionID or OpenID can be obtained through the capability of sign-in with a HUAWEI ID, obtaining user information associated with a HUAWEI ID, HUAWEI ID sign-in panel component, or HUAWEI ID sign-in button component.
sceneId string No No Scenario ID for identity verification. This property and the riskLevel property together represent a set of configurations of an app on the Account Kit server, including the number of verifications, first verification method, and secondary verification method. The value contains 1 to 10 characters.
riskLevel RiskLevel No No Risk level. This property and the sceneId property together represent a set of configurations of an app on the Account Kit server. Generally, secondary verification is required in high-risk scenarios.
nonce string No No

nonce in the request body. The value contains 1 to 64 characters. This property is contained in the returned verifyToken and can be used to prevent replay attacks through consistency verification.

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

Example:

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

// Create request parameters.
const request: extendService.VerifyRequest = {
  idType: extendService.IdType.UNION_ID,
  idValue: 'xxx', // The value can be obtained through the HUAWEI ID sign-in API.
  sceneId: 'xxx', // ID of a scenario that triggers identity verification.
  riskLevel: extendService.RiskLevel.LOW,
  nonce: util.generateRandomUUID() // You are advised to use generateRandomUUID to generate a nonce.
};

VerifyResult

Defines the identity verification response. It is the return value of the verifyAccount API upon a successful user 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 4.1.0(11).

System capability: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

Since: 4.0.0(10)

Name Type Read-Only Optional Description
verifyToken string Yes No Token returned for identity verification, which is in JWT format.

Example:

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

// Create request parameters.
const request: extendService.VerifyRequest = {
  idType: extendService.IdType.UNION_ID,
  idValue: 'xxx', // The value can be obtained through the HUAWEI ID sign-in or authorization API.
  sceneId: 'xxx', // ID of a scenario that triggers identity verification.
  riskLevel: extendService.RiskLevel.LOW,
  nonce: util.generateRandomUUID() // You are advised to use generateRandomUUID to generate a nonce.
};

// Execute the identity verification request and process the result.
try {
  // The following provides only code snippets. Use it in the custom component instance and pass a valid context object.
  extendService.verifyAccount(this.getUIContext().getHostContext(), request, (error: BusinessError, data) => {
    if (error) {
      dealAllError(error);
      return;
    }
    const verifyResult = data as extendService.VerifyResult;
    hilog.info(0x0000, 'testTag', 'Succeeded in verifying.');
    const verifyToken = verifyResult.verifyToken;
    // Process verifyToken.
  });
} catch (error) {
  dealAllError(error);
}

// Handle the error.
function dealAllError(error: BusinessError): void {
  hilog.error(0x0000, 'testTag', `Failed to verify. Code: ${error.code}, message: ${error.message}`);
}

ExtendErrorCode

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

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

System capability: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

Since: 4.0.0(10)

Name Value Description
INVALID_PARAMETER 401

Parameter check failed.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).
NETWORK_ERROR 1001600001

The network is unavailable.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).
ACCOUNT_NOT_LOGGED_IN 1001600002

The user has not signed in with their HUAWEI ID.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).
PACKAGE_FINGERPRINT_CHECK_ERROR 1001600003

The certificate fingerprint of the app fails to be verified.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).
PERMISSION_CHECK_ERROR 1001600004

The app does not have the required permissions.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).
USER_CANCELED 1001600005

The user canceled the current operation.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).
VERIFICATION_FACTOR_UNAVAILABLE 1001600006

The verification factor is not supported on the device.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).
INTERNAL_ERROR 1001600007

Internal error.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).
DEVICE_NOT_SUPPORTED 1001600011

The device does not support this API.

Since: 6.1.0(23)

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

verifyAccount

verifyAccount(context: common.Context, request: VerifyRequest, callback: AsyncCallback<VerifyResult>): void

Executes identity verification. This API returns verification credentials via an asynchronous callback upon successful verification. Calling this API launches the identity verification screen, where users need to authenticate themselves via methods such as password or SMS verification. The identity verification screen supports an extended timeout period. If verification succeeds, this API returns verification credentials to your app. In other scenarios, such as when the user closes the screen, a corresponding error code is returned.

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 4.1.0(11).

System capability: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

Since: 4.0.0(10)

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.

NOTE

- In version 4.0.0(10), the parameter type is UIAbilityContext.

- In 4.1.0(11) and later versions, the parameter type is Context.
request VerifyRequest Yes Identity verification request object, containing request parameters.
callback AsyncCallback<VerifyResult> Yes

Callback used to return the result.

If the identity verification is successful, err is undefined, and data is the obtained VerifyResult object. Otherwise, err is an error object.

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.
1001600001 The network is unavailable.
1001600002 The user has not logged in with HUAWEI ID.
1001600003 Failed to check the fingerprint of the application bundle.
1001600004 The application does not have the required permissions.
1001600005 The user canceled the current operation.
1001600006 The requested verification factors are unavailable on the device.
1001600007 Internal error.

Example:

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

// Create request parameters.
const request: extendService.VerifyRequest = {
  idType: extendService.IdType.UNION_ID,
  idValue: 'xxx', // The value can be obtained through the HUAWEI ID sign-in API.
  sceneId: 'xxx', // ID of a scenario that triggers identity verification, which is obtained through configuration application.
  riskLevel: extendService.RiskLevel.LOW,
  nonce: util.generateRandomUUID() // You are advised to use generateRandomUUID to generate a nonce.
};

// Execute the identity verification request and process the result.
try {
  // The following provides only code snippets. Use it in the custom component instance and pass a valid context object.
  extendService.verifyAccount(this.getUIContext().getHostContext(), request, (error, data) => {
    if (error) {
      dealAllError(error);
      return;
    }
    const verifyResult = data as extendService.VerifyResult;
    hilog.info(0x0000, 'testTag', 'Succeeded in verifying.');
    const verifyToken = verifyResult.verifyToken;
    // Process verifyToken.
  });
} catch (error) {
  dealAllError(error);
}

// Handle the error.
function dealAllError(error: BusinessError): void {
  hilog.error(0x0000, 'testTag', `Failed to verify. Code: ${error.code}, message: ${error.message}`);
}

verifyAccount

verifyAccount(context: common.Context, request: VerifyRequest): Promise<VerifyResult>

Executes identity verification. This API returns verification credentials asynchronously via a promise upon successful verification. Calling this API launches the identity verification screen, where users need to authenticate themselves via methods such as password or SMS verification. The identity verification screen supports an extended timeout period. If verification succeeds, this API returns verification credentials to your app. In other scenarios, such as when the user closes the screen, a corresponding error code is returned.

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 4.1.0(11).

System capability: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

Since: 4.0.0(10)

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.

NOTE

- In version 4.0.0(10), the parameter type is UIAbilityContext.

- In 4.1.0(11) and later versions, the parameter type is Context.
request VerifyRequest Yes Identity verification request object, containing request parameters.

Returns

Type Description
Promise<VerifyResult> Promise used to return the VerifyResult object.

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.
1001600001 The network is unavailable.
1001600002 The user has not logged in with HUAWEI ID.
1001600003 Failed to check the fingerprint of the application bundle.
1001600004 The application does not have the required permissions.
1001600005 The user canceled the current operation.
1001600006 The requested verification factors are unavailable on the device.
1001600007 Internal error.

Example:

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

// Create request parameters.
const request: extendService.VerifyRequest = {
  idType: extendService.IdType.UNION_ID,
  idValue: 'xxx', // The value can be obtained through the HUAWEI ID sign-in API.
  sceneId: 'xxx', // ID of a scenario that triggers identity verification, which is obtained through configuration application.
  riskLevel: extendService.RiskLevel.LOW,
  nonce: util.generateRandomUUID() // You are advised to use generateRandomUUID to generate a nonce.
};

// The following provides only code snippets. Use it in the custom component instance and pass a valid context object.
// Execute the identity verification request and process the result.
extendService.verifyAccount(this.getUIContext().getHostContext(), request).then(data => {
  const verifyResult = data as extendService.VerifyResult;
  hilog.info(0x0000, 'testTag', 'Succeeded in verifying.');
  const verifyToken = verifyResult.verifyToken;
  // Process verifyToken.
}).catch((error: BusinessError) => {
  dealAllError(error);
});

// Handle the error.
function dealAllError(error: BusinessError): void {
  hilog.error(0x0000, 'testTag', `Failed to verify. Code: ${error.code}, message: ${error.message}`);
}

startAccountCenter

startAccountCenter(context: common.Context, callback: AsyncCallback<void>): void

Launches the account center. This API uses an asynchronous callback to return the result. You can call this API to launch the HUAWEI ID screen, where users can view and manage their personal information such as the avatar, nickname, and mobile number. This screen supports an extended timeout period. When a user closes the screen, a callback function will be triggered.

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

System capability: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

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

Since: 4.0.0(10)

Parameters

Parameter Type Mandatory Description
context common.Context Yes

Context.

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

NOTE

- In version 4.0.0(10), the parameter type is UIAbilityContext.

- In 4.1.0(11) and later versions, the parameter type is Context.
callback AsyncCallback<void> Yes

Callback used to return the result.

If the request for launching the account center is successfully executed, err is undefined. Otherwise, err is an error object.

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.

Applicable versions: 4.1.0(11)+
1001600001

The network is unavailable.

Applicable versions: 4.1.0(11)+
1001600002 The user has not logged in with HUAWEI ID.
1001600003 Failed to check the fingerprint of the application bundle.
1001600004 The application does not have the required permissions.
1001600007 Internal error.
1001600011

This device does not support this API.

Applicable versions: 6.1.0(23)+

Example:

import { extendService } from '@kit.AccountKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

// Execute the request for launching the account center and process the result.
try {
  // The following provides only code snippets. Use it in the custom component instance and pass a valid context object.
  extendService.startAccountCenter(this.getUIContext().getHostContext(), (error: BusinessError) => {
    if (error) {
      dealAllError(error);
      return;
    }
    hilog.info(0x0000, 'testTag', 'Succeeded in starting account center');
  });
} catch (error) {
  dealAllError(error);
}

// Handle the error.
function dealAllError(error: BusinessError): void {
  hilog.error(0x0000, 'testTag', `Failed to startAccountCenter. Code: ${error.code}, message: ${error.message}`);
}

startAccountCenter

startAccountCenter(context: common.Context): Promise<void>

Launches the account center. This API uses a promise to return the result. You can call this API to launch the HUAWEI ID screen, where users can view and manage their personal information such as the avatar, nickname, and mobile number. This screen supports an extended timeout period. When a user closes the screen, a promise that contains no value is returned.

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

System capability: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

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

Since: 4.0.0(10)

Parameters

Parameter Type Mandatory Description
context common.Context Yes

Context.

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

NOTE

- In version 4.0.0(10), the parameter type is UIAbilityContext.

- In 4.1.0(11) and later versions, the parameter type is Context.

Returns

Type Description
Promise<void> Promise that returns no value.

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.

Applicable versions: 4.1.0(11)+
1001600001

The network is unavailable.

Applicable versions: 4.1.0(11)+
1001600002 The user has not logged in with HUAWEI ID.
1001600003 Failed to check the fingerprint of the application bundle.
1001600004 The application does not have the required permissions.
1001600007 Internal error.
1001600011

This device does not support this API.

Applicable versions: 6.1.0(23)+

Example:

import { extendService } from '@kit.AccountKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

// The following provides only code snippets. Use it in the custom component instance and pass a valid context object.
// Execute the request for launching the account center and process the result.
extendService.startAccountCenter(this.getUIContext().getHostContext()).then(() => {
  hilog.info(0x0000, 'testTag', 'Succeeded in starting account center');
}).catch((error: BusinessError<Object>) => {
  dealAllError(error);
});

// Handle the error.
function dealAllError(error: BusinessError<Object>): void {
  hilog.error(0x0000, 'testTag', `Failed to startAccountCenter. Code: ${error.code}, message: ${error.message}`);
}