cometchat-native-push
Push notifications for React Native CometChat — APNs + FCM setup, dashboard provider configuration, client registration, token lifecycle, foreground display, background wake, tap-to-deep-link, and the Expo Go / APNs-environment traps that silently break production.
cometchat · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add cometchat/cometchat-skills --skill cometchat-native-push技能说明
name: cometchat-native-push description: "Push notifications for React Native CometChat — APNs + FCM setup, dashboard provider configuration, client registration, token lifecycle, foreground display, background wake, tap-to-deep-link, and the Expo Go / APNs-environment traps that silently break production." license: "MIT" compatibility: "Node.js >=18; React Native >=0.70; @cometchat/chat-uikit-react-native ^5; @cometchat/chat-sdk-react-native ^4; @react-native-firebase/messaging ^18" allowed-tools: "executeBash, readFile, fileSearch, listDirectory" metadata: author: "CometChat" version: "1.0.0" tags: "cometchat react-native push notifications apns fcm firebase expo"
Purpose
Teaches Claude how to add push notifications to a CometChat React Native integration — end-to-end, from Apple Developer / Google Cloud setup through CometChat dashboard provider configuration, client token registration, foreground/background handling, and tap-to-deep-link.
Push is non-negotiable for production chat. Without it, a backgrounded app never wakes when a message arrives. The user doesn't see the message, doesn't re-open the app, and stops using chat. This is THE feature that separates "works in demo" from "works in production."
Ground truth: examples/SampleAppWithPushNotifications/ in @cometchat/chat-uikit-react-native@5.3.3, docs/sdk/react-native/push-notification-setup.mdx, and https://www.cometchat.com/docs/notifications/push-integration.
1. The moving pieces
Push spans four systems that must all agree:
┌─────────────┐ ┌─────────────┐ ┌──────────────┐ ┌────────┐
│ Apple / │ │ CometChat │ │ CometChat │ │ RN │
│ Google │ → │ Dashboard │ → │ server │ → │ client │
│ (APNs/FCM) │ │ (providers) │ │ (via SDK) │ │ (app) │
└─────────────┘ └─────────────┘ └──────────────┘ └────────┘
p8 key / JSON Uploaded creds Webhook on message Displays notif
When user A sends a message to user B:
- CometChat server receives the message
- Looks up B's registered push tokens (client did this at login)
- Sends a push via APNs (iOS) or FCM (Android) using the credentials the dashboard holds
- B's device receives it, OS wakes the app (or fires foreground handler)
- Notification displays; tap → app navigates to the conversation
All five steps must work. A broken step is almost always silent — no log, no error, just no notification. Debugging requires checking each layer.
2. Expo Go CANNOT receive push notifications
This is the #1 support ticket from Expo users. Expo Go is a prebuilt shell app without your custom native modules — it has no APNs entitlement, no FCM configuration, no way to receive your app's push.
For push, Expo projects require a development build:
npx expo install expo-dev-client
npx expo prebuild --clean # generates ios/ + android/ with native configuration
eas build --profile development --platform ios # or android
Open the resulting .ipa / .apk and run npx expo start --dev-client. This is the only Expo setup that can receive push.
If a user reports "I set everything up but no notifications arrive" and they're running Expo Go, that's the answer — no code fix will help.
3. APNs setup (iOS)
3a. Create an APNs Auth Key (p8)
Apple's two options for signing push — certificate (.p12) or auth key (.p8). Use .p8. It never expires, one key works for all your apps, and CometChat accepts the simpler key format.
- https://developer.apple.com/account → Certificates, Identifiers & Profiles → Keys → "+"
- Name it (e.g., "CometChat APNs"), check Apple Push Notifications service (APNs), Continue, Register
- Download the
.p8file (one-time — Apple never lets you download it again) - Copy the Key ID (10-char alphanumeric, shown on the key page)
- From the membership page, copy your Team ID (10-char alphanumeric, top-right)
- Collect your app's Bundle ID (from
ios/<Name>.xcodeproj→ Targets → General)
You'll paste all four into the CometChat dashboard in §5.
3b. Enable Push Notifications capability in Xcode
Open ios/<Name>.xcworkspace
Select the project → Signing & Capabilities tab
Click "+ Capability" → "Push Notifications"
Click "+ Capability" → "Background Modes"
In Background Modes, check:
- Remote notifications
- Voice over IP (only if integrating CometChat calls)
This writes aps-environment (development or production) into the entitlements file. Wrong environment is the #1 silent-failure in §10.
3c. Two environments — the TestFlight / App Store trap
APNs has two parallel networks:
- Development (
aps-environment: development) — Xcode dev builds. Uses dev key paths. - Production (
aps-environment: production) — TestFlight, App Store, Ad-Hoc. Uses prod key paths.
The p8 auth key you generated in 3a works for both environments. But CometChat has to know which environment the token came from. If you upload the p8 only as "Development" in the dashboard, TestFlight builds silently fail — a token arrives from production APNs but the dashboard has no matching credentials.
Fix: upload the same p8 twice in the CometChat dashboard — once as Development provider, once as Production provider. Then register with the matching provider ID at runtime (§7).
4. FCM setup (Android)
4a. Create a Firebase project + service account
- https://console.firebase.google.com → Add project → name it, continue through setup
- Project Settings (gear icon) → Service accounts tab
- Generate new private key → downloads a
.jsonfile with your server credentials
This JSON file is what CometChat's dashboard needs.
4b. Add Android app to Firebase + download google-services.json
- Project Overview → Add app → Android
- Enter your app's package name (from
android/app/build.gradle→applicationId) - Download `google-se