用途
本技能用于指导 Claude 为 CometChat 的 React Native 集成添加推送通知，覆盖从 Apple Developer / Google Cloud 配置，到 CometChat 后台推送提供商设置、客户端令牌注册、前台与后台处理，以及点击通知深链跳转的端到端流程。
推送通知对生产环境聊天是必需的。没有推送，应用在后台时不会因新消息被唤醒，用户看不到消息、不会重新打开应用，最终停止使用聊天功能。
涉及的系统
推送跨越四个必须协同工作的系统：Apple / Google（APNs / FCM）→ CometChat 后台（提供商配置）→ CometChat 服务端（通过 SDK）→ React Native 客户端（应用）。
当用户 A 向用户 B 发送消息时：CometChat 服务端接收消息，查找 B 已注册的推送令牌（客户端在登录时完成注册），使用后台持有的凭据通过 APNs（iOS）或 FCM（Android）发送推送，B 的设备接收后由操作系统唤醒应用（或触发前台处理器），通知展示，点击后应用导航到对应会话。五个步骤都必须正常工作，任一环节出错通常都是静默失败。
Expo Go 无法接收推送通知
Expo Go 是预构建的壳应用，不包含自定义原生模块，没有 APNs 权限、没有 FCM 配置，无法接收应用的推送。Expo 项目接收推送需要开发构建（development build）：
npx expo install expo-dev-client
npx expo prebuild --clean
eas build --profile development --platform ios
打开生成的 .ipa / .apk 并运行 npx expo start --dev-client。这是唯一能接收推送的 Expo 配置方式。
APNs 配置（iOS）
创建 APNs Auth Key（p8）：在 Apple Developer 账户的 Certificates, Identifiers & Profiles → Keys 中新建密钥，勾选 Apple Push Notifications service (APNs)，下载 .p8 文件（仅可下载一次），记录 Key ID、Team ID 和应用的 Bundle ID。
在 Xcode 中启用能力：打开 ios/<Name>.xcworkspace，在 Signing & Capabilities 中添加 Push Notifications 和 Background Modes，并在 Background Modes 中勾选 Remote notifications（如集成 CometChat 通话则勾选 Voice over IP）。
APNs 有开发（development）和生产（production）两套并行网络。p8 密钥对两者都有效，但 CometChat 需要知道令牌来自哪个环境。如果只在后台以 Development 上传 p8，TestFlight 构建会静默失败。解决办法是在 CometChat 后台将同一个 p8 上传两次，分别作为 Development 和 Production 提供商，并在运行时使用匹配的提供商 ID 注册。
FCM 配置（Android）
在 Firebase 控制台创建项目，在 Project Settings → Service accounts 中生成新的私钥，下载包含服务端凭据的 .json 文件，供 CometChat 后台使用。
共存检查：如果应用已使用 Firebase（存在 firebase / @react-native-firebase/* 依赖、google-services.json 或 GoogleService-Info.plist），应复用同一 Firebase 项目和配置文件，不要添加第二个 google-services.json 或重复的插件条目。如果存在竞争性推送提供商（如 OneSignal），需先与用户确认是否两者都注册通知。
在 Firebase 中添加 Android 应用，输入包名（来自 android/app/build.gradle 的 applicationId），下载 google-services.json 放到 android/app/ 目录，并在 android/app/build.gradle 末尾添加 apply plugin: 'com.google.gms.google-services'，在 android/build.gradle 的 buildscript.dependencies 中添加 classpath 'com.google.gms:google-services:4.4.2'。Expo 托管项目将 google-services.json 放在项目根目录，并在 app.json 中通过 android.googleServicesFile 引用。
iOS 若使用 firebase/messaging，仍需在 Firebase 控制台添加 iOS 应用并下载 GoogleService-Info.plist，添加到 ios/<Name>/ 目录；Expo 项目放在根目录并通过 ios.googleServicesFile 引用。
CometChat 后台配置
在 app.cometchat.com 进入应用 → Notifications → Push Notifications。分别添加 APNs 提供商（Development 和 Production 各一个，上传 p8 并填写 Key ID、Team ID、Bundle ID）和 FCM 提供商（上传服务账号 .json 文件）。保存后复制各提供商 ID，存入应用配置常量，运行时根据平台和 DEV 选择正确的 ID。
安装客户端包
裸 React Native：
npm install @react-native-firebase/app @react-native-firebase/messaging \
@notifee/react-native @react-native-community/push-notification-ios
cd ios && pod install && cd ..
Expo 托管（开发构建）：
npx expo install @react-native-firebase/app @react-native-firebase/messaging \
@notifee/react-native @react-native-community/push-notification-ios expo-dev-client
npx expo prebuild --clean
Android 需要在 AndroidManifest.xml 中添加 POST_NOTIFICATIONS 和 WAKE_LOCK 权限；Expo 托管项目在 app.json 的 android.permissions 中配置。
注册推送令牌
使用 CometChatNotifications.registerPushToken(token, platform, providerId)。平台枚举值包括 FCM_REACT_NATIVE_ANDROID、FCM_REACT_NATIVE_IOS、APNS_REACT_NATIVE_DEVICE、APNS_REACT_NATIVE_VOIP。多数应用在两个平台都使用 FCM。
登录后获取 FCM 令牌并注册，同时监听令牌轮换（onTokenRefresh）重新注册。调用时机应与 CometChatUIKit.login() 在同一 effect 中，顺序很重要——SDK 需要已登录用户才能关联令牌。登出前调用 CometChatNotifications.unregisterPushToken()，登出后 SDK 无法解析用户。
权限
iOS 在首次调用 messaging().requestPermission() 时弹出提示，建议在登录后的引导流程中请求。Android 13+ 需要 POST_NOTIFICATIONS 运行时权限。用户拒绝后不要反复重试，可在聊天设置中提供提示并链接到 Linking.openSettings()。
展示、后台与点击
Android 前台消息：FCM 在应用前台时投递 data-only 推送，系统不会自动展示，需用 @notifee/react-native 渲染本地通知。iOS 前台行为通过 messaging().setForegroundNotificationPresentationOptions(...) 配置，默认不展示，需主动开启徽章、横幅和声音。
后台/被杀状态的消息由操作系统投递，无需代码。点击跳转需处理三种场景：iOS 应用被杀时通过 PushNotificationIOS.getInitialNotification() 获取；iOS 后台时通过 PushNotificationIOS.addEventListener("notification", ...) 处理；Android 通过 messaging().getInitialNotification() 和 messaging().onNotificationOpenedApp() 处理。