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