|
|
@@ -0,0 +1,309 @@
|
|
|
+# 后台推送:具体操作步骤(可照做)
|
|
|
+
|
|
|
+> 2026-11-18 · 基于当前代码实际状态编写,每步含**命令/入口/验收方式**。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 现状速览
|
|
|
+
|
|
|
+| 项 | 状态 |
|
|
|
+|---|---|
|
|
|
+| 推送代码(原生插件 + 前端) | ✅ 已写完,10 个组件齐全 |
|
|
|
+| Gradle 开关 `fmodeJpushEnabled` | ⚠️ 默认 `false` |
|
|
|
+| 前端开关 `JPUSH_OPTIONS.enabled` | ⚠️ 硬编码 `false` |
|
|
|
+| 极光 AppKey | ❌ 没有 |
|
|
|
+| 厂商通道证书 | ❌ 没有 |
|
|
|
+| 服务端推送链路 | ❌ 没有 |
|
|
|
+| 别名签发后台 | ❌ 没有 |
|
|
|
+| 隐私同意 UI | ❌ 没接入 |
|
|
|
+
|
|
|
+**当前 APK 不含推送 SDK**,权限干净,不会申请定位/电话/存储。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 第一阶段:App 侧配置(我能做,需要你先给 AppKey)
|
|
|
+
|
|
|
+## 步骤 1:注册极光账号拿 AppKey
|
|
|
+
|
|
|
+**你要做的:**
|
|
|
+
|
|
|
+1. 打开 https://www.jiguang.cn ,注册(建议企业账号)
|
|
|
+2. 登录后 → 「创建应用」
|
|
|
+3. 填写:
|
|
|
+ - **应用名称**:`Fmode`
|
|
|
+ - **Android 包名**:`cn.fmode.app` ⚠️ **必须一字不差**
|
|
|
+4. 创建成功后,在应用详情页找到:
|
|
|
+ - **AppKey**(形如 `1a2b3c4d5e6f7a8b9c0d1e2f`)
|
|
|
+ - **Master Secret**(服务端调 API 用,**不要放进前端**)
|
|
|
+
|
|
|
+**验收**:你能看到一个 24 位左右的 AppKey。
|
|
|
+
|
|
|
+**然后告诉我 AppKey**,接下来的步骤我来做。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 步骤 2:我配置 App 构建(约 30 分钟)
|
|
|
+
|
|
|
+拿到 AppKey 后我会做这些:
|
|
|
+
|
|
|
+### 2.1 打开 Gradle 开关
|
|
|
+
|
|
|
+`android/gradle.properties` 追加:
|
|
|
+```properties
|
|
|
+fmodeJpushEnabled=true
|
|
|
+```
|
|
|
+
|
|
|
+AppKey 通过环境变量传入(**不写进仓库**):
|
|
|
+```bash
|
|
|
+export JPUSH_APPKEY=<你给的 AppKey>
|
|
|
+```
|
|
|
+
|
|
|
+### 2.2 打开前端开关
|
|
|
+
|
|
|
+`src/app/core/jpush.plugin.ts` 第 36 行:
|
|
|
+```typescript
|
|
|
+factory: () => ({ enabled: false }), // 改成 true
|
|
|
+```
|
|
|
+
|
|
|
+### 2.3 接入隐私同意 UI
|
|
|
+
|
|
|
+推送 SDK 启动前**必须**用户同意(代码已强制门控):
|
|
|
+
|
|
|
+```
|
|
|
+JPushPlugin.allowed() =
|
|
|
+ BuildConfig.JPUSH_ENABLED === true
|
|
|
+ && SharedPreferences("fmode-jpush").getBoolean("consent", false)
|
|
|
+```
|
|
|
+
|
|
|
+我会在「我的 → 通知」页加一个开关:
|
|
|
+```
|
|
|
+[ ] 开启后台消息推送
|
|
|
+ 开启后可在地关闭 App 时收到新消息提醒
|
|
|
+```
|
|
|
+
|
|
|
+用户打开时调用 `push.start(true)`(传 `privacyConsent: true`)。
|
|
|
+
|
|
|
+### 2.4 构建验证
|
|
|
+
|
|
|
+```bash
|
|
|
+export JPUSH_APPKEY=<AppKey>
|
|
|
+pnpm run build && npx cap sync android
|
|
|
+cd android && ./gradlew assembleDebug
|
|
|
+```
|
|
|
+
|
|
|
+**验收**:
|
|
|
+```bash
|
|
|
+# APK 内应出现 JPush 类
|
|
|
+unzip -l android/app/build/outputs/apk/debug/app-debug.apk | grep -ci jiguang
|
|
|
+# 应 > 0
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 第二阶段:厂商通道(你做,1-2 周,⭐ 最慢,先启动)
|
|
|
+
|
|
|
+**为什么必须**:没有厂商通道,App 被系统杀掉后**极光也推不到**。
|
|
|
+
|
|
|
+## 步骤 3:申请厂商推送服务
|
|
|
+
|
|
|
+按优先级申请(先做华为 + 小米,覆盖大部分用户):
|
|
|
+
|
|
|
+### 华为推送(1-2 周,需企业认证)
|
|
|
+
|
|
|
+1. 打开 https://developer.huawei.com ,注册开发者
|
|
|
+2. 完成**企业实名认证**(需要营业执照)
|
|
|
+3. 控制台 → 「我的项目」→ 创建项目 → 添加应用
|
|
|
+ - 包名:`cn.fmode.app`
|
|
|
+ - 上传**签名证书指纹**(需要你的 APK 签名,我可以帮你取)
|
|
|
+4. 开通「Push Kit」服务
|
|
|
+5. 记录:**AppID**、**AppSecret**
|
|
|
+
|
|
|
+### 小米推送(1-3 天)
|
|
|
+
|
|
|
+1. 打开 https://dev.mi.com ,注册开发者
|
|
|
+2. 控制台 → 消息推送 → 创建应用
|
|
|
+ - 包名:`cn.fmode.app`
|
|
|
+3. 记录:**AppID**、**AppKey**、**AppSecret**
|
|
|
+
|
|
|
+### OPPO / vivo(各 3-5 天,可选)
|
|
|
+
|
|
|
+同理,需要企业认证。
|
|
|
+
|
|
|
+## 步骤 4:把厂商凭证填进极光
|
|
|
+
|
|
|
+**你要做的:**
|
|
|
+
|
|
|
+极光控制台 → 你的应用 → 「应用设置」→「厂商通道」
|
|
|
+逐个填入上一步拿到的凭证。
|
|
|
+
|
|
|
+**验收**:极光控制台显示各厂商通道状态为「已开启」。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 第三阶段:服务端开发(平台做,5-10 天)
|
|
|
+
|
|
|
+**这是最关键、也最缺的一环。** 可以和第二阶段的厂商审核**并行**。
|
|
|
+
|
|
|
+## 步骤 5:别名签发后台
|
|
|
+
|
|
|
+**目标**:让服务端知道「哪个用户 → 哪台设备」。
|
|
|
+
|
|
|
+### 接口设计
|
|
|
+
|
|
|
+```
|
|
|
+POST /api/bind-push-alias
|
|
|
+Header: X-Parse-Session-Token: <用户token>
|
|
|
+Body: { alias: "fm_<32位hex>", registrationId: "<极光返回的>" }
|
|
|
+
|
|
|
+响应: { code: 200 }
|
|
|
+```
|
|
|
+
|
|
|
+### 数据表
|
|
|
+
|
|
|
+```sql
|
|
|
+CREATE TABLE PushBinding (
|
|
|
+ userId TEXT PRIMARY KEY,
|
|
|
+ alias TEXT NOT NULL,
|
|
|
+ registrationId TEXT NOT NULL,
|
|
|
+ updatedAt TIMESTAMP
|
|
|
+);
|
|
|
+```
|
|
|
+
|
|
|
+### 别名格式约束(代码已强制)
|
|
|
+
|
|
|
+`src/app/core/jpush.service.ts` 要求:
|
|
|
+```typescript
|
|
|
+/^fm_[a-f0-9]{32,60}$/
|
|
|
+```
|
|
|
+
|
|
|
+所以别名必须是 `fm_` + 32~60 位十六进制。
|
|
|
+
|
|
|
+### App 侧要配合的(我来写)
|
|
|
+
|
|
|
+用户登录成功后:
|
|
|
+```typescript
|
|
|
+const registrationId = await push.getRegistrationId();
|
|
|
+const alias = 'fm_' + hash(userId); // 稳定、不可反推
|
|
|
+await fetch('/api/bind-push-alias', { ... });
|
|
|
+```
|
|
|
+
|
|
|
+用户登出时调 `push.unbindAccount()`(代码已实现)。
|
|
|
+
|
|
|
+**验收**:
|
|
|
+```bash
|
|
|
+# 登录 App 后,数据库应出现一条 PushBinding 记录
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 步骤 6:服务端监听 Matrix → 推送
|
|
|
+
|
|
|
+### 架构
|
|
|
+
|
|
|
+```
|
|
|
+常驻进程(Node/Python 均可)
|
|
|
+ │
|
|
|
+ ├─ 用 Matrix Application Service 或 /sync 长轮询
|
|
|
+ │ 监听所有用户的房间新消息
|
|
|
+ │
|
|
|
+ ├─ 判断「这条消息的接收者是谁」
|
|
|
+ │ 排除自己发的、排除容器自己的回显
|
|
|
+ │
|
|
|
+ ├─ 查 PushBinding:userId → alias
|
|
|
+ │
|
|
|
+ └─ POST https://api.jpush.cn/v3/push
|
|
|
+```
|
|
|
+
|
|
|
+### 推送 API 示例
|
|
|
+
|
|
|
+```bash
|
|
|
+curl -X POST https://api.jpush.cn/v3/push \
|
|
|
+ -H "Authorization: Basic $(echo -n 'APPKEY:MASTER_SECRET' | base64)" \
|
|
|
+ -H "Content-Type: application/json" \
|
|
|
+ -d '{
|
|
|
+ "platform": "android",
|
|
|
+ "audience": { "alias": ["fm_a1b2c3d4e5f6..."] },
|
|
|
+ "notification": {
|
|
|
+ "alert": "容器回复了你的消息",
|
|
|
+ "title": "Fmode",
|
|
|
+ "android": { "extras": { "fmodeJpushPayload": "{\"sessionId\":\"...\"}" } }
|
|
|
+ },
|
|
|
+ "options": { "time_to_live": 86400 }
|
|
|
+ }'
|
|
|
+```
|
|
|
+
|
|
|
+> ⚠️ `extras.fmodeJpushPayload` 这个 key **必须一致** —— App 端 `JPushClickActivity`
|
|
|
+> 靠它解析点击后跳转到哪个会话。
|
|
|
+
|
|
|
+**验收**:
|
|
|
+```bash
|
|
|
+# 手动调一次推送 API,手机应收到通知
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 第四阶段:联调验收
|
|
|
+
|
|
|
+## 步骤 7:逐场景测试
|
|
|
+
|
|
|
+| # | 场景 | 预期 | 由谁测 |
|
|
|
+|---|---|---|---|
|
|
|
+| 1 | App 在前台收到消息 | 通知出现 | 你 |
|
|
|
+| 2 | App 切后台 1 分钟 | 通知出现 | 你 |
|
|
|
+| 3 | App 切后台 30 分钟 | 通知出现 | 你 |
|
|
|
+| 4 | App 被划掉(进程杀掉) | **通知出现**(需厂商通道) | 你 |
|
|
|
+| 5 | 手机重启后 | 通知出现 | 你 |
|
|
|
+| 6 | 点通知 | 拉起 App + 跳到对应会话 | 你 |
|
|
|
+| 7 | 换账号登录 | 收不到前一个账号的消息 | 你 |
|
|
|
+| 8 | 关闭推送开关 | 收不到任何推送 | 你 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 总览:谁做什么、要多久
|
|
|
+
|
|
|
+| 步骤 | 内容 | 谁 | 耗时 | 能否并行 |
|
|
|
+|---|---|---|---|---|
|
|
|
+| 1 | 注册极光拿 AppKey | **你** | 1 小时 | — |
|
|
|
+| 2 | App 构建配置 | 我 | 30 分钟 | 等步骤 1 |
|
|
|
+| 3 | **申请厂商通道** | **你** | **1-2 周** ⭐ | ✅ 可与其他并行 |
|
|
|
+| 4 | 厂商凭证填极光 | 你 | 10 分钟 | 等步骤 3 |
|
|
|
+| 5 | 别名签发后台 | 平台 | 3-5 天 | ✅ 可与步骤 3 并行 |
|
|
|
+| 6 | 服务端推送链路 | 平台 | 5-10 天 | ✅ 可与步骤 3 并行 |
|
|
|
+| 7 | 联调验收 | 你 + 我 | 1 天 | 等前面全部完成 |
|
|
|
+
|
|
|
+### 关键路径
|
|
|
+
|
|
|
+```
|
|
|
+步骤 3(厂商通道 1-2 周)
|
|
|
+ ↓
|
|
|
+步骤 4 → 步骤 7(联调)
|
|
|
+```
|
|
|
+
|
|
|
+**建议:立刻启动步骤 3 的华为认证**,因为它是唯一卡 1-2 周的环节。
|
|
|
+步骤 1/5/6 都可以在这期间并行完成。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 如果暂时不做
|
|
|
+
|
|
|
+建议先把「我的 → 通知」的文案改准确,避免用户困惑:
|
|
|
+
|
|
|
+```
|
|
|
+消息通知仅在 App 打开时生效。
|
|
|
+关闭 App 后将无法收到新消息提醒。
|
|
|
+```
|
|
|
+
|
|
|
+**要我现在就改这个文案吗?** 一句话的事,能让用户明白限制。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 附:常见坑
|
|
|
+
|
|
|
+| 坑 | 影响 | 怎么避 |
|
|
|
+|---|---|---|
|
|
|
+| 包名不一致 | 完全收不到 | 极光后台填 `cn.fmode.app`,一字不差 |
|
|
|
+| 华为需企业认证 | 做不了 | 提前准备营业执照 |
|
|
|
+| 忘了清理别名 | 换账号收到前一个人的消息 | 登出时调 `unbindAccount()`(已实现) |
|
|
|
+| 只配华为没配小米 | 小米手机收不到 | 各厂商要逐个配 |
|
|
|
+| `fmodeJpushPayload` key 写错 | 点通知跳转失败 | 与 `JPushClickActivity` 的 `CLICK_EXTRA` 保持一致 |
|
|
|
+| 极光免费版限流 | 推送失败 | 商用需付费版 |
|