@hms.core.account.extendService模块提供华为账号增强能力,在基础的登录、授权功能之上,为应用提供更丰富的账号管理与安全校验能力。包含两大核心功能:身份验证、打开账号中心。
身份验证:拉起身份验证页面,对当前系统登录的华为账号用户的身份进行校验,以保护用户的个人信息和隐私安全。
打开账号中心:直接拉起华为账号中心页面,供用户查看并管理当前登录的华为账号信息。
开发者可通过@hms.core.account.extendService模块提供的方法verifyAccount、startAccountCenter实现上述能力。
起始版本: 4.0.0(10)
该服务目前仅对系统应用开放。
华为账号身份标识类型枚举。当前支持设置: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的格式说明。 |
风险等级枚举。
模型约束: 此接口仅可在Stage模型下使用。
元服务API: 从版本4.1.0(11)开始,该接口支持在元服务中使用。
系统能力: SystemCapability.AuthenticationServices.HuaweiID.ExtendService
起始版本: 4.0.0(10)
| 名称 | 值 | 说明 |
|---|---|---|
| LOW | 1 | 低风险。 |
| HIGH | 2 | 高风险。 |
身份验证请求。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
}; 身份验证请求响应。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}`);
} 华为账号增强服务接口错误码枚举。
模型约束: 此接口仅可在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(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对象;否则为错误对象。 |
错误码:
| 错误码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(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对象。 |
错误码:
| 错误码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(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;否则为错误对象。 |
错误码:
| 错误码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(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对象。 |
错误码:
| 错误码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}`);
}