一、场景

应用可以使用Account Kit提供的华为账号登录按钮，获取华为账号用户身份标识UnionID、OpenID，通过UnionID、OpenID完成用户登录；或者与应用账号完成绑定，绑定后用于登录或者验证。

按钮样式

包含三种样式：

样式	说明
文本	仅显示文字
标志	仅显示华为账号标志
文本+标志	同时显示文字和标志

二、支持的设备

设备类型	支持版本
Phone	支持
Tablet	支持
PC/2in1	支持
TV	5.1.1(19)版本开始支持

三、用户体验设计

账号登录按钮的用户体验和UX设计需符合【华为账号登录】按钮规范，不符合规范的UX设计可能会对应用上架和用户体验带来影响。

四、业务流程

4.1 流程说明

阶段	序号	说明
调用登录按钮展示登录页	1-3	应用拉起登录页并展示“华为账号登录”按钮，用户点击按钮，请求华为账号授权信息
用户点击登录	4-6	华为账号未登录时拉起登录页；已登录时直接返回Authorization Code
用户关联应用账号	7-16	服务端通过Authorization Code获取Access Token，再获取用户信息，绑定UnionID完成登录

4.2 安全性

通过Authorization Code凭证获取用户信息可以有效避免黑客通过数据遍历、身份伪造、重放攻击等手段导致的安全风险。

五、开发前提

在进行代码开发前，请确保已完成：

1. 配置签名和指纹（参考配置签名和指纹）

2. 配置Client ID（参考配置Client ID）

说明：此场景无需申请账号权限。

六、客户端开发

6.1 导入模块

import { LoginWithHuaweiIDButton, loginComponentManager } from '@kit.AccountKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

6.2 核心接口

接口	描述
LoginWithHuaweiIDButton	华为账号Button登录组件，支持Icon类型、纯文本、Icon+文本混合按钮
onClickLoginWithHuaweiIDButton	注册登录事件结果回调，使用callback异步回调
setAgreementStatus	设置协议状态。如需用户同意协议才能登录，请先设置NOT_ACCEPTED，同意后设置ACCEPTED

6.3 错误码枚举

export enum ErrorCode {
    ERROR_CODE_LOGIN_OUT = 1001502001,           // 账号未登录
    ERROR_CODE_NETWORK_ERROR = 1001502005,       // 网络错误
    ERROR_CODE_INTERNAL_ERROR = 1001502009,      // 内部错误
    ERROR_CODE_USER_CANCEL = 1001502012,         // 用户取消授权
    ERROR_CODE_SYSTEM_SERVICE = 12300001,        // 系统服务异常
    ERROR_CODE_REQUEST_REFUSE = 1001500002,      // 重复请求
    ERROR_CODE_AGREEMENT_STATUS_NOT_ACCEPTED = 1005300001  // 用户未同意协议
}

6.4 代码示例

@Entry
@Component
struct PreviewLoginButtonPage {
    // 构造LoginWithHuaweiIDButton组件的控制器
    controller: loginComponentManager.LoginWithHuaweiIDButtonController =
        new loginComponentManager.LoginWithHuaweiIDButtonController()
            .onClickLoginWithHuaweiIDButton((error: BusinessError, response: loginComponentManager.HuaweiIDCredential) => {
                if (error) {
                    this.dealAllError(error);
                    return;
                }
                if (response) {
                    hilog.info(0x0000, 'testTag', 'Succeeded in getting response.');
                    const authCode = response.authorizationCode;
                    // 开发者处理authCode（传给服务端）
                }
            });

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

        if (error.code === ErrorCode.ERROR_CODE_LOGIN_OUT) {
            // 用户未登录华为账号，请登录华为账号并重试
        } else if (error.code === ErrorCode.ERROR_CODE_NETWORK_ERROR) {
            // 网络异常，请检查当前网络状态并重试
        } else if (error.code === ErrorCode.ERROR_CODE_INTERNAL_ERROR) {
            // 登录失败，请尝试使用其他方式登录
        } else if (error.code === ErrorCode.ERROR_CODE_USER_CANCEL) {
            // 用户取消授权
        } else if (error.code === ErrorCode.ERROR_CODE_SYSTEM_SERVICE) {
            // 系统服务异常，请稍后重试
        } else if (error.code === ErrorCode.ERROR_CODE_REQUEST_REFUSE) {
            // 重复请求，应用无需处理
        } else if (error.code === ErrorCode.ERROR_CODE_AGREEMENT_STATUS_NOT_ACCEPTED) {
            // 用户未同意协议
        } else {
            // 应用登录失败，请尝试使用其他方式登录
        }
    }

    build() {
        Column() {
            Column() {
                LoginWithHuaweiIDButton({
                    params: {
                        style: loginComponentManager.Style.BUTTON_RED,  // 按钮样式
                        extraStyle: {
                            buttonStyle: new loginComponentManager.ButtonStyle().loadingStyle({
                                show: true
                            })
                        },
                        borderRadius: 24,                               // 边框圆角半径
                        loginType: loginComponentManager.LoginType.ID,  // 登录类型
                        supportDarkMode: true                           // 支持深浅色模式切换
                    },
                    controller: this.controller
                })
            }
            .height(40)
        }
        .width('100%')
        .justifyContent(FlexAlign.Center)
        .margin({ left: 16, right: 16 })
    }
}

七、服务端开发

7.1 获取Access Token和UnionID

步骤	接口	说明
1	获取用户级凭证接口	使用Client ID、Client Secret、Authorization Code获取Access Token、Refresh Token
2	解析凭证接口	使用Access Token获取用户的UnionID

7.2 关联用户体系

应用通过查询获取的UnionID判断该用户是否已关联：

• 已关联：完成用户登录

• 未关联：创建新用户，绑定UnionID，完成用户登录

八、Token过期处理

8.1 Access Token过期处理

项目	说明
有效期	60分钟
处理方式	使用Refresh Token（有效期180天）通过刷新用户级凭证接口获取新的Access Token

重要：当Access Token失效时，若应用不使用Refresh Token获取新的Access Token，账号的授权信息将会失效，导致使用Access Token的功能都会失败。

8.2 Access Token非正常失效场景

当Access Token非正常失效（如修改密码、退出账号、删除设备）时，应用可重新登录授权获取Authorization Code，向华为账号服务器请求获取新的Access Token。

8.3 Refresh Token过期处理

项目	说明
有效期	180天
处理方式	失效后，应用服务端需要通知客户端，重新调用授权接口，请求用户重新授权

九、其他

要点	说明
核心组件	LoginWithHuaweiIDButton
获取信息	Authorization Code → Access Token → UnionID
有效期	Access Token 60分钟，Refresh Token 180天
设备支持	Phone、Tablet、PC/2in1、TV(19+)
错误处理	需根据错误码引导用户

业务流程

用户点击登录按钮
    ↓
获取Authorization Code
    ↓
服务端用Authorization Code换取Access Token
    ↓
用Access Token获取UnionID
    ↓
根据UnionID关联/创建用户
    ↓
完成登录