lucky_shop/docs/hwservice-integration-guide.md

华为快应用 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
2. 创建应用（选择「快应用」类型）
3. 开启以下服务：
   • 华为帐号服务 (Account Kit)
   • 华为分析服务 (Analytics Kit)（可选）
   • 华为推送服务 (Push Kit)（可选）
4. 下载 agconnect-services.json 配置文件
5. 将配置文件放入项目根目录

2. 安装 npm 依赖

# 基础桥接库（必装，提供 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 配置项：

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:女）

返回格式（需与现有登录接口保持一致）：

{
    "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 是否可用

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. 登录降级：如果华为帐号服务不可用，建议提供短信验证码或其他登录方式作为降级方案