jpush-integration.md 16 KB

极光推送子任务:配置与整合交接

核查日期: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 二进制提交仓库。

主源与官方资料:

默认安全行为

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) 之前,与现有插件注册并列添加:

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 version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove" />
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" tools:node="remove" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" tools:node="remove" />
    <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" tools:node="remove" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" tools:node="remove" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" tools:node="remove" />
    <application>
        <receiver android:name=".JPushReceiver" android:exported="false">
            <intent-filter>
                <action android:name="cn.jpush.android.intent.RECEIVER_MESSAGE" />
                <category android:name="${applicationId}" />
            </intent-filter>
        </receiver>
        <service android:name=".JPushService" android:exported="false" android:process=":pushcore">
            <intent-filter>
                <action android:name="cn.jiguang.user.service.action" />
            </intent-filter>
        </service>
        <activity
            android:name=".JPushClickActivity"
            android:exported="true"
            android:launchMode="singleTop"
            android:theme="@android:style/Theme.Translucent.NoTitleBar" />
        <provider android:name="cn.jpush.android.service.InitProvider" tools:node="remove" />
    </application>
</manifest>

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。使用 <uses-permission android:name="android.permission.…" tools:node="remove" />。保留网络与通知所需权限;不要重新加入精确闹钟权限。检查所有最终 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 中增加:

import { provideJPushLifecycle } from './core/jpush.lifecycle';

在现有 providers 数组中增加一项,不替换已有 initializer:

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 仅携带:

{
  "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:<agentId> 当永久事件键,否则会误吞后续任务。

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 注册、远程发送、账号推送或离线到达完整打通。