medical-mall/pages/mall/delivery/doc/需求文档/uni-push2_安卓联调与取CID说明.md

uni-push2 安卓联调与取 CID 说明

1. 目的与范围

本文档用于记录本项目在 uni-app x（UVUE + UTS） 下，对 DCloud 统一推送 uni-push2 的安卓端最小化接入与验证流程，目标是完成闭环：

1. 真机运行应用
2. 获取 CID（clientId）
3. 在 uni-push2 控制台使用“指定 CID”推送
4. 设备收到推送（通知栏/透传回调）

说明：本文聚焦“能跑通验证链路”的最小方案；厂商通道（小米/华为等）的离线推送配置属于后续增强。

2. 关键结论（先看这个）

• 调试基座 ≠ 你的应用：在 HBuilderX 使用“运行到 Android 设备（标准基座）”拿到的 CID，归属是“基座应用”，因此在你的 uni-push2 应用里按 CID 推送会提示“CID 不存在或不属于此应用”。
• 要让 CID 归属正确，必须使用 云打包/本地打包 生成的 你自己的 APK，安装到手机后再获取 CID。
• 不依赖控制台日志获取 CID：为了避免无法抓取 logcat 的情况，已实现 把 CID 写入本地存储，并在 minimal 页面 直接展示 + 点击复制。

3. 环境说明

• 框架：uni-app x（UVUE + UTS）
• 平台：Android 真机（红米/小米系统 MIUI/HyperOS 等）
• 推送：DCloud uni-push2

4. 客户端实现（最小可用）

4.1 App 启动初始化与监听

在应用启动时：

• 调用 uni.onPushMessage 监听推送回调（用于验证是否收到推送/透传）
• 调用 uni.getPushClientId 获取 CID
• 将 CID 输出日志，同时写入本地存储 uni_push2_cid

涉及文件：

• App.uvue

注意事项（UTS 语法/类型限制）：

• UTS 对 Any/Any? 较严格，不能随意使用 TS 写法（如 (x as any)）
• 对 ret.cid 这类对 Any 的直接属性访问可能编译失败，需要用 UTSJSONObject 或字符串兜底

4.2 minimal 页面展示 CID 并一键复制

为了不依赖 HBuilderX 控制台/adb：

• 从本地存储读取 uni_push2_cid
• 页面展示 CID
• 点击 CID 触发 uni.setClipboardData 复制

涉及文件：

• pages/minimal.uvue

5. 打包与安装（验证闭环必需）

5.1 云打包

• 在 HBuilderX 执行 Android 云端打包
• 打包成功后会得到下载链接

下载次数限制（常见问题）：

• 云端下载链接可能存在短时间“下载次数超限”
• 规避策略：
  • 尽量 只下载一次并备份（网盘/U盘/微信文件传输助手）
  • 必要时更换网络/IP（例如手机热点）
  • 仍受限时，重新云打包生成新下载链接

5.2 手机安装与启动

• 建议卸载旧的调试基座或旧包，避免混淆
• 通过系统安装 APK
• 桌面无图标时（MIUI/HyperOS 常见）：
  • 在系统“应用列表/管理应用”中搜索应用名进入详情页打开
  • 或在应用抽屉里搜索应用名，长按拖到桌面

6. 获取 CID 的两种方式

6.1 推荐：从 minimal 页面直接复制（无需日志）

步骤：

1. 安装云打包 APK
2. 打开应用进入 Minimal Test Page
3. 等待 10–30 秒（必要时重启一次 App）
4. 页面显示 CID，点击即可复制

6.2 备选：adb logcat 抓日志（需要电脑装 adb）

• 电脑安装 Android SDK Platform-Tools
• 开启手机 USB 调试并授权
• 使用 adb logcat 过滤关键词（如：uni-push2、clientId、cid）

说明：不建议通过 HBuilderX “运行到 Android 设备（标准基座）”来取日志，因为会回到基座环境，CID 归属不正确。

7. 控制台推送验证步骤

1. 确认使用的 uni-push2 控制台账号/应用，与打包 APK 对应的 AppID 一致
2. 在控制台选择“消息推送/测试推送 → 指定 CID”
3. 粘贴从 minimal 页面复制的 CID
4. 发送通知消息

如果提示“CID 不存在或不属于此应用”，按以下顺序排查：

• 是否仍在使用调试基座的 CID（需要用云打包 APK 重新取 CID）
• 是否账号/应用选错（AppID 不一致）
• 是否刚安装/首次启动（CID 同步可能有延迟，等 1–3 分钟再试）

8. 厂商通道（小米等）说明（可选）

• 厂商通道用于离线推送/更稳定通知
• 若云打包勾选/启用小米推送模块但未配置参数，可能触发校验提示
• 最小验证路径：先确保能完成“在线推送/控制台指定 CID”闭环，再按需要补齐厂商通道

9. 本次相关改动点（便于回溯）

• App.uvue
  • 初始化 uni.onPushMessage
  • 获取 CID 并写入 uni.setStorageSync('uni_push2_cid', cid)
• pages/minimal.uvue
  • 读取 uni.getStorageSync('uni_push2_cid')
  • 展示 CID，点击复制
  • 修复 UTS 的 Any? 类型推断问题（避免强制标注 any）

---

如需把“推送触达率/离线推送（小米/华为/OPPO/vivo）/通知样式与点击跳转”纳入需求范围，请在本文基础上补充对应厂商后台开通、证书参数与多通道策略。