# 极光推送子任务:配置与整合交接 核查日期:2026-11-16。仅 Android;不依赖微信登录、企微 SDK 或分享模块。 ## 主源核验与选择 - 优先主源 `ahhxyz/jpush-capacitor-plugin` 的 HEAD 为 `fea7722187bd83e8e521cfe5725638fe273d1a4c`,`package.json` 标为 4.0.6,`plugin.xml` 仍标为 3.8.2。 - 它实际为 Cordova 插件,入口是 `www/JPushPlugin.js`,依赖回调式 `init`、`getRegistrationID`、`setAlias`、`deleteAlias`,不是现代 Capacitor TypeScript 插件。 - `src/android/JPushPlugin.java` 直接导入 `cn.fits.plugins.jpush.FitsPushPlugin`,并在 `initialize` 解引用 `FitsPushPlugin.jpushIntent.toString()`;该依赖在 `plugin.xml` 中被注释。不能直接作为当前工程可构建、可冷启动的 Capacitor 8 插件。 - 主源同时捆绑 JPush Android 4.6.3、JCore 3.2.2、旧厂商 jar/aar,并声明定位、存储、读取电话状态、查询安装列表等权限。未通过真实安装/真机验证;不能把这些事实概括成“所有 Cordova 插件都不支持 Capacitor 8”。 - `registry.npmjs.org/jpush-capacitor-plugin` 核查返回 404,GitHub API 命中限流;版本和提交来自 raw 主源与 `git ls-remote`,不声称查到了不存在的 npm 发布版本。 - 因以上具体源码缺口采用用户允许的局部自建 Capacitor 插件,保持现有 Capacitor 8.6.2。官方 Maven Central 当前稳定版本为 JPush 6.3.1(元数据更新 2026-11-10)、JCore 5.6.0(2026-10-26);依赖固定版本,排除 JPush POM 的动态 JCore 范围。 - 已下载这两个官方 AAR 到系统临时目录,并通过 `javap` 核实实际签名:`JPushInterface.init/getRegistrationID/setAlias/deleteAlias/stopPush/resumePush`、`JPushMessageReceiver`、`JCommonService`、`JCollectionAuth.setAuth`。不将 SDK 二进制提交仓库。 主源与官方资料: - https://github.com/ahhxyz/jpush-capacitor-plugin - https://raw.githubusercontent.com/ahhxyz/jpush-capacitor-plugin/master/package.json - https://raw.githubusercontent.com/ahhxyz/jpush-capacitor-plugin/master/plugin.xml - https://raw.githubusercontent.com/ahhxyz/jpush-capacitor-plugin/master/src/android/JPushPlugin.java - https://docs.jiguang.cn/jpush/client/Android/android_guide - https://docs.jiguang.cn/jpush/client/Android/android_api - https://repo.maven.apache.org/maven2/cn/jiguang/sdk/jpush/maven-metadata.xml - https://repo.maven.apache.org/maven2/cn/jiguang/sdk/jcore/maven-metadata.xml ## 默认安全行为 `JPUSH_OPTIONS.enabled` 默认 `false`;Gradle `fmodeJpushEnabled` 默认 `false`。默认 APK 仅编译 `JPushPlugin` 桥接,不包含 JPush/JCore AAR,也不编译依赖 SDK 的四个 Java 文件。未提供 AppKey 不影响默认构建,SDK 不会启动。 即使显式打开 Gradle 开关,缺少合法 AppKey、声明的 Receiver/Service/点击 Activity,或保留 SDK 自动初始化 Provider,`getStatus()` 也返回不可用,`start()` 拒绝启动。原生 `start` 还要求 `privacyConsent: true`;TS 入口亦要求明确同意,不在启动时自动弹通知权限。 `phase=started` 只表示桥接初始化并完成清理旧别名,不代表已经获得注册 ID、服务器投递成功或具备离线到达能力。`registrationId` 初始为 `null`,仅接受 SDK 查询/注册回调真实返回值,不生成假 ID。`getStatus` 不返回 AppKey、别名、Token 或个人信息。 ## 主代理必须完成的整合 以下受限文件本子任务没有修改;未完成整合前保持两端开关关闭。 ### 1. MainActivity.java 在现有 `onCreate` 的 `super.onCreate(savedInstanceState)` 之前,与现有插件注册并列添加: ```java registerPlugin(JPushPlugin.class); ``` 不需要改 `onNewIntent`,Capacitor 的插件生命周期会把 Intent 交给 `JPushPlugin.handleOnNewIntent`。本插件专用 extra 为 `fmodeJpushPayload`,不复用旧 `deepLink` extra,避免 `FmodeNotifyPlugin` 再导航一次。 ### 2. AndroidManifest.xml(仅启用 SDK 的构建) 当前 `android/app/src/main/AndroidManifest.xml` 不需要推送修改,保留主代理的分享/深链等更改。下面三个组件只有开启 Gradle 开关才会编译,不能把它们直接放进默认 main manifest。 请由主代理新建 `android/app/src/jpush/AndroidManifest.xml`,完整内容如下。推送 Gradle 段已实现:仅当 `fmodeJpushEnabled=true` 且此文件存在时,作为 debug/release overlay 合并;默认完全不使用。此文件未创建也能做 SDK 编译检查,但运行门禁会阻止 SDK 启动。 ```xml ``` SDK AAR 自带 `JPUSH_APPKEY`、`JPUSH_CHANNEL` metadata,Gradle 已提供 placeholders,无需重复 metadata。移除 InitProvider 避免其早于 JS/用户同意执行;原生状态门禁也会检查这一点。 注意 SDK 5.4.0 以后回调 action 是 `RECEIVER_MESSAGE`,不是旧插件中的 `RECEIVE_MESSAGE`;原生门禁会拒绝错误的过滤器。 审查并移除 AAR 带入但本功能不需要的权限:`ACCESS_COARSE_LOCATION`、`ACCESS_FINE_LOCATION`、`ACCESS_BACKGROUND_LOCATION`、`READ_PHONE_STATE`、`QUERY_ALL_PACKAGES`、`WRITE_EXTERNAL_STORAGE`、`READ_EXTERNAL_STORAGE`。使用 ``。保留网络与通知所需权限;不要重新加入精确闹钟权限。检查所有最终 merged manifest,不只检查源码。 ### 3. Gradle / AppKey 默认验证命令:`android/gradlew.bat :app:assembleDebug`。 准备好推送构建的 manifest 后,由 CI/受保护本机环境注入 `JPUSH_APPKEY`,然后使用 `-PfmodeJpushEnabled=true`。不要在命令参数、仓库文件或构建日志中打印其值。AppKey 是客户端应用标识,不是可保密的服务端凭据;JPush Master Secret 必须只在受信任服务端,绝不放进 APK/TS。 ### 4. app.config.ts / 登录生命周期 在 `app.config.ts` 的 imports 中增加: ```ts import { provideJPushLifecycle } from './core/jpush.lifecycle'; ``` 在现有 `providers` 数组中增加一项,不替换已有 initializer: ```ts provideJPushLifecycle(), ``` 该 provider 通过真正的 Angular AppInitializer 调用 `JPushService.start()`,**不传 `true`**。默认禁用立即返回 `false`;即使以后配置 enabled,也会先停在 `privacy-consent-required`,不会把 bootstrap 当作用户同意。它还创建 root 生命周期监听:既有 SessionService 的账号/租户变化或登出会请求 `unbindAccount()`,不需要修改 SessionService,也不读取或发送 Token。 - 启用配置时另导入 `JPUSH_OPTIONS` 并添加 `{ provide: JPUSH_OPTIONS, useValue: { enabled: true } }`;默认不要增加这一项。 - 用户明确同意极光隐私告知后调用 `JPushService.start(true)`,不要以通知权限等同隐私同意,也不要阻塞应用首屏等待网络。 - 仅在用户主动申请时调用 `requestPermission()`,其复用现有 `AppNotificationService.request()`;已有权限引导保留。 - 现有任意登录方式均可用。由受信任后台按已认证账号/租户签发不透明、稳定别名 `fm_` 加 32–60 个小写十六进制字符,再调用 `bindAccount(alias)`。不得传手机号、姓名、邮箱、sessionToken,不建议用这些字段的无盐散列代替不透明别名。 - `start` 先清理 SDK 留存的旧别名;`bindAccount` 先删除旧别名再设置新别名。所有操作串行,仅收到 SDK 成功回执才返回成功,15 秒超时返回失败。 - 登出/切号先 `await unbindAccount()`;失败不会伪报解绑成功,会停止推送并显示 `binding=error`。身份登出不应因离线而永远阻塞。下次启动/绑定会先重试清理;后台也必须注销原账号的设备关联,不能只依赖设备在线删别名。 - 撤回隐私同意或销毁能力调用 `stop()`。它尝试解绑、停止 SDK、撤回本地 SDK 同意标志并移除本服务监听,不动旧本地通知服务。 - `registrationId()` 仅保存在内存信号;需要设备登记时经已认证后端传输,不打印、不落日志。本子任务不虚构登记接口。 - `package.json`、锁文件、`capacitor.config.ts` 不需要添加旧插件或降级 Capacitor。 当前可用连接点:隐私同意事件调用 `start(true)`,拒绝/撤回调用 `stop()`,已有通知权限 UI 调用 `requestPermission()`,后台签发别名返回后调用 `bindAccount(alias)`,主动登出可在清会话前 `await unbindAccount()`。root 监听是主动解绑漏接时的补充,不代替需要精确 await 的登出流程。 **当前尚未连接**:没有伪造别名签发后台,没有给现有登录成功逻辑硬编码 alias,也没有现成的极光隐私同意 UI 可擅自复用;这些入口只有在主代理接上实际 UI/已鉴权后台后才可用。主代理只加本节 initializer 并不代表账号推送完整打通。后台返回较慢时,调用方必须确认当前账号/租户仍是发起请求时的身份再绑定。 ### 5. 隔离的 enabled 编译检查 `android/jpush-compile-check.init.gradle` 支持通过 `FMODE_JPUSH_TEST_BUILD_DIR` 将 app 编译产物全部放入一次性临时目录。检查时只在子进程环境提供全零、非秘密的 24 位合成 AppKey,关闭 Gradle build/configuration cache,只运行 `:app:compileDebugJavaWithJavac -PfmodeJpushEnabled=true`。不生成发布 APK,不连接设备,不执行 SDK 启动;之后恢复环境并删除经过路径校验的临时目录。合成 AppKey 不写入仓库、文档示例、受保护配置或发布产物。 ## 通知内容与点击合同 推荐服务端 notification extras 仅携带: ```json { "businessKey": "task-completed:opaque-event-id", "deepLink": "fmode://chat/opaque-agent-id/opaque-session-id" } ``` 不得携带 Token、电话号码或不必要的个人信息。服务端还要校验目标账号有权读取目标对象;深链本身不授予权限。 - 收到 SDK notification 只记去重键,不再调用本地通知,避免同一远程通知被二次展示。 - 收到 data/custom message 且 JS 存活时,复用 `AppNotificationService.notify()`(包括既有权限、渠道、点击与按 key 覆盖)。JS 不存在时不补造“离线数据消息通知”。 - 冷启动点击:服务端 Android notification 使用 `intent:#Intent;component=cn.fmode.app/cn.fmode.app.JPushClickActivity;end` 作为点击 Intent,SDK 把 `JMessageExtra` 传入该 Activity。解析 `msg_id`/`n_extras` 后转交 MainActivity,插件 `load` 保留事件直至 JS 监听就绪;热启动走插件 `handleOnNewIntent`。 - `JPushReceiver.onNotifyMessageOpened` 为已存活桥接提供另一路回调;不在 BroadcastReceiver 中拉 Activity,避免 Android 12+ notification trampoline。两路按消息 ID 去重。 - TS 点击统一调用既有 `DeepLinkService.toRoute()` / `navigate()`。到达不导航;未知 scheme、非法百分号编码等不导航,不新增路由。 - 点击 Activity 是可导出的入口,数据视作不可信输入,仅允许经过既有深链白名单的内部路由。仍须由既有 auth/对象权限控制页面访问。 ## 本地通知去重边界 内存内按业务事件键/消息 ID 去重,TTL 五分钟、上限 256 条;点击和到达使用独立集合。应用重启不声称跨进程持久去重。 本子任务没有修改现有 `AppNotificationService` 或消息生产者。要让既有在线业务与 data message 共享去重,由主代理将相关生产者从 `appNotification.notify(notice)` 改为 `jpush.notifyLocal(notice, businessEventKey)`。`notice.key` 是会话通知覆盖键;`businessEventKey` 必须代表一次具体业务事件,不可把 `task-done:` 当永久事件键,否则会误吞后续任务。 SDK notification 在 JS 收到回调前可能已经展示;如果本地生产者先展示,不能仅靠 JS 保证反向顺序不双显。后端必须为同一业务选择唯一投递策略,不同时发 notification 与 data,并在启用远程 notification 后停用同一事件的本地生产者。没有业务事件 ID 或没有主代理迁移时,不声称全链路去重完成。 ## 未就绪资源与验收边界 缺少:匹配 `cn.fmode.app` 的 JPush AppKey/控制台应用、后台凭据安全配置、鉴权设备登记与别名签发/撤销接口、业务事件推送触发、通知点击 Intent 配置、厂商通道申请配置、隐私告知与同意入口。 厂商通道当前明确关闭,无华为/小米/OPPO/vivo SDK;不要把极光基础长连接误称为国产 ROM 杀进程后的可靠离线到达。未进行服务端真实发送、真机注册、前后台/杀进程/ROM 回归、通知点击实测。上述由主代理在资源齐备后回归,不属于本次已通过门禁。 ## 实际验证记录 - ChromeHeadless 定向执行 `jpush.service.spec.ts` 与 `jpush.lifecycle.spec.ts`:24/24 通过。覆盖默认禁用、隐私门禁、缺 AppKey、启动清理旧别名、注册 ID、监听回收、点击白名单/去重、复用本地通知、别名串行回执/失败、AppInitializer 及登出/切号/租户变化解绑。 - `tsc -p tsconfig.app.json --noEmit`、`tsc -p tsconfig.spec.json --noEmit` 通过;后加生命周期代码亦经过上述 Angular 测试编译。 - 默认 `:app:assembleDebug :app:testDebugUnitTest` 通过,后者执行当前共享工程 4 项 JVM 测试,无失败;不是新增 SDK 真机测试。 - 默认 `debugRuntimeClasspath` 的 `dependencyInsight --dependency cn.jiguang.sdk` 显示无匹配依赖;`apkanalyzer dex packages --defined-only` 确认默认 APK 有本地桥接、没有 JPush/JCore SDK 定义。 - 开启 `fmodeJpushEnabled=true` 后 `:app:compileDebugJavaWithJavac` 通过;也使用仅子进程环境中的非秘密合成 AppKey、临时 app build 目录、关闭 build/configuration cache 再次编译通过,确认 `JPushSdk.class` 实际产出,APK 数量为 0。未执行任何 SDK 运行任务。 - scoped `git diff --check` 通过。构建存在原有 flatDir/Gradle 弃用提示与 SDK API 弃用提示,无编译错误。 - 未运行 ADB、CDP、模拟器或真机操作;未安装/发布含合成 AppKey 的 APK。父代理负责最终 web build、cap sync、APK 与设备回归。 隔离编译临时目录的递归清理被工具执行策略拒绝,**尚未自动清除**。待主代理/用户用文件管理器删除:`C:\Users\11729\AppData\Local\Temp\fmode-jpush-compile-6a53fcb1fdf34f0a8d3bc3e36411a77e`。合成值只在此一次性编译产物和子进程环境中,不在仓库代码/发布 APK;不要复制其 merged manifest 到项目。不能把这个清理项写成已完成。 以上单测与编译不等同于 SDK 注册、远程发送、账号推送或离线到达完整打通。