用途
本技能用于给 Flutter 应用添加推送通知能力,基于 CometChat 实现。推送被明确定位为外部集成,而不是 UI Kit 组件:它涉及 Firebase 项目、Android 与 iOS 两端的原生配置,以及 CometChat Dashboard 中的推送提供方。技能本身只固化经过验证的 SDK 符号(对照 cometchat_sdk 5.0.6)与加固要点,逐步操作流程需要从官方通知文档获取。
主要能力
- 在 Flutter 应用中集成 FCM(Android)与 FCM/APNs(iOS)推送。
- 通过 CometChatNotifications 注册与注销推送令牌。
- 处理令牌生命周期:登录后注册、令牌刷新时重新注册、登出时注销。
- 覆盖常见陷阱,例如缺少 Dashboard 提供方、登录前注册、未在刷新时重新注册、未在登出时注销、在模拟器上测试、前台消息处理、以及移动端与 Web/桌面端差异。
使用方式
前置条件:先阅读配套技能 cometchat-flutter-v6-core(安装、凭据、init→login→render),本技能假设其已完成;推送注册发生在登录之后,且使用同一个 SDK。事件监听生命周期可参考 cometchat-flutter-v6-events。
步骤要点:
- 获取官方设置文档(source of truth):通过 ../cometchat-flutter-v6-core/references/docs-map.md 找到 /notifications/push-overview、/notifications/flutter-push-notifications-android、/notifications/flutter-push-notifications-ios。注意旧的单数页面 /notifications/flutter-push-notifications 已重定向到遗留页面,应使用上述按平台的页面。
- 按文档完成 Firebase 项目创建、google-services.json / GoogleService-Info.plist 放置、Gradle/Podfile 修改,以及 iOS 的 APNs 密钥上传。若文档有误或缺少步骤,应标记为文档缺口,而不是固化临时绕过方案。
- 在 CometChat Dashboard 中配置推送提供方(它是发送方),记录 provider ID,注册时需要用到。没有它,客户端再正确也不会送达。
- 安装依赖:flutter pub add firebase_core firebase_messaging。CometChatNotifications 随已安装的 cometchat_sdk 提供,无需额外 CometChat 包。
- 使用内置 SDK 符号进行注册与注销(代码见下)。
内置 SDK 符号(对照 5.0.6 验证,不要猜测):
import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
// Register AFTER login, with the token you got from firebase_messaging getToken().
Future registerPush(String fcmToken, String providerId) async {
await CometChatNotifications.registerPushToken(
PushPlatforms.FCM_FLUTTER_ANDROID, // FCM_FLUTTER_IOS on iOS; for a raw APNs token use APNS_FLUTTER_DEVICE / APNS_FLUTTER_VOIP (there is NO plain PushPlatforms.APNS)
providerId: providerId, // from the Dashboard provider you configured
fcmToken: fcmToken,
onSuccess: (res) {},
onError: (e) {},
);
}
// On logout — otherwise the device keeps receiving the previous user's messages.
Future unregisterPush() async {
await CometChatNotifications.unregisterPushToken(onSuccess: (res) {}, onError: (e) {});
}
PushPlatforms 是按平台区分的 Flutter 枚举变体,需选择与运行平台和令牌类型匹配的项(fcmToken、deviceToken 或 voipToken)。不要把 FCM 令牌当作 deviceToken 传入。
令牌生命周期(文档通常描述不足的部分):
- 在 login 成功后注册——没有用户时注册的令牌不会生效。
- 令牌刷新时重新注册。FCM 会轮换令牌;监听 onTokenRefresh 并重新注册,否则数天后推送会静默停止。
- 登出时注销,在 CometChatUIKit.logout() 之前——否则该设备的下一个用户会收到上一个用户的通知,这是隐私问题,不只是干扰。
- 在合适时机请求权限——iOS(以及 Android 13+)需要运行时提示。应在用户主动操作时请求,而不是首次启动时,否则用户可能永久拒绝。
适用场景
- 需要为 Flutter 应用添加推送通知。
- 需要 FCM 推送。
- 需要在应用关闭或后台时通知用户。
限制与注意事项
常见陷阱:
- 没有 Dashboard 提供方 → 客户端完美但不会送达。调试时应首先检查这一点。
- 在登录前注册 → 静默失败。
- 从未在刷新时重新注册 → 推送工作数天后停止。
- 登出时未注销 → 上一个用户的消息会落到该设备。
- 在模拟器上测试 → iOS 模拟器无法接收推送,需使用真机。
- 期望应用在前台时收到推送——前台消息以数据形式到达,需要自行展示。
- 假设 Web/桌面端与移动端一致——在承诺前需先验证。
验证方式:在真机上,权限已授予 → 登录后令牌注册成功(无错误)→ 应用进入后台 → 另一用户发消息产生通知 → 点击打开应用 → 登出后该设备停止接收。客户端干净却收不到消息,几乎总是 Dashboard 提供方或平台凭据(APNs 密钥 / google-services.json)的问题,而不是 Dart 代码。实时送达是手动设备检查,无法在此自动化,应如实说明,而不是声称未做过的验证。