华为账号一键登录，它不仅可以获取UnionID，还能直接获取手机号，实现更便捷的用户登录体验。

一、华为账号一键登录

华为账号一键登录是基于OAuth 2.0协议标准和OpenID Connect协议标准构建的授权登录系统，应用可以快捷地获取华为账号用户的身份标识和手机号，快速建立应用内的用户体系。

优势	说明
简化登录步骤	用户无需输入账号名和密码，无需复杂安全验证
提高转化率	利用系统账号的安全性和便利性
系统验证手机号	提供系统验证过的手机号，关联应用已有用户
多设备一致体验	支持Phone、Tablet、PC/2in1、TV设备

使用场景

若应用需同时获取手机号和UnionID完成用户登录，Account Kit提供了同时获取手机号和UnionID的华为账号一键登录按钮。设备登录华为账号（该账号已绑定手机号）后，一键登录获取手机号可不依赖设备插SIM卡。

限制

限制项	说明
业务场景	需满足《常见类型移动互联网应用程序必要个人信息范围规定》中使用手机号的必要业务场景
用户协议	用户必须同意《华为账号用户认证协议》，应用需实现协议跳转
二次放号	应用需根据自身业务场景判断使用方式，必要时增加其他安全验证手段
可用地区	仅限中国境内（香港特别行政区、澳门特别行政区、中国台湾除外）
服务器位置	应用服务端必须部署在中国境内（香港特别行政区、澳门特别行政区、中国台湾除外）
设备支持	Phone、Tablet、PC/2in1、TV（5.1.1(19)开始支持）
开发者类型	仅支持企业开发者，个人开发者请使用华为账号登录或静默登录

儿童账号一键登录

用户使用儿童账号进行登录，点击一键登录会触发Account Kit默认提供的家长验密流程（Account Kit提供的验证页，暂不可自定义），家长验密完成后可获取用户的身份标识和手机号。

注意：TV设备暂不支持儿童账号。

手机号验证机制

Account Kit调用系统能力获取华为账号登录设备上的SIM卡手机号码，与华为账号绑定的手机号进行校验（有网络即可，无需使用SIM卡移动数据）：

情况	行为
90天内有验证通过记录	返回该华为账号绑定的手机号
90天内无验证通过记录	触发Account Kit默认提供的短信验证流程（暂不可自定义）

二、用户体验设计

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

登录页面UX设计

• 从华为账号侧获取的匿名手机号需展示在页面上

• 设置好隐私协议（包含用户服务协议、隐私协议、华为账号用户认证协议）

• 设置登录按钮类型为LoginType.QUICK_LOGIN

• 应用需实现协议跳转功能

三、业务流程

3.1 用户首次登录应用

流程说明：

阶段	序号	说明
预取号	1-4	应用scope传quickLoginAnonymousPhone获取匿名手机号。若获取为空，需展示其他登录方式
展示一键登录页面	5	展示匿名手机号和隐私协议，设置登录按钮类型为QUICK_LOGIN
点击一键登录关联用户	6-16	获取Authorization Code，服务端调用接口获取完整手机号和UnionID，完成登录

提示：

• 获取匿名手机号需进行超时处理，推荐设置5秒保证用户体验

• 若华为账号未登录，会返回错误码1001502001，需展示其他登录方式

• forceAuthorization参数必须设置为false

3.2 用户非首次登录应用（可选）

若应用已接入过华为账号登录，存在使用华为账号登录过的用户账号（即根据UnionID/OpenID判断用户已关联过应用系统数据库），则：

1. 调用授权请求获取Authorization Code

2. 服务端通过Authorization Code获取用户信息

3. 通过UnionID/OpenID判断用户是否已关联

4. 如已关联，可展示已关联账号，由用户选择是否登录，或免用户操作静默登录

四、接口说明

接口	描述
createAuthorizationWithHuaweiIDRequest()	获取授权请求，传入scope: quickLoginAnonymousPhone，获取匿名手机号和Authorization Code
executeRequest(request)	通过Promise方式执行授权操作
LoginWithHuaweiIDButton	华为账号Button登录组件，仅纯文本样式支持一键登录
onClickLoginWithHuaweiIDButton	注册一键登录按钮的结果回调
setAgreementStatus	设置协议状态（NOT_ACCEPTED / ACCEPTED）
onClickEvent	注册一键登录按钮的点击事件回调
continueLogin	用户点击协议弹框的同意并登录按钮结果回调

注意：上述接口需在页面或自定义组件生命周期内调用。

五、开发前提

在进行代码开发前，请先确认已完成开发准备工作：

未配置项	报错码
未配置签名和指纹	1001500001（应用指纹证书校验失败）
未申请“华为账号一键登录”权限	1001502014（应用未申请scopes或permissions权限）
开启代码混淆	需将quickLoginAnonymousPhone属性加入混淆白名单

代码混淆配置

在调用获取匿名手机号方法工程模块的混淆文件obfuscation-rules.txt中添加：

-enable-property-obfuscation
-keep-property-name
quickLoginAnonymousPhone

六、客户端开发

6.1 导入模块

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

6.2 获取匿名手机号

getQuickLoginAnonymousPhone() {
    // 创建授权请求
    const authRequest = new authentication.HuaweiIDProvider()
        .createAuthorizationWithHuaweiIDRequest();
    
    // 获取匿名手机号需传quickLoginAnonymousPhone这个scope
    authRequest.scopes = ['quickLoginAnonymousPhone'];
    
    // 用于防跨站点请求伪造
    authRequest.state = util.generateRandomUUID();
    
    // 一键登录场景该参数必须设置为false
    authRequest.forceAuthorization = false;
    
    const controller = new authentication.AuthenticationController();
    
    try {
        controller.executeRequest(authRequest).then((response) => {
            const anonymousPhone = response.data?.extraInfo?.quickLoginAnonymousPhone as string;
            if (anonymousPhone) {
                // 获取到匿名手机号，用于页面展示
                hilog.info(0x0000, 'testTag', 'Succeeded in authentication.');
                this.quickLoginAnonymousPhone = anonymousPhone;
                return;
            }
            // 未获取到匿名手机号，跳转到其他方式登录页面
            hilog.info(0x0000, 'testTag', 'AnonymousPhone is empty.');
        }).catch((error: BusinessError) => {
            this.dealAllError(error);
        });
    } catch (error) {
        this.dealAllError(error);
    }
}

6.3 获取匿名手机号错误码处理

错误码	错误描述	处理建议
1001502001	用户未登录华为账号	应用展示其他登录方式
1001502005	网络异常	提示用户检查网络后重试
1001502009	内部错误	应用展示其他登录方式
1001502014	应用未申请scopes或permissions权限	参考FAQ解决
1001500001	应用指纹证书校验失败	参考FAQ解决
1001500002	重复请求	应用无需处理
1001500003	不支持该scopes或permissions	海外账号或设备不支持
12300001	系统服务异常	应用展示其他登录方式

6.4 展示一键登录页面并获取Authorization Code

@Entry
@Component
struct PreviewLoginButtonPage {
    @State quickLoginAnonymousPhone: string = '';
    
    build() {
        Column() {
            // 展示匿名手机号
            Text(this.quickLoginAnonymousPhone)
                .fontSize(36)
                .fontWeight(FontWeight.Bold)
            
            Text('华为账号绑定号码')
                .fontSize(14)
            
            // 华为账号一键登录按钮
            LoginWithHuaweiIDButton({
                params: {
                    style: loginComponentManager.Style.BUTTON_RED,
                    loginType: loginComponentManager.LoginType.QUICK_LOGIN,
                    supportDarkMode: true
                },
                controller: this.controller
            })
        }
    }
}

七、服务端开发

7.1 接口调用

应用服务端使用Client ID、Client Secret、Authorization Code调用/oauth2/v6/quickLogin/getPhoneNumber接口获取完整手机号和华为账号用户标识UnionID。

7.2 用户关联处理

情况	处理方式
已关联	绑定UnionID与手机号到已有用户上（如已绑定可忽略），完成登录
未关联	创建新用户并绑定手机号与UnionID

八、客户端与服务端交互

8.1 数据流向

应用客户端 → 应用服务端 → 华为账号服务器
    ①           ②           ③

1. 客户端获取Authorization Code后传给服务端

2. 服务端使用Authorization Code调用华为账号接口获取用户信息

3. 服务端返回用户信息给客户端

8.2 客户端请求示例

import { rcp } from '@kit.RemoteCommunicationKit';

export function rcpRequest(authCode: string) {
    const headers: rcp.RequestHeaders = {
        'accept': 'application/json'
    };
    
    const postMessage: Record<string, string> = {
        'authorizationCode': authCode
    };
    
    const baseUrl = 'http://localhost:8080/login';
    const req = new rcp.Request(baseUrl, 'POST', headers, postMessage);
    
    const session = rcp.createSession();
    session.fetch(req).then((response) => {
        // 处理响应
    });
}

九、开发后验证

标准编号	标准项名称	说明
1	满足华为账号提供登录设计规范	需合规的设计规范
2	用户交互体验原则	协议可展示可点击、用户勾选协议后才可登录
3	登录页面内容用户体验原则	匿名手机号须从华为账号侧获取，必须包含《华为账号用户认证协议》
4	异常处理用户体验原则	勿将错误码透传给用户
5	应用生命周期变化	应用更新后登录状态须与更新前一致

业务流程

预取号获取匿名手机号（超时5秒）
    ↓
展示一键登录页面（匿名手机号+隐私协议）
    ↓
用户同意协议点击登录
    ↓
获取Authorization Code
    ↓
服务端调用getPhoneNumber接口
    ↓
获取完整手机号和UnionID
    ↓
关联/创建用户，完成登录

   鸿蒙华为账号一键登录通过quickLoginAnonymousPhone scope获取匿名手机号展示，用户同意协议后获取Authorization Code，服务端调用/oauth2/v6/quickLogin/getPhoneNumber接口获取完整手机号和UnionID，实现企业开发者场景下的便捷登录，手机号验证在90天内有记录可免短信验证。