目录

@hms.core.account.extendService (华为账号增强服务)

模块概述

@hms.core.account.extendService模块提供华为账号增强能力,在基础的登录、授权功能之上,为应用提供更丰富的账号管理与安全校验能力。包含两大核心功能:身份验证、打开账号中心。

开发者可通过@hms.core.account.extendService模块提供的方法verifyAccount、startAccountCenter实现上述能力。

起始版本: 4.0.0(10)

该服务目前仅对系统应用开放。

导入模块

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

IdType

华为账号身份标识类型枚举。当前支持设置:IdType.UNION_ID或IdType.OPEN_ID。

模型约束: 此接口仅可在Stage模型下使用。

元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。

系统能力: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

起始版本: 4.0.0(10)

名称 值 说明
USER_ID 1

华为账号用户的UID。

说明: 该参数仅对系统应用开放。

OPEN_ID 2 华为账号用户的OpenID。具体格式要求请参考OpenID和UnionID的格式说明。
UNION_ID 3 华为账号用户的UnionID。具体格式要求请参考OpenID和UnionID的格式说明。

RiskLevel

风险等级枚举。

模型约束: 此接口仅可在Stage模型下使用。

元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。

系统能力: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

起始版本: 4.0.0(10)

名称 值 说明
LOW 1 低风险。
HIGH 2 高风险。

VerifyRequest

身份验证请求。verifyAccount方法入参,接口需包含用户的基础身份标识,与系统华为账号用户进行身份比对。开发者可通过设置身份验证的场景值、风险等级等属性,控制身份验证的次数和方式,华为账号服务会根据这些属性拉起对应的身份验证页面。

模型约束: 此接口仅可在Stage模型下使用。

元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。

系统能力: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

起始版本: 4.0.0(10)

名称 类型 只读 可选 说明
idType IdType 否 否 华为账号身份标识类型。当前非系统应用仅支持设置:IdType.UNION_ID或IdType.OPEN_ID。
idValue string 否 否

华为账号身份标识UnionID/OpenID值。身份标识类型通过idType属性定义。长度限制1-256。

UnionID、OpenID值可以通过华为账号登录、获取华为账号用户信息、华为账号Panel登录组件或华为账号Button登录组件获取。

sceneId string 否 否 身份验证的场景值,该值与riskLevel属性一起代表了应用在华为账号服务器上的一组配置,包括验证次数、首次验证方式、二次验证方式等。长度限制1-10。
riskLevel RiskLevel 否 否 风险等级,该值与sceneId一起代表了应用在华为账号服务器上的一组配置,一般风险等级高的场景,需要进行二次验证。
nonce string 否 否

请求体中的nonce属性,长度限制1-64。该属性会包含在返回的verifyToken中,通过校验一致性,可用于防止重放攻击。

推荐开发者用随机数并做一致性校验。建议生成方式:util.generateRandomUUID()。

示例:

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

// 创建请求参数
const request: extendService.VerifyRequest = {
  idType: extendService.IdType.UNION_ID,
  idValue: '<可通过华为账号登录接口获取>', // 该值可以通过华为账号登录接口获取
  sceneId: '<触发身份认证的场景ID>', // 触发身份验证的场景ID
  riskLevel: extendService.RiskLevel.LOW,
  nonce: util.generateRandomUUID() // 建议使用generateRandomUUID生成nonce
};

VerifyResult

身份验证请求响应。verifyAccount方法返回值,当用户验证身份成功时返回。

模型约束: 此接口仅可在Stage模型下使用。

元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。

系统能力: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

起始版本: 4.0.0(10)

名称 类型 只读 可选 说明
verifyToken string 是 否 身份验证返回的Token,JWT格式的数据。

示例:

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

// 创建请求参数
const request: extendService.VerifyRequest = {
  idType: extendService.IdType.UNION_ID,
  idValue: '<可通过华为账号登录接口获取>', // 该值可以通过华为账号登录或授权接口获取
  sceneId: '<触发身份认证的场景ID>', // 触发身份验证的场景ID
  riskLevel: extendService.RiskLevel.LOW,
  nonce: util.generateRandomUUID() // 建议使用generateRandomUUID生成nonce
};

// 执行身份验证请求,并处理结果
try {
  // 此示例为代码片段,实际需在自定义组件实例中使用,并传入有效的Context上下文对象
  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;
    // 开发者处理verifyToken
  });
} catch (error) {
  dealAllError(error);
}

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

ExtendErrorCode

华为账号增强服务接口错误码枚举。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

起始版本: 4.0.0(10)

名称 值 说明
INVALID_PARAMETER 401

参数检查失败。

元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。

NETWORK_ERROR 1001600001

网络不可用。

元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。

ACCOUNT_NOT_LOGGED_IN 1001600002

用户未登录华为账号。

元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。

PACKAGE_FINGERPRINT_CHECK_ERROR 1001600003

应用指纹证书校验失败。

元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。

PERMISSION_CHECK_ERROR 1001600004

应用未申请对应permissions权限。

元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。

USER_CANCELED 1001600005

用户取消当前操作。

元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。

VERIFICATION_FACTOR_UNAVAILABLE 1001600006

当前设备不支持此验证要素。

元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。

INTERNAL_ERROR 1001600007

内部错误。

元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。

DEVICE_NOT_SUPPORTED 1001600011

该设备不支持此API。

起始版本: 6.1.0(23)

元服务API: 从版本6.1.0(23)开始,该接口支持在元服务中使用。

verifyAccount

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

身份验证方法,使用Callback异步回调返回验证成功凭证。调用该方法会拉起身份验证页面,需要用户进行密码、短信等方式验证身份。身份页面可长时间停留,当用户验证成功后,会返回验证凭证给应用,其他场景如用户点击关闭则会抛出错误码。

模型约束: 此接口仅可在Stage模型下使用。

元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。

系统能力: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

起始版本: 4.0.0(10)

参数:

参数名 类型 必填 说明
context common.Context 是

Context上下文。

应用可支持的Context有:UIAbilityContext和UIExtensionContext。不支持应用在半模态、弹出框、子窗口等非全页面组件中使用UIExtensionContext调用。

元服务可支持的Context有:UIAbilityContext。

说明:

- 在4.0.0(10)版本,参数类型为UIAbilityContext。

- 从4.1.0(11)版本开始,参数类型为Context。

request VerifyRequest 是 身份验证请求对象,包含请求参数。
callback AsyncCallback<VerifyResult> 是

回调函数。

当身份验证请求成功,err为undefined,data为获取到的VerifyResult对象;否则为错误对象。

错误码:

以下错误码的详细介绍请参见通用错误码和ArkTS错误码。

错误码ID 错误信息
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.

示例:

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

// 创建请求参数
const request: extendService.VerifyRequest = {
  idType: extendService.IdType.UNION_ID,
  idValue: '<可通过华为账号登录接口获取>', // 该值可以通过华为账号登录接口获取
  sceneId: '<触发身份认证的场景ID>', // 触发身份验证的场景ID,通过配置申请获取
  riskLevel: extendService.RiskLevel.LOW,
  nonce: util.generateRandomUUID() // 建议使用generateRandomUUID生成nonce
};

// 执行身份验证请求,并处理结果
try {
  // 此示例为代码片段,实际需在自定义组件实例中使用,并传入有效的Context上下文对象
  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;
    // 开发者处理verifyToken
  });
} catch (error) {
  dealAllError(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>

身份验证方法,使用Promise异步回调返回验证成功凭证。调用该方法会拉起身份验证页面,需要用户进行密码、短信等方式验证身份。身份页面可长时间停留,当用户验证成功后,会返回验证凭证给应用,其他场景如用户点击关闭则会抛出错误码。

模型约束: 此接口仅可在Stage模型下使用。

元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。

系统能力: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

起始版本: 4.0.0(10)

参数:

参数名 类型 必填 说明
context common.Context 是

Context上下文。

应用可支持的Context有:UIAbilityContext和UIExtensionContext。不支持应用在半模态、弹出框、子窗口等非全页面组件中使用UIExtensionContext调用。

元服务可支持的Context有:UIAbilityContext。

说明:

- 在4.0.0(10)版本,参数类型为UIAbilityContext。

- 从4.1.0(11)版本开始,参数类型为Context。

request VerifyRequest 是 身份验证请求对象,包含请求参数。

返回值:

类型 说明
Promise<VerifyResult> Promise对象,返回VerifyResult对象。

错误码:

以下错误码的详细介绍请参见通用错误码和ArkTS错误码。

错误码ID 错误信息
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.

示例:

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

// 创建请求参数
const request: extendService.VerifyRequest = {
  idType: extendService.IdType.UNION_ID,
  idValue: '<可通过华为账号登录接口获取>', // 该值可以通过华为账号登录接口获取
  sceneId: '<触发身份认证的场景ID>', // 触发身份验证的场景ID,通过配置申请获取
  riskLevel: extendService.RiskLevel.LOW,
  nonce: util.generateRandomUUID() // 建议使用generateRandomUUID生成nonce
};

// 此示例为代码片段,实际需在自定义组件实例中使用,并传入有效的Context上下文对象
// 执行身份验证请求,并处理结果
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;
  // 开发者处理verifyToken
}).catch((error: BusinessError) => {
  dealAllError(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

打开华为账号中心方法,使用Callback异步回调。开发者可调用该方法拉起账号中心页面,供用户查看并管理头像、昵称、手机号等个人信息。账号中心页面会长时间停留,当用户关闭该页面后,会触发Callback回调函数。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

设备行为差异: 该接口在Phone、PC/2in1、Tablet、TV中可正常调用,在其他设备类型中返回1001600011错误码。

起始版本: 4.0.0(10)

参数:

参数名 类型 必填 说明
context common.Context 是

Context上下文。

可支持的Context有:UIAbilityContext和UIExtensionContext。不支持应用在半模态、弹出框、子窗口等非全页面组件中使用UIExtensionContext调用。

说明:

- 在4.0.0(10)版本,参数类型为UIAbilityContext。

- 从4.1.0(11)版本开始,参数类型为Context。

callback AsyncCallback<void> 是

回调函数。

当执行打开账号中心请求成功,err为undefined;否则为错误对象。

错误码:

以下错误码的详细介绍请参见通用错误码和ArkTS错误码。

错误码ID 错误信息
401

Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

适用版本:4.1.0(11)+

1001600001

The network is unavailable.

适用版本: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.

适用版本:6.1.0(23)+

示例:

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

// 执行打开账号中心请求,并处理结果
try {
  // 此示例为代码片段,实际需在自定义组件实例中使用,并传入有效的Context上下文对象
  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);
}

// 错误处理
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>

打开华为账号中心方法,使用Promise异步回调。开发者可调用该方法拉起账号中心页面,供用户查看并管理头像、昵称、手机号等个人信息。账号中心页面会长时间停留,当用户关闭该页面后,会返回无结果的Promise对象。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.AuthenticationServices.HuaweiID.ExtendService

设备行为差异: 该接口在Phone、PC/2in1、Tablet、TV中可正常调用,在其他设备类型中返回1001600011错误码。

起始版本: 4.0.0(10)

参数:

参数名 类型 必填 说明
context common.Context 是

Context上下文。

可支持的Context有:UIAbilityContext和UIExtensionContext。不支持应用在半模态、弹出框、子窗口等非全页面组件中使用UIExtensionContext调用。

说明:

- 在4.0.0(10)版本,参数类型为UIAbilityContext。

- 从4.1.0(11)版本开始,参数类型为Context。

返回值:

类型 说明
Promise<void> Promise对象,无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和ArkTS错误码。

错误码ID 错误信息
401

Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

适用版本:4.1.0(11)+

1001600001

The network is unavailable.

适用版本: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.

适用版本:6.1.0(23)+

示例:

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

// 此示例为代码片段,实际需在自定义组件实例中使用,并传入有效的Context上下文对象
// 执行打开账号中心请求,并处理结果
extendService.startAccountCenter(this.getUIContext().getHostContext()).then(() => {
  hilog.info(0x0000, 'testTag', 'Succeeded in starting account center');
}).catch((error: BusinessError<Object>) => {
  dealAllError(error);
});

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