feat: 集成华为快应用帐号登录
This commit is contained in:
158
docs/hwservice-integration-guide.md
Normal file
158
docs/hwservice-integration-guide.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# 华为快应用 HwService JS SDK 集成指南
|
||||
|
||||
## 概述
|
||||
|
||||
本文档介绍如何将该 uni-app 项目以 H5 壳模式部署到华为快应用平台，并集成华为 HwService JS SDK（帐号服务 + 分析服务）。
|
||||
|
||||
## 项目架构
|
||||
|
||||
```
|
||||
H5 壳模式快应用架构：
|
||||
┌─────────────────────────────────────┐
|
||||
│ 华为快应用引擎 (QuickApp Runtime) │
|
||||
│ ┌─────────────────────────────────┐ │
|
||||
│ │ WebView (H5 页面) │ │
|
||||
│ │ ┌───────────────────────────┐ │ │
|
||||
│ │ │ uni-app 应用 │ │ │
|
||||
│ │ │ ├─ common/js/hw-jssdk.js │ │ │
|
||||
│ │ │ ├─ common/js/auth.js │ │ │
|
||||
│ │ │ └─ store/index.js │ │ │
|
||||
│ │ └───────────────────────────┘ │ │
|
||||
│ └─────────────────────────────────┘ │
|
||||
│ │ HwService Bridge │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────┐ │
|
||||
│ │ HMS Core (华为移动服务) │ │
|
||||
│ │ ├─ Account Kit (帐号服务) │ │
|
||||
│ │ ├─ Analytics Kit (分析服务) │ │
|
||||
│ │ └─ Push Kit (推送服务，可选) │ │
|
||||
│ └─────────────────────────────────┘ │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 部署前准备
|
||||
|
||||
### 1. 华为 AppGallery Connect 配置
|
||||
|
||||
1. 登录 [AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)
|
||||
2. 创建应用（选择「快应用」类型）
|
||||
3. 开启以下服务：
|
||||
- **华为帐号服务 (Account Kit)**
|
||||
- **华为分析服务 (Analytics Kit)**（可选）
|
||||
- **华为推送服务 (Push Kit)**（可选）
|
||||
4. 下载 `agconnect-services.json` 配置文件
|
||||
5. 将配置文件放入项目根目录
|
||||
|
||||
### 2. 安装 npm 依赖
|
||||
|
||||
```bash
|
||||
# 基础桥接库（必装，提供 hmsjsb.invoke 桥接能力）
|
||||
npm install --save @hw-hmscore/hms-js-base
|
||||
|
||||
# 华为分析服务封装包（可选，提供更完善的 API 封装）
|
||||
npm install --save @hw-hmscore/analytics-sdk-quickapp
|
||||
```
|
||||
|
||||
**注意：**
|
||||
- **Account Kit（帐号服务）** 和 **Push Kit（推送服务）** 没有独立的 quickapp npm 包，统一通过 `@hw-hmscore/hms-js-base` 的 `hmsjsb.invoke()` 桥接调用
|
||||
- `@hw-hmscore/analytics-sdk-quickapp` 版本 `6.10.0-301`（ISC 许可证），**可选安装**——不装则走 invoke 桥接
|
||||
- 相关 npm 包由华为官方发布（`hmscore@huawei.com`）
|
||||
|
||||
### 3. 配置 HUAWEI 条件编译
|
||||
|
||||
本项目的 `package.json` 已为各快应用域名定义自定义发行脚本：
|
||||
|
||||
| 脚本名 | 条件编译标记 | 用途 |
|
||||
|--------|------------|------|
|
||||
| `h5-xcx20.5g-quickapp.com` | `H5_XCX_5G_QUICKAPP_COM` | 5G 快应用 |
|
||||
| `h5-xcx.aigc-quickapp.com` | `H5_XCX_AIGC_QUICKAPP_COM` | AIGC 快应用 |
|
||||
| `h5-5g.aigc-quickapp.com` | `H5_5G_AIGC_QUICKAPP_COM` | 5G AIGC 快应用 |
|
||||
| `h5-test.aigc-quickapp.com` | `H5_TEST_AIGC_QUICKAPP_COM` | 测试快应用 |
|
||||
|
||||
当使用 HBuilderX → 发行 → 自定义发行 时，对应的 `#ifdef` 条件编译块会被激活。
|
||||
|
||||
### 4. 配置华为参数
|
||||
|
||||
编辑 `common/js/config.js` 中的 `huawei` 配置项：
|
||||
|
||||
```javascript
|
||||
huawei: {
|
||||
appId: '你的AGC应用ID',
|
||||
clientId: '你的客户端ID',
|
||||
clientSecret: '你的客户端密钥（建议由后端下发）',
|
||||
redirectUri: window.location.origin + '/hwappx/common/',
|
||||
}
|
||||
```
|
||||
|
||||
**注意**：`clientSecret` 敏感信息建议由后端接口动态下发，避免在前端硬编码。
|
||||
|
||||
## 后端配合
|
||||
|
||||
### 新增接口
|
||||
|
||||
华为帐号登录需要后端增加以下接口：
|
||||
|
||||
| 接口路径 | 方法 | 说明 |
|
||||
|---------|------|------|
|
||||
| `/wechat/api/quickapp/huawei_auth` | POST | 华为 openId 换 token |
|
||||
|
||||
**请求参数**：
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `openid` | string | 华为帐号 openId |
|
||||
| `unionid` | string | 华为帐号 unionId（可选） |
|
||||
| `nickname` | string | 用户昵称 |
|
||||
| `avatar` | string | 头像 URL |
|
||||
| `gender` | int | 性别（0:未知 1:男 2:女） |
|
||||
|
||||
**返回格式**（需与现有登录接口保持一致）：
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"openid": "华为openId",
|
||||
"unionid": "华为unionId"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 已修改的文件清单
|
||||
|
||||
| 文件 | 变更类型 | 说明 |
|
||||
|------|---------|------|
|
||||
| `common/js/hw-jssdk.js` | **新增** | HwService 统一封装（Account/Analytics/Push） |
|
||||
| `common/js/auth.js` | 修改 | 新增 `_huaweiSignIn` 方法，快应用环境下使用华为帐号登录 |
|
||||
| `common/js/http.js` | 修改 | 新增 `H5_XCX_*_QUICKAPP_COM` 条件编译，请求类型为 `quickapp` |
|
||||
| `common/js/event-bus.js` | 修改 | 新增 `quickapp` 平台检测分支 |
|
||||
| `common/js/config.js` | 修改 | 新增 `huawei` 配置项 |
|
||||
| `store/index.js` | 修改 | 新增 `huaweiAccountInfo` 状态/`initHwService` action |
|
||||
|
||||
## 发布流程
|
||||
|
||||
1. 使用 HBuilderX 打开项目
|
||||
2. 修改 `manifest.json` → Web 配置 → 基础路径（`/hwappx/common/`）
|
||||
3. 选择「发行」→「自定义发行」→ 选择对应的快应用脚本
|
||||
4. 构建完成后，将 `unpackage/dist/build/web/` 目录打包为 zip
|
||||
5. 使用华为快应用 IDE 导入并发布
|
||||
|
||||
## 验证方式
|
||||
|
||||
### 检查 HwService 是否可用
|
||||
```javascript
|
||||
const HwService = require('@/common/js/hw-jssdk.js').default;
|
||||
console.log('是否快应用环境:', HwService.isQuickAppEnv());
|
||||
```
|
||||
|
||||
### 验证华为帐号登录
|
||||
在华为手机上打开快应用，点击登录，应弹出华为帐号授权窗口。
|
||||
|
||||
### 验证分析服务
|
||||
集成后可在 AppGallery Connect 控制台查看埋点数据。
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **H5 壳模式限制**：HwService 依赖华为快应用引擎注入的 Bridge，在普通浏览器中不可用
|
||||
2. **真机测试**：必须在华为手机上测试，模拟器可能无法完整模拟 Bridge
|
||||
3. **条件编译生效**：必须通过 HBuilderX 的自定义发行脚本构建，`#ifdef` 标记才会生效
|
||||
4. **clientSecret 安全**：建议由后端接口动态下发，不要前端硬编码
|
||||
5. **登录降级**：如果华为帐号服务不可用，建议提供短信验证码或其他登录方式作为降级方案
|
||||
Reference in New Issue
Block a user