124 lines
4.9 KiB
Markdown
124 lines
4.9 KiB
Markdown
# 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）/通知样式与点击跳转”纳入需求范围，请在本文基础上补充对应厂商后台开通、证书参数与多通道策略。 |