cometchat-native-push-8cb026— agent skill

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/[email protected], 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:

1. CometChat server receives the message
2. Looks up B's registered push tokens (client did this at login)
3. Sends a push via APNs (iOS) or FCM (Android) using the credentials the dashboard holds
4. B's device receives it, OS wakes the app (or fires foreground handler)
5. 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.

1. https://developer.apple.com/account → Certificates, Identifiers & Profiles → Keys → "+"
2. Name it (e.g., "CometChat APNs"), check Apple Push Notifications service (APNs), Continue, Register
3. Download the `.p8` file (one-time — Apple never lets you download it again)
4. Copy the Key ID (10-char alphanumeric, shown on the key page)
5. From the membership page, copy your Team ID (10-char alphanumeric, top-right)
6. 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

1. https://console.firebase.google.com → Add project → name it, continue through setup
2. Project Settings (gear icon) → Service accounts tab
3. Generate new private key → downloads a .json file with your server credentials

This JSON file is what CometChat's dashboard needs.

4b. Add Android app to Firebase + download google-services.json

1. Project Overview → Add app → Android
2. Enter your app's package name (from android/app/build.gradle → applicationId)
3. Download google-services.json
4. Place it at android/app/google-services.json
5. Add this line at the end of android/app/build.gradle:

   apply plugin: 'com.google.gms.google-services'

1. In android/build.gradle under buildscript.dependencies:

   classpath 'com.google.gms:google-services:4.4.2'

Expo managed: google-services.json goes in the project root, and you reference it in app.json:

{
  "expo": {
    "android": {
      "googleServicesFile": "./google-services.json"
    },
    "plugins": ["@react-native-firebase/app", "@react-native-firebase/messaging"]
  }
}

4c. iOS Firebase config (if using firebase/messaging on iOS)

react-native-firebase/messaging wraps APNs under the hood on iOS, so the APNs setup in §3 is what actually powers iOS push. BUT Firebase expects a GoogleService-Info.plist even though it doesn't route iOS push through FCM:

1. Add iOS app in Firebase console (Project Overview → Add app → iOS)
2. Download GoogleService-Info.plist
3. Add it to ios/<Name>/ via Xcode (Right-click project → Add Files)
4. In Expo: put it at project root and reference in app.json:

   { "expo": { "ios": { "googleServicesFile": "./GoogleService-Info.plist" } } }

5. CometChat dashboard — upload credentials

https://app.cometchat.com → your app → Notifications → Push Notifications

5a. Add an APNs provider (per environment)

• Add Provider → choose APNs
• Provider name: apns-dev (or similar)
• Environment: Development
• Upload the .p8 file from §3a
• Paste Key ID, Team ID, Bundle ID
• Save → copy the Provider ID string (you'll need it in §7)

Repeat for Production:

• Provider name: apns-prod
• Environment: Production
• Same p8, Key ID, Team ID, Bundle ID
• Save → copy the second Provider ID

If you skip the production provider, TestFlight / App Store builds will silently not receive push.

5b. Add an FCM provider

• Add Provider → choose FCM
• Provider name: fcm-default
• Upload the service account .json file from §4a
• Save → copy the Provider ID

5c. Cache the Provider IDs

You'll have 2-3 provider IDs. Store them in a config constant in your app:

// src/config/push.ts
export const PUSH_PROVIDERS = {
  fcm: "fcm-<hex-from-dashboard>",
  apnsDev: "apns-dev-<hex-from-dashboard>",
  apnsProd: "apns-prod-<hex-from-dashboard>",
};

At runtime (§7), you'll pick the right one based on platform + __DEV__.

6. Install client packages

Bare 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 ..

• @react-native-firebase/app — initializes Firebase (reads GoogleService-Info.plist / google-services.json)
• @react-native-firebase/messaging — FCM on Android AND APNs on iOS (Firebase handles both)
• @notifee/react-native — local notification display (for foreground messages on Android; required because FCM data-only pushes don't auto-display)
• @react-native-community/push-notification-ios — iOS APNs device token retrieval + notification tap handling (getInitialNotification, addEventListener)

Expo managed (dev build)

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

Then build a dev client (§2) and run npx expo start --dev-client.

iOS permissions in `ios/<Name>/Info.plist`: no changes needed for basic push.

Android permissions in `android/app/src/main/AndroidManifest.xml`:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

For Expo managed, put permissions in app.json:

{
  "expo": {
    "android": {
      "permissions": ["POST_NOTIFICATIONS", "WAKE_LOCK"]
    }
  }
}

7. Register the push token with CometChat

The canonical API — confirmed from examples/SampleAppWithPushNotifications/src/utils/PushNotification.tsx:

import { CometChatNotifications } from "@cometchat/chat-sdk-react-native";

CometChatNotifications.PushPlatforms enum values:

Most apps use FCM on both platforms (simpler — Firebase handles the APNs dance). Only use APNS_REACT_NATIVE_DEVICE if you're registering the raw APNs device token without Firebase in between.

7a. Canonical register helper

// src/push/registerPushToken.ts
import { Platform } from "react-native";
import { CometChatNotifications } from "@cometchat/chat-sdk-react-native";
import { PUSH_PROVIDERS } from "../config/push";

export async function registerPushToken(token: string): Promise<void> {
  const platform =
    Platform.OS === "android"
      ? CometChatNotifications.PushPlatforms.FCM_REACT_NATIVE_ANDROID
      : CometChatNotifications.PushPlatforms.FCM_REACT_NATIVE_IOS;

  // Single FCM provider covers both platforms when using firebase/messaging.
  const providerId = PUSH_PROVIDERS.fcm;

  try {
    await CometChatNotifications.registerPushToken(token, platform, providerId);
  } catch (err) {
    console.error("[push] registerPushToken failed", err);
  }
}

7b. Fetch the FCM token and register (after login)

// src/push/bootstrap.ts
import messaging from "@react-native-firebase/messaging";
import { registerPushToken } from "./registerPushToken";

export async function bootstrapPushAfterLogin(): Promise<void> {
  await messaging().registerDeviceForRemoteMessages();
  const token = await messaging().getToken();
  await registerPushToken(token);

  // Re-register when the token rotates (rare but it happens — new install, app restore).
  messaging().onTokenRefresh(async (newToken) => {
    await registerPushToken(newToken);
  });
}

Call bootstrapPushAfterLogin() in the same effect that runs CometChatUIKit.login(). Order matters — the SDK needs a logged-in user to associate the token with.

7c. Unregister on logout

import { CometChatNotifications } from "@cometchat/chat-sdk-react-native";

export async function unregisterPushTokenOnLogout(): Promise<void> {
  try {
    await CometChatNotifications.unregisterPushToken();
  } catch (err) {
    console.error("[push] unregisterPushToken failed", err);
  }
}

Call this BEFORE CometChatUIKit.logout() — after logout the SDK can't resolve the user to unregister the token against.

If the user switches accounts without logging out (bad pattern, but it happens), re-register with the new user after login. CometChat auto-scopes push to the current user.

8. Permissions — ask early, handle deny gracefully

iOS

iOS prompts the user on the first call to messaging().requestPermission(). Do it early in the onboarding flow (post-login is fine), not in the first render — a permission prompt on app open looks hostile.

import messaging from "@react-native-firebase/messaging";

async function requestIosPush(): Promise<boolean> {
  const status = await messaging().requestPermission();
  return (
    status === messaging.AuthorizationStatus.AUTHORIZED ||
    status === messaging.AuthorizationStatus.PROVISIONAL
  );
}

Android

Android 13+ requires the POST_NOTIFICATIONS runtime permission (prior versions grant it automatically from the manifest).

import { PermissionsAndroid, Platform } from "react-native";

async function requestAndroidPush(): Promise<boolean> {
  if (Platform.OS !== "android" || Platform.Version < 33) return true;
  const status = await PermissionsAndroid.request(
    PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS,
  );
  return status === PermissionsAndroid.RESULTS.GRANTED;
}

Handle deny

If the user denies, don't retry — it just shows the system "open Settings" prompt. Surface a small UI nudge in chat settings: "Enable push notifications — so you know when you get a message." Link to Linking.openSettings().

9. Display, background, tap

9a. Foreground messages (Android)

FCM on Android delivers data-only pushes while the app is foregrounded — the OS does NOT display them automatically. You have to render a local notification with @notifee/react-native:

import messaging from "@react-native-firebase/messaging";
import notifee, { AndroidImportance } from "@notifee/react-native";

messaging().onMessage(async (remoteMessage) => {
  const { title, body } = remoteMessage.data ?? {};
  const channelId = await notifee.createChannel({
    id: "chat-messages",
    name: "Chat Messages",
    importance: AndroidImportance.HIGH,
  });
  await notifee.displayNotification({
    title: title ?? "New Message",
    body: body ?? "You received a new message.",
    android: { channelId, pressAction: { id: "default" } },
    data: remoteMessage.data, // preserved for tap handling
  });
});

iOS foregrounding behavior is configured by messaging().setForegroundNotificationPresentationOptions(...) — set it once at app startup. Default is "don't display" (iOS assumes the app handles it), so you must opt-in to badges/banners/sounds.

9b. Background / killed messages

OS-delivered, no code needed. The notification displays as an OS notification. Tap handling: see §9c.

9c. Tap to deep-link

Three scenarios to handle:

iOS — app killed, tap opens the app:

import PushNotificationIOS from "@react-native-community/push-notification-ios";

async function checkInitialNotificationIOS(): Promise<void> {
  const notification = await PushNotificationIOS.getInitialNotification();
  if (!notification) return;
  const data = notification.getData();
  navigateFromPayload(data);
}

iOS — app in background, tap foregrounds:

PushNotificationIOS.addEventListener("notification", (notification) => {
  const data = notification.getData();
  if (data.userInteraction === 1) {
    navigateFromPayload(data);
  }
  notification.finish(PushNotificationIOS.FetchResult.NoData);
});

Android (via messaging):

import messaging from "@react-native-firebase/messaging";

// App killed → tap → opens app
messaging().getInitialNotification().then((remoteMessage) => {
  if (remoteMessage?.data) navigateFromPayload(remoteMessage.data);
});

// App backgrounded → tap → foregrounds
messaging().onNotificationOpenedApp((remoteMessage) => {
  if (remoteMessage?.data) navigateFromPayload(remoteMessage.data);
});

// Foreground local notification (displayed via notifee in §9a) → tap
import notifee, { EventType } from "@notifee/react-native";
notifee.onForegroundEvent(({ type, detail }) => {
  if (type === EventType.PRESS) {
    navigateFromPayload(detail.notification?.data ?? {});
  }
});

9d. Payload → navigation

CometChat's push payload schema (confirmed from examples/SampleAppWithPushNotifications/src/utils/helper.ts):

{
  type: "chat",
  receiverType: "user" | "group",
  sender: "<uid>",
  receiver: "<uid-or-guid>",
  conversationId: "<compound-id>",
  unreadMessageCount: "<number-as-string>",
  title: "Alice",
  body: "Hey, you around?",
  senderAvatar: "<url>",
  tag: "<messageId>",
  message: "<JSON-stringified-full-message>",   // parse for parentId, id, etc.
}

Parse it into navigation params:

import { CometChat } from "@cometchat/chat-sdk-react-native";
import { navigate } from "./NavigationService";   // createNavigationContainerRef wrapper

async function navigateFromPayload(data: Record<string, unknown>): Promise<void> {
  if (data.type !== "chat") return;

  let parentMessageId: string | undefined;
  if (typeof data.message === "string") {
    try {
      parentMessageId = JSON.parse(data.message).parentId;
    } catch {}
  }

  if (data.receiverType === "group" && typeof data.receiver === "string") {
    const group = await CometChat.getGroup(data.receiver);
    navigate("Messages", { group, ...(parentMessageId ? { parentMessageId } : {}) });
  } else if (data.receiverType === "user" && typeof data.sender === "string") {
    const user = await CometChat.getUser(data.sender);
    navigate("Messages", { user, ...(parentMessageId ? { parentMessageId } : {}) });
  }
}

Use React Navigation's createNavigationContainerRef so you can navigate from outside React (the tap handler fires before the component tree mounts on app launch):

// src/navigation/NavigationService.ts
import { createNavigationContainerRef } from "@react-navigation/native";

export const navigationRef = createNavigationContainerRef();

export function navigate(name: string, params?: unknown): void {
  if (navigationRef.isReady()) navigationRef.navigate(name as never, params as never);
  else setTimeout(() => navigate(name, params), 100);   // wait for mount
}

In the root layout:

<NavigationContainer ref={navigationRef}>…</NavigationContainer>

For Expo Router, use the router from expo-router inside the tap handler — no navigation ref needed, but check router.canGoBack() before pushing on cold start.

10. Badge count

CometChat sends unreadMessageCount in the payload. Set it on iOS via PushNotificationIOS.setApplicationIconBadgeNumber(count) inside the notification handler. On Android, Notifee's setBadgeCount() works on most launchers but is inconsistent (Samsung, Xiaomi have their own rules).

Reset badge to 0 when the user opens a conversation:

import { AppState, Platform } from "react-native";
import PushNotificationIOS from "@react-native-community/push-notification-ios";
import notifee from "@notifee/react-native";

function clearBadge(): void {
  if (Platform.OS === "ios") PushNotificationIOS.setApplicationIconBadgeNumber(0);
  else notifee.setBadgeCount(0);
}

11. Testing the push pipeline

End-to-end verification — run each step in order and stop at the first failure. Silent failures are the norm, so testing each layer separately is faster than chasing a black box.

1. APNs alone (iOS): In Firebase Console → Cloud Messaging → Send test message to your FCM token. If this arrives, Firebase + APNs are fine.
2. FCM alone (Android): Same as above — Firebase test message. If it arrives, FCM + google-services.json are fine.
3. CometChat provider → device: Send a message to the logged-in user from another user. If this fails but step 1/2 worked, the issue is in the CometChat dashboard provider config (wrong p8 environment, wrong bundle ID, expired service account).
4. Tap deep-links correctly: Put the app in background, send a message, tap the notification. App should land on the right conversation.
5. TestFlight / App Store: Build an archive, upload to TestFlight, install on a real device (NOT the simulator — iOS simulator cannot receive real APNs). Repeat step 3. This is where the "production APNs provider not uploaded" trap appears.

12. Troubleshooting — common silent failures

13. Hard rules

• Register AFTER login. The SDK needs a logged-in user to scope the token. Register before login and the token lands against "anonymous."
• Unregister BEFORE logout. The SDK needs to know the user to dissociate the token.
• Call `onTokenRefresh`. FCM rotates tokens. Missing the rotation means push stops working after a few weeks for some users.
• Upload both APNs environments. Dev + Production. Missing Production = silent TestFlight/App Store breakage.
• Expo Go is a dead-end. Build a dev client for push. No exceptions.
• Don't auto-display on Android foreground. Show a local notification via Notifee so the user sees the message.
• Don't ship without testing on a real device. iOS simulator doesn't receive real APNs.

14. Skill routing