docs(rn): React Native push notification guides for @cometchat/push-notifications-react-native (Android + iOS)

[suraj-chauhan-cometchat]

What

Rewrites the React Native push notification guides for the new @cometchat/push-notifications-react-native package, on the two existing pages and URLs:

• notifications/react-native-push-notifications-android
• notifications/react-native-push-notifications-ios

Each page follows its Flutter counterpart section for section: dashboard providers → platform credentials → local configuration → bring in the package → native layer → token registration and runtime events → badge count → testing → troubleshooting. Installing the package replaces the copied notification stack; the native steps shrink to Gradle and a notification icon on Android and a few AppDelegate lines on iOS.

Like the Flutter guides, no legacy copies are kept in the repo: the pages are rewritten in place, and /notifications/react-native-push-notifications-legacy keeps redirecting to the legacy archive.

Every code block comes from files compiled against a strict React Native + UI Kit project; the iOS AppDelegate also compiles in a fresh React Native 0.81.4 app.

⚠️ Merge after the release

1. Publish @cometchat/push-notifications-react-native to npm (cometchat-team/push-notifications-sdk-react-native#1).
2. Merge cometchat-team/uikit-react-native#1439, publish the migrated sample to the public repo, and point the sample-app card on both pages at it.

Changes

• notifications/react-native-push-notifications-android.mdx — rewritten
• notifications/react-native-push-notifications-ios.mdx — rewritten

No navigation or redirect changes.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cometchat	🟢 Ready	View Preview	Sep 17, 2026, 3:50 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[jitvarpatil]

Review: React Native push notification guides (Android + iOS)

Requesting changes / hold. The guides are well written and the API calls match the master-app integration, but they document a package customers can't install yet, and they overwrite the two live RN push pages that document the setup the public sample app uses today.

🔴 Blockers

1. @cometchat/push-notifications-react-native isn't published

npm view @cometchat/push-notifications-react-native returns 404 — the package isn't on npm under any version. The only consumer is the UI Kit master app on feat/push-notifications-js-first (cometchat-team/uikit-react-native#1439, still open, base dev-v5), which pins ^0.1.0 with no lockfile or .npmrc showing where that resolves from. Step 3.1 / 4.1 (npm install …) fails for every reader, and nothing after it works.

2. Both pages overwrite the live guides rather than adding new ones

After fb684825 split the guide back into react-native-push-notifications-android.mdx and -ios.mdx — the URLs that are live now — merging replaces today's working setup (Firebase Messaging + Notifee + CallKeep + react-native-voip-push-notification) with instructions for a package that doesn't exist. Customers already on the current stack lose their docs with no fallback. Please either hold until the package ships, or keep the current guide at a legacy URL (the existing /notifications/react-native-push-notifications-legacy redirect already allows for this).

3. The linked sample app contradicts the guide

Both pages link cometchat-uikit-react-native/tree/v5/examples/SampleAppWithPushNotifications as the reference implementation. On v5 that app depends on @notifee/react-native, react-native-callkeep, react-native-voip-push-notification and @react-native-firebase/messaging — the exact libraries the guide's Warning says to remove so notifications and calls don't arrive twice — and doesn't use the new package at all. Point the Card at the migrated sample once #1439 is merged and mirrored to the public repo.

🟠 Should fix

• Stale PR title and description. They describe a single unified react-native-push-notifications.mdx, deleting the Android/iOS pair, docs.json nav + redirect changes, cross-link repoints in four files, and npx cometchat-pn setup. The current diff has none of that: 2 files, no docs.json change, and the setup CLI was removed in 5345d0bd. Please update both so reviewers and the merge history aren't misled.

• Android-only content copied into the iOS page:

  • the permission comment says "Android allows only one pending request per activity";
  • init() passes notificationSmallIcon: 'ic_notification' // Android status-bar icon (step 2) — step 2 on the iOS page is Apple credentials;
  • registerBackgroundCallTask() is shown in index.js although it's a documented no-op on iOS.

  Fine if the code is intentionally shared across platforms, but say so explicitly.

• Payload type mismatch. The iOS example shows "unreadMessageCount": 5 (number); the Android page says it's a string ("5"). Please confirm against the backend payload for each platform.

• Firebase on iOS. The guide says "No Firebase is needed on iOS" and lists @react-native-firebase/messaging for removal, but the master app's ios/masterapp/AppDelegate.swift still has import Firebase. Worth resolving before that app becomes the reference.

✅ Consistent with the master app (feat/push-notifications-js-first @ 0fc4b83a)

• CometChatPushNotifications.init / onNotificationTap / onCallAccepted / onCallEnded / unregister and CometChatPNHelper.requestNotificationPermission / requestCallPermissions.
• init() options: fcmProviderId, apnsProviderId, notificationSmallIcon, showInForeground: true, ringInForeground: false.
• iOS: import react_native_cometchat_push_notifications, and CometChatPushNotificationsAppDelegate.registerForVoIPPushes() (before React Native starts) / didRegisterAPNsToken / didReceiveRemoteNotification.
• No URL or nav changes, so no redirects are needed.

Not verifiable yet: the package source isn't in any repo I could reach, so these are unchecked beyond the master app's usage — the init() defaults (voip, ringInForeground: true), the ERR_* rejection codes, the 5 × 3 s retry, the 45-second ring timeout, the merged-manifest permission list, and the CometChatFcmService.handleMessage / handleNewToken names. Please re-verify these against the package once it's published.

[suraj-chauhan-cometchat]

Thanks for the review — the should-fix items are in 6ebe8f6, and the legacy guides are in 69292a2. The blockers depend on the release, so this PR stays unmerged until the package is published.

🔴 Blockers (resolved by the release)

1. Package not published: we publish @cometchat/push-notifications-react-native first (cometchat-team/push-notifications-sdk-react-native#1) and merge these docs only once it's on npm.
2. Replacing the live guides: held until the release as well, so the new pages go live with the package. Today's guides also stay available at /notifications/react-native-push-notifications-android-legacy and /notifications/react-native-push-notifications-ios-legacy — unchanged apart from a banner pointing to the new guide, kept out of the navigation, and linked from the new pages.
3. Sample app card: once cometchat-team/uikit-react-native#1439 is merged and published to the public repo, the card will point at the migrated sample as part of the same release.

🟠 Should fix

• PR title and description: updated to the current changes.
• Android-only content on the iOS page: the JavaScript files are intentionally shared. Both pages now say so and name the Android-only lines (registerBackgroundCallTask(), notificationSmallIcon, waiting between permission requests), and the wrong "(step 2)" reference is gone.
• unreadMessageCount type: the iOS example now shows a string, matching CometChat's native iOS APNs guide, which reads it as? String. Either way, the package passes every payload value to JavaScript as a string on both platforms, and both pages say so.
• Firebase in the master app: it's there for the app's other Firebase features (Firebase Analytics runs in it), not push — the package doesn't use Firebase on iOS.

Where the unverified claims live in the package (PR #1)

• init() defaults (voip: true, showInForeground: false, ringInForeground: true): CometChatPushNotifications.ts, PNConfiguration.ts
• ERR_* rejection codes and the 45-second ring timeout (RING_TIMEOUT_MS): CometChatPushConstants.kt
• 5 × 3 s token retry (TOKEN_MAX_RETRIES, TOKEN_RETRY_MS): constants.ts
• Permission list: AndroidManifest.xml
• CometChatFcmService.handleMessage / handleNewToken: CometChatFcmService.kt

[suraj-chauhan-cometchat]

Update on blocker 2: to match the Flutter guides, the legacy page copies are removed again (8c1480c).

The docs keep no legacy push guides in the repo: dfce1bb deleted them all — including the earlier react-native-push-notifications-legacy and flutter-push-notifications pages — in favour of redirects to the legacy archive, and the Flutter guides have been rewritten in place since. So the two React Native pages are updated in place, /notifications/react-native-push-notifications-legacy keeps redirecting to the archive, and this PR stays unmerged until the package is released, so the new pages go live together with it.

[jitvarpatil]

Re-check: release-gated only

Thanks for the updates. The should-fix items from the first review are resolved (6ebe8f66), and the description now matches the branch — two pages rewritten in place, no docs.json changes, with /notifications/react-native-push-notifications-legacy redirecting to the archive, following the Flutter precedent and dfce1bbb1.

Leaving Changes requested in place only for the release gates:

Gate	Status
@cometchat/push-notifications-react-native on npm	404
cometchat-team/push-notifications-sdk-react-native#1 (package)	Open
cometchat-team/uikit-react-native#1439 (migrated sample + sample-app card link)	Open

✅ Previously unverified claims — now verified against the package (feat/js-first-push-voip)

Claim	Source
init() defaults voip: true, showInForeground: false, ringInForeground: true	src/models/PNConfiguration.ts:21-32
Token retry 5 × 3 s	src/constants.ts:62-64
45 s ring timeout	CometChatPushConstants.kt:90
ERR_NO_ACTIVITY, ERR_PERMISSION_IN_FLIGHT, ERR_ACTIVITY_NOT_PERMISSION_AWARE	CometChatPushConstants.kt:132-134
CometChatFcmService.handleMessage / handleNewToken (@JvmStatic)	CometChatFcmService.kt:39-53
Merged-manifest permissions and components	android/src/main/AndroidManifest.xml — all 10 permissions match
registerToken('fcm' | 'apns' | 'voip')	PNTokenPlatform in src/models/events.ts
registerBackgroundCallTask(handler, { rejectDeclinedCalls })	src/registerBackgroundCallTask.ts
unreadMessageCount delivered as a string	onMessageReceived(cb: (data: Record<string, string>) => void)
iOS registerForVoIPPushes / didRegisterAPNsToken / didReceiveRemoteNotification / didUpdateVoIPToken / didReceiveIncomingVoIPPush	ios/CometChatPushNotificationsBridge.swift:647-663 (public static, no @objc — so the "Swift-only" note is correct)
import react_native_cometchat_push_notifications	podspec s.name

Notes

• Legacy content: the archive behind the -legacy redirect is the January 2026 single RN page, not today's Android/iOS guides, so customers on the current Firebase/Notifee/CallKeep stack lose the newer version of those instructions once this merges. Fine if that's the intended trade-off, as with Flutter; otherwise consider adding the two current pages to assets.cometchat.io/legacy-docs before merging.
• Nit: ERR_PN_CONFIGURE (CometChatPushConstants.kt:131) isn't in the rejection-code table — worth adding if init() can surface it to JavaScript.

Once the package is on npm and #1439 is merged, I'll confirm the published version and the sample-app card link, and approve.