静默登录适用于应用卸载重装、用户换机等场景，不需要用户点击登录/注册按钮，即可自动获取用户的身份标识UnionID/OpenID，完成用户的静默登录。

一、静默登录

在应用卸载重装、用户换机等场景，如登录的华为账号与应用重装、换机前一致，应用可通过Account Kit提供的静默登录方式即不需要用户点击登录/注册按钮，即可获取用户的身份标识UnionID/OpenID，完成用户的静默登录。

场景	说明
应用卸载重装	用户重新安装应用后，无需再次登录
用户换机	用户更换设备后，自动登录

特点

• 无需用户交互：不需要用户点击登录/注册按钮

• 自动获取身份标识：获取UnionID/OpenID

• 提升用户体验：减少用户操作步骤

二、支持版本

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

三、业务流程

阶段	说明
调用登录API	用户使用华为账号登录过应用，应用卸载重装或换机后再进入应用时，应用传forceLogin = false等参数调用登录API。如华为账号已登录且API调用成功，获取Authorization Code；如华为账号未登录，返回错误码1001502001
用户关联应用账号	服务端通过Authorization Code获取Access Token，再获取UnionID，应用完成静默登录

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

四、开发前提

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

配置项	说明
配置签名和指纹	参考配置签名和指纹
配置Client ID	参考配置Client ID

注意：此场景无需申请账号权限。

五、接口

接口	描述
createLoginWithHuaweiIDRequest()	创建账号登录请求。forceLogin参数静默登录场景设置为false
constructor(context)	创建登录请求Controller
executeRequest(request)	通过Promise方式执行登录操作

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

六、客户端开发

6.1 导入模块

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

6.2 错误码枚举

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   // 重复请求
}

6.3 创建登录请求并执行

// 创建登录请求，并设置参数
const loginRequest = new authentication.HuaweiIDProvider()
    .createLoginWithHuaweiIDRequest();

// false表示静默登录（重要）
loginRequest.forceLogin = false;

// 用于防跨站点请求伪造
loginRequest.state = util.generateRandomUUID();

// 执行登录请求
try {
    const controller = new authentication.AuthenticationController();
    
    controller.executeRequest(loginRequest).then((response: authentication.LoginWithHuaweiIDResponse) => {
        const state = response.state;
        if (state && loginRequest.state !== state) {
            hilog.error(0x0000, 'testTag', `The state is different, response state: ${state}`);
            return;
        }
        
        hilog.info(0x0000, 'testTag', 'Succeeded in logging in.');
        
        const code = response?.data?.authorizationCode;
        // 开发者处理code（传给服务端）
    }).catch((error: BusinessError) => {
        dealAllError(error);
    });
} catch (error) {
    dealAllError(error);
}

6.4 参数

参数	静默登录值	说明
forceLogin	false	不强制拉起登录页面，静默获取授权
state	随机UUID	防跨站点请求伪造

6.5 错误处理函数

function dealAllError(error: BusinessError): void {
    hilog.error(0x0000, 'testTag', `Failed to login. Code: ${error.code}, message: ${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 {
        // 应用登录失败，请尝试使用其他方式登录
    }
}

七、服务端开发

7.1 获取Access Token

应用服务端使用Client ID、Client Secret、Authorization Code调用获取用户级凭证接口向华为账号服务器请求获取Access Token、Refresh Token。

7.2 获取UnionID

使用Access Token调用解析凭证接口获取用户的UnionID。

7.3 用户关联

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

• 已关联：完成用户登录

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

7.4 业务流程

应用启动（重装/换机后）
    ↓
创建LoginWithHuaweiIDRequest
    ↓
设置forceLogin=false
    ↓
调用executeRequest执行静默登录
    ↓
如华为账号已登录 → 获取Authorization Code
如华为账号未登录 → 返回错误码1001502001
    ↓
服务端用Authorization Code换取Access Token
    ↓
用Access Token获取UnionID
    ↓
根据UnionID关联用户，完成静默登录

7.5 注意事项

1. forceLogin必须为false：静默登录的关键参数

2. 华为账号未登录处理：返回错误码1001502001，需引导用户登录

3. Token管理：注意Access Token和Refresh Token的有效期

八、Token过期处理

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

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

Access Token非正常失效场景

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

Refresh Token过期处理

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

九、四种登录方式对比

对比项	静默登录	自定义按钮登录	华为账号登录按钮	华为账号一键登录
用户操作	无需点击	点击自定义按钮	点击标准按钮	点击标准按钮
forceLogin	false	true	-	-
获取信息	UnionID	UnionID	UnionID	手机号+UnionID
开发者类型	企业+个人	企业+个人	企业+个人	仅企业
适用场景	重装/换机自动登录	UI定制需求	快速集成	需要手机号

   静默登录通过forceLogin=false参数调用华为账号登录API，在应用卸载重装或换机场景下无需用户点击即可获取Authorization Code，服务端再用Code换取UnionID完成自动登录，适用于企业开发者和个人开发者。