SuperAPI AI 工具集

cometchat-flutter-v6-push

通用与其它

查看项目

更新于 10-21 20:28

技能介绍

用途

本技能用于给 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。

步骤要点:

  1. 获取官方设置文档(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 已重定向到遗留页面,应使用上述按平台的页面。
  2. 按文档完成 Firebase 项目创建、google-services.json / GoogleService-Info.plist 放置、Gradle/Podfile 修改,以及 iOS 的 APNs 密钥上传。若文档有误或缺少步骤,应标记为文档缺口,而不是固化临时绕过方案。
  3. 在 CometChat Dashboard 中配置推送提供方(它是发送方),记录 provider ID,注册时需要用到。没有它,客户端再正确也不会送达。
  4. 安装依赖:flutter pub add firebase_core firebase_messaging。CometChatNotifications 随已安装的 cometchat_sdk 提供,无需额外 CometChat 包。
  5. 使用内置 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 传入。

令牌生命周期(文档通常描述不足的部分):

  1. 在 login 成功后注册——没有用户时注册的令牌不会生效。
  2. 令牌刷新时重新注册。FCM 会轮换令牌;监听 onTokenRefresh 并重新注册,否则数天后推送会静默停止。
  3. 登出时注销,在 CometChatUIKit.logout() 之前——否则该设备的下一个用户会收到上一个用户的通知,这是隐私问题,不只是干扰。
  4. 在合适时机请求权限——iOS(以及 Android 13+)需要运行时提示。应在用户主动操作时请求,而不是首次启动时,否则用户可能永久拒绝。

适用场景

  • 需要为 Flutter 应用添加推送通知。
  • 需要 FCM 推送。
  • 需要在应用关闭或后台时通知用户。

限制与注意事项

常见陷阱:

  • 没有 Dashboard 提供方 → 客户端完美但不会送达。调试时应首先检查这一点。
  • 在登录前注册 → 静默失败。
  • 从未在刷新时重新注册 → 推送工作数天后停止。
  • 登出时未注销 → 上一个用户的消息会落到该设备。
  • 在模拟器上测试 → iOS 模拟器无法接收推送,需使用真机。
  • 期望应用在前台时收到推送——前台消息以数据形式到达,需要自行展示。
  • 假设 Web/桌面端与移动端一致——在承诺前需先验证。

验证方式:在真机上,权限已授予 → 登录后令牌注册成功(无错误)→ 应用进入后台 → 另一用户发消息产生通知 → 点击打开应用 → 登出后该设备停止接收。客户端干净却收不到消息,几乎总是 Dashboard 提供方或平台凭据(APNs 密钥 / google-services.json)的问题,而不是 Dart 代码。实时送达是手动设备检查,无法在此自动化,应如实说明,而不是声称未做过的验证。