|
@@ -0,0 +1,228 @@
|
|
|
|
|
+# 后台推送:完整实施指南(需你做哪些操作)
|
|
|
|
|
+
|
|
|
|
|
+> 2026-11-18 整理。**当前状态:代码已就绪,但整条链路未打通。**
|
|
|
|
|
+> 用户裁决:暂不做,先记录。本文档供后续启动时直接照着做。
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 一、先说清楚:现在为什么收不到
|
|
|
|
|
+
|
|
|
|
|
+### 现象
|
|
|
|
|
+
|
|
|
|
|
+| 场景 | 能否收到通知 |
|
|
|
|
|
+|---|---|
|
|
|
|
|
+| App 在前台 | ✅ |
|
|
|
|
|
+| 切走后几秒内 | ⚠️ 不稳定 |
|
|
|
|
|
+| **后台超过 1-2 分钟** | ❌ |
|
|
|
|
|
+| App 被杀 / 重启后 | ❌ |
|
|
|
|
|
+
|
|
|
|
|
+### 根因
|
|
|
|
|
+
|
|
|
|
|
+Android 系统在 App 进入后台后会**暂停 WebView 的 JavaScript 执行**。
|
|
|
|
|
+App 里的 `TaskPulseService` 靠定时轮询检测「容器是否回复了」,轮询一停就什么都收不到。
|
|
|
|
|
+
|
|
|
|
|
+**这不是 bug,是 Android 的省电机制。** 唯一解法是**服务端主动推送**。
|
|
|
|
|
+
|
|
|
|
|
+### 完整链路(缺 3 环)
|
|
|
|
|
+
|
|
|
|
|
+```
|
|
|
|
|
+容器回复
|
|
|
|
|
+ ↓
|
|
|
|
|
+Matrix 事件
|
|
|
|
|
+ ↓
|
|
|
|
|
+【缺失 ①】某个后端常驻服务监听 Matrix 新消息
|
|
|
|
|
+ ↓
|
|
|
|
|
+【缺失 ②】根据收件人找到设备推送 ID → 调极光推送 API
|
|
|
|
|
+ ↓
|
|
|
|
|
+极光服务器
|
|
|
|
|
+ ↓
|
|
|
|
|
+【缺失 ③】厂商通道(华为/小米/OPPO/vivo)— 保证 App 被杀也能收到
|
|
|
|
|
+ ↓
|
|
|
|
|
+用户手机
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 二、已经做完的部分(不用你管)
|
|
|
|
|
+
|
|
|
|
|
+| 组件 | 文件 | 状态 |
|
|
|
|
|
+|---|---|---|
|
|
|
|
|
+| Capacitor 桥接插件 | `JPushPlugin.java` | ✅ 已实现 |
|
|
|
|
|
+| SDK 适配层 | `JPushSdk.java` | ✅ 已实现 |
|
|
|
|
|
+| 消息接收器 | `JPushReceiver.java` | ✅ 已实现 |
|
|
|
|
|
+| 点击落地 Activity | `JPushClickActivity.java` | ✅ 已实现 |
|
|
|
|
|
+| 前台服务 | `JPushService.java` | ✅ 已实现 |
|
|
|
|
|
+| 隔离 Manifest(裁掉多余权限) | `android/app/src/jpush/AndroidManifest.xml` | ✅ 已实现 |
|
|
|
|
|
+| 前端状态机 | `src/app/core/jpush.service.ts` | ✅ 已实现 |
|
|
|
|
|
+| 生命周期钩子 | `src/app/core/jpush.lifecycle.ts` | ✅ 已实现 |
|
|
|
|
|
+| Gradle 开关 | `android/app/build.gradle` | ✅ 已实现(默认关) |
|
|
|
|
|
+| 隐私同意门控 | `JPushPlugin.allowed()` | ✅ 已实现 |
|
|
|
|
|
+
|
|
|
|
|
+**当前 APK 里不含推送 SDK**(`fmodeJpushEnabled=false`),权限清单干净,
|
|
|
|
|
+不会申请定位/电话/存储等敏感权限。
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 三、需要你做的事(按顺序)
|
|
|
|
|
+
|
|
|
|
|
+### 第 1 步:注册极光账号,拿 AppKey(约 1 小时)
|
|
|
|
|
+
|
|
|
|
|
+1. 打开 https://www.jiguang.cn ,注册企业账号
|
|
|
|
|
+2. 控制台 → 创建应用
|
|
|
|
|
+ - 应用名:`Fmode`
|
|
|
|
|
+ - 包名:**`cn.fmode.app`**(必须完全一致,否则收不到)
|
|
|
|
|
+3. 记下 **AppKey**(形如 `1a2b3c4d5e6f7g8h9i0j1k2l`)
|
|
|
|
|
+
|
|
|
|
|
+**完成后告诉我 AppKey**,我帮你配进构建。
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+### 第 2 步:申请厂商通道(最慢,1-2 周)
|
|
|
|
|
+
|
|
|
|
|
+**为什么必须做**:没有厂商通道,App 被系统杀掉后极光也推不到。
|
|
|
|
|
+
|
|
|
|
|
+需要逐个申请:
|
|
|
|
|
+
|
|
|
|
|
+| 厂商 | 入口 | 需要什么 | 耗时 |
|
|
|
|
|
+|---|---|---|---|
|
|
|
|
|
+| **华为** | developer.huawei.com → 推送服务 | **企业认证**(营业执照) | 1-2 周 |
|
|
|
|
|
+| **小米** | dev.mi.com → 推送 | 开发者账号 | 1-3 天 |
|
|
|
|
|
+| **OPPO** | open.oppomobile.com → 推送 | 企业认证 | 3-5 天 |
|
|
|
|
|
+| **vivo** | dev.vivo.com.cn → 推送 | 企业认证 | 3-5 天 |
|
|
|
|
|
+
|
|
|
|
|
+每个厂商申请完会给你:
|
|
|
|
|
+- `AppID`
|
|
|
|
|
+- `AppSecret`
|
|
|
|
|
+- `AppKey`(厂商自己的)
|
|
|
|
|
+
|
|
|
|
|
+**这些填到极光控制台** → 你的应用 → 厂商通道配置。
|
|
|
|
|
+
|
|
|
|
|
+> 💡 **可以先只做华为 + 小米**(覆盖大部分安卓用户),其余后续补。
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+### 第 3 步:配置隐私同意 UI(App 侧,我来做)
|
|
|
|
|
+
|
|
|
|
|
+推送 SDK 启动了就必须有用户同意。当前代码已实现门控:
|
|
|
|
|
+
|
|
|
|
|
+```typescript
|
|
|
|
|
+// JPushPlugin.allowed() 检查:
|
|
|
|
|
+BuildConfig.JPUSH_ENABLED === true
|
|
|
|
|
+ && SharedPreferences("fmode-jpush").getBoolean("consent", false)
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**需要补的**:一个「开启推送通知」的开关界面(可以复用现有的通知权限引导弹层)。
|
|
|
|
|
+
|
|
|
|
|
+这一步**我来写**,你确认界面文案即可。
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+### 第 4 步:开发服务端推送链路(平台来做,5-10 天)
|
|
|
|
|
+
|
|
|
|
|
+**这是最关键、也最缺的一环。**
|
|
|
|
|
+
|
|
|
|
|
+需要一个常驻服务,做两件事:
|
|
|
|
|
+
|
|
|
|
|
+```
|
|
|
|
|
+① 监听 Matrix 新消息
|
|
|
|
|
+ · 用 Matrix 应用服务(Application Service)或长轮询 /sync
|
|
|
|
|
+ · 识别「接收方是谁」
|
|
|
|
|
+
|
|
|
|
|
+② 调极光推送 API
|
|
|
|
|
+ POST https://api.jpush.cn/v3/push
|
|
|
|
|
+ Header: Authorization: Basic base64(AppKey:MasterSecret)
|
|
|
|
|
+ Body: {
|
|
|
|
|
+ "platform": "android",
|
|
|
|
|
+ "audience": { "alias": ["<用户ID>"] },
|
|
|
|
|
+ "notification": { "alert": "容器回复了", "title": "Fmode" },
|
|
|
|
|
+ "options": { "apns_production": false }
|
|
|
|
|
+ }
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**依赖第 5 步的别名系统**。
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+### 第 5 步:开发别名签发后台(平台来做,3-5 天)
|
|
|
|
|
+
|
|
|
|
|
+极光用「别名(alias)」识别设备。需要:
|
|
|
|
|
+
|
|
|
|
|
+```
|
|
|
|
|
+用户登录 App
|
|
|
|
|
+ ↓
|
|
|
|
|
+App 调极光 SDK 拿到 registrationId
|
|
|
|
|
+ ↓
|
|
|
|
|
+App 调你的接口:POST /api/bind-push-alias
|
|
|
|
|
+ { alias: "fm_<32位hash>", registrationId: "..." }
|
|
|
|
|
+ ↓
|
|
|
|
|
+服务端存表:userId ↔ alias ↔ registrationId
|
|
|
|
|
+ ↓
|
|
|
|
|
+推送时:userId → alias → 极光推送
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**当前代码已有约束**:别名必须匹配 `/^fm_[a-f0-9]{32,60}$/`(见 `jpush.service.ts`),
|
|
|
|
|
+所以别名格式要按这个来。
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 四、总工作量与顺序
|
|
|
|
|
+
|
|
|
|
|
+| 步骤 | 谁做 | 耗时 | 能否并行 |
|
|
|
|
|
+|---|---|---|---|
|
|
|
|
|
+| 1. 极光 AppKey | **你** | 1 小时 | — |
|
|
|
|
|
+| 2. 厂商通道 | **你** | 1-2 周 | ✅ 可与 4/5 并行 |
|
|
|
|
|
+| 3. 隐私同意 UI | 我 | 0.5 天 | 等 1 完成 |
|
|
|
|
|
+| 4. 服务端推送链路 | 平台 | 5-10 天 | ✅ 可与 2 并行 |
|
|
|
|
|
+| 5. 别名签发后台 | 平台 | 3-5 天 | ✅ 可与 4 并行 |
|
|
|
|
|
+
|
|
|
|
|
+**关键路径**:第 2 步(厂商通道)最慢,**应该最先启动**。
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 五、如果暂时不做
|
|
|
|
|
+
|
|
|
|
|
+建议在 App 里明确告知用户,避免「为什么收不到消息」的困惑:
|
|
|
|
|
+
|
|
|
|
|
+```
|
|
|
|
|
+消息通知仅在 App 打开时生效。
|
|
|
|
|
+关闭 App 后将无法收到新消息提醒,请保持 App 在后台运行。
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+这个提示我可以加到「我的 → 通知」页面。
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 六、验收标准
|
|
|
|
|
+
|
|
|
|
|
+全部完成后,以下场景都应收到通知:
|
|
|
|
|
+
|
|
|
|
|
+| 场景 | 预期 |
|
|
|
|
|
+|---|---|
|
|
|
|
|
+| App 在前台 | ✅ 收到 |
|
|
|
|
|
+| App 切后台 1 分钟 | ✅ 收到 |
|
|
|
|
|
+| App 切后台 30 分钟 | ✅ 收到 |
|
|
|
|
|
+| App 被划掉(进程杀掉) | ✅ 收到(**需厂商通道**) |
|
|
|
|
|
+| 手机重启后 | ✅ 收到 |
|
|
|
|
|
+| 点击通知 | ✅ 拉起 App 并跳到对应会话 |
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 七、常见坑(提前知道)
|
|
|
|
|
+
|
|
|
|
|
+| 坑 | 说明 |
|
|
|
|
|
+|---|---|
|
|
|
|
|
+| **包名不一致** | 极光后台填的包名必须与 `cn.fmode.app` 完全一致 |
|
|
|
|
|
+| **华为需企业认证** | 没有营业执照做不了,个人账号不行 |
|
|
|
|
|
+| **极光免费版有频率限制** | 免费版每天推送次数有限,商用需付费 |
|
|
|
|
|
+| **别名要清理** | 用户登出时调 `deleteAlias`,否则换账号会收到前一个人的消息(代码已实现 `unbindAccount()`) |
|
|
|
|
|
+| **厂商通道要逐个开** | 只配华为不代表小米能收到 |
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 八、现在能立刻做的一件事
|
|
|
|
|
+
|
|
|
|
|
+如果你暂时不想投入 2 周等厂商审核,可以**先只做「前台通知」的产品化说明**:
|
|
|
|
|
+
|
|
|
|
|
+在「我的 → 通知」页把文案改成准确的描述,让用户知道限制。
|
|
|
|
|
+
|
|
|
|
|
+**要我改吗?** 一句话的事。
|