原文环境为 2024 年 jpush_flutter 3.0.0,不代表当前 SDK 配置。
这份记录来自 2024 年 jpush_flutter 3.0.0 的集成,覆盖 iOS、OPPO、vivo、荣耀、小米和华为。Flutter 层负责初始化与业务回调,厂商通道还涉及 Android 依赖、应用标识、签名和推送平台配置。
先注册回调,再初始化
原集成顺序中,事件监听放在 setup 前,避免初始化期间的事件没有接收者。下方保留历史插件的接口形式,业务处理由项目自己的函数完成。
final jPush = JPush();
jPush.addEventHandler(
onReceiveNotification: (Map<String, dynamic> message) async {
handleNotificationReceived(message);
},
onOpenNotification: (Map<String, dynamic> message) async {
handleNotificationOpened(message);
},
onReceiveMessage: (Map<String, dynamic> message) async {
handleCustomMessage(message);
},
onConnected: (Map<String, dynamic> message) async {
handlePushConnected(message);
},
);
jPush.setup(
appKey: jpushAppKey,
channel: distributionChannel,
production: usesProductionApns,
debug: false,
);
production 与 iOS 使用的 APNs 环境一致,不直接用“是否调试构建”替代环境配置。SDK 初始化与通知授权放在产品约定的用户授权流程中处理。
Registration ID 与业务别名
final registrationId = await jPush.getRegistrationID();
Registration ID 标识推送注册结果,业务别名用于把登录用户关联到设备。原文通过固定等待五秒设置别名,这只是当时绕开网络时序的尝试;可靠流程应读取 SDK 回调或结果,再按错误码处理重试,不能把固定延迟当作成功依据。
账户退出时,按 SDK 的删除别名 API 清理关联。stopPush 和 resumePush 控制推送状态,不能替代服务端的账号绑定管理。旧文的 setAlias("") 不作为通用删除方式保留。
Android 的三层配置
先使 Flutter 插件与主 SDK 版本配套,再添加实际使用的厂商通道,最后配置各厂商应用。原文将 JPush 5.2.4 与 5.3.1 厂商依赖混写,不能作为一份可直接复制的版本清单。
应用模块的 manifestPlaceholders 表达的是平台注册信息:
android {
defaultConfig {
manifestPlaceholders += [
JPUSH_PKGNAME: applicationId,
JPUSH_APPKEY: project.property('jpushAppKey'),
JPUSH_CHANNEL: 'developer-default'
]
}
}
厂商的 App ID、客户端 Key 和通道依赖按选定 SDK 版本补充。服务端 Master Secret 等凭据不能放入应用包。App ID、包名、签名与平台登记不一致,单改 Flutter 初始化代码无法解决。
本地 AAR 与华为通道
旧集成中的 OPPO、荣耀部分资源采用本地 AAR,放在 android/app/libs 后由应用模块声明依赖。具体语法见本地 AAR 接入记录。

华为部分涉及仓库、AG Connect 插件、agconnect-services.json 和签名证书指纹。原工程通过以下仓库获取相关依赖:
maven { url 'https://developer.huawei.com/repo/' }
该声明应放进工程实际使用的仓库管理位置。新旧 Gradle 工程可能在 settings 或项目文件中集中配置,不能直接覆盖整份 build.gradle。调试包和正式包签名可能不同,配置时需要与正在安装的包一致。
点击通知后的路由
接收通知、点击通知和自定义消息分别处理。点击时先读取业务字段,再确认应用初始化与登录状态;冷启动阶段可以暂存目标,等导航器就绪后进入页面。
原文中的 intent、消息分类和厂商 category 属于特定平台载荷配置。分类应与真实消息用途一致,不能把所有消息填成系统类或即时通信类来规避额度。Flutter 3.27 的相关冷启动问题另见深链接冲突记录。


