@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-native-calls/references/voip-push-end-to-end.md

@@ -1,319 +0,0 @@
-# VoIP push end-to-end on React Native
-
-The hardest piece of RN calls. This reference is the canonical implementation — the SKILL.md sketches it; here is the code.
-
-Stack:
-
-- **`react-native-callkeep`** — bridges CallKit (iOS) + ConnectionService (Android). One Dart-side API: "ring this device with this caller name."
-- **`react-native-voip-push-notification`** — iOS PushKit token registration and payload delivery
-- **`@react-native-firebase/messaging`** — Android FCM data messages
-- **Server-side** — your push server splits sends: PushKit (VoIP cert) for iOS, FCM with `priority: "high"` and `data` payload for Android
-
----
-
-## iOS — PushKit + CallKit
-
-### Install + native config
-
-```bash
-npm install react-native-callkeep react-native-voip-push-notification
-cd ios && pod install && cd ..
-```
-
-In Xcode (manual steps the skill documents but cannot automate):
-
-1. Capabilities → Background Modes → enable: **Audio, AirPlay, and Picture in Picture** + **Voice over IP** + **Remote notifications**
-2. Capabilities → Push Notifications → ensure enabled
-3. Apple Developer portal → Certificates → create a **VoIP Services** certificate for your bundle ID (separate from the standard APNs cert)
-4. Upload the `.p12` to your push server
-
-### Info.plist
-
-```xml
-<key>UIBackgroundModes</key>
-<array>
-  <string>audio</string>
-  <string>voip</string>
-  <string>remote-notification</string>
-</array>
-<key>NSMicrophoneUsageDescription</key>
-<string>So you can talk during voice and video calls.</string>
-<key>NSCameraUsageDescription</key>
-<string>So you can be seen during video calls.</string>
-```
-
-### Register PushKit + CallKit at app launch
-
-```tsx
-// App.tsx
-import { useEffect } from "react";
-import VoipPushNotification from "react-native-voip-push-notification";
-import RNCallKeep from "react-native-callkeep";
-import { Platform } from "react-native";
-
-const callKeepOptions = {
-  ios: {
-    appName: "YourApp",
-    supportsVideo: true,
-    maximumCallGroups: 1,
-    maximumCallsPerCallGroup: 1,
-  },
-  android: {
-    alertTitle: "Permissions required",
-    alertDescription: "This app needs to access your phone calling system to ring you on incoming calls",
-    cancelButton: "Cancel",
-    okButton: "OK",
-    foregroundService: {
-      channelId: "com.yourapp.calls",
-      channelName: "Calls",
-      notificationTitle: "Call in progress",
-      notificationIcon: "ic_launcher",
-    },
-  },
-};
-
-export function App() {
-  useEffect(() => {
-    RNCallKeep.setup(callKeepOptions).then(() => {
-      RNCallKeep.setAvailable(true);
-    });
-
-    if (Platform.OS === "ios") {
-      // Register PushKit listener — iOS will call onRegister with the VoIP token
-      VoipPushNotification.addEventListener("register", (token) => {
-        // Send this token to your server, keyed by the logged-in CometChat UID
-        sendVoipTokenToServer(token);
-      });
-
-      // Incoming VoIP push payload arrives — IMMEDIATELY report to CallKit
-      VoipPushNotification.addEventListener("notification", (notification) => {
-        const { sessionId, callerName, callerUid } = notification.data;
-        // CRITICAL: this MUST happen within ~5s of payload delivery or iOS terminates the app
-        RNCallKeep.displayIncomingCall(
-          sessionId,                  // unique call UUID
-          callerUid,                  // handle
-          callerName,                 // localized caller name
-          "generic",                  // handle type
-          true,                       // hasVideo
-        );
-      });
-
-      VoipPushNotification.registerVoipToken();
-    }
-
-    if (Platform.OS === "android") {
-      setupAndroidVoipPush();
-    }
-
-    return () => {
-      VoipPushNotification.removeEventListener("register");
-      VoipPushNotification.removeEventListener("notification");
-    };
-  }, []);
-
-  // CallKit answer/end events — wire them to CometChat Calls SDK
-  useEffect(() => {
-    RNCallKeep.addEventListener("answerCall", async ({ callUUID }) => {
-      // sessionId === callUUID we passed to displayIncomingCall.
-      // Accept lives on the CHAT SDK (CometChat.acceptCall), NOT CometChatCalls —
-      // the Calls SDK has no acceptCall; calling it crashes at answer time.
-      await CometChat.acceptCall(callUUID);
-      navigate("OngoingCall", { sessionId: callUUID });
-    });
-
-    RNCallKeep.addEventListener("endCall", async ({ callUUID }) => {
-      await CometChatCalls.leaveSession();
-    });
-
-    return () => {
-      RNCallKeep.removeEventListener("answerCall");
-      RNCallKeep.removeEventListener("endCall");
-    };
-  }, []);
-
-  return /* ...your nav... */;
-}
-```
-
-**5-second rule:** Apple terminates apps that delay `RNCallKeep.displayIncomingCall` more than ~5 seconds after PushKit delivery. Do not `await` async work before the call — display first, then do the rest from inside the answer handler.
-
----
-
-## Android — FCM data messages + ConnectionService
-
-### Install + native config
-
-```bash
-npm install @react-native-firebase/app @react-native-firebase/messaging
-cd ios && pod install && cd ..    # iOS link for firebase even if you don't use iOS messaging
-```
-
-Place `google-services.json` (downloaded from Firebase console) at `android/app/google-services.json`.
-
-In `android/build.gradle`:
-
-```gradle
-buildscript {
-  dependencies {
-    classpath 'com.google.gms:google-services:4.4.0'
-  }
-}
-```
-
-In `android/app/build.gradle`:
-
-```gradle
-apply plugin: 'com.google.gms.google-services'
-```
-
-### AndroidManifest.xml
-
-```xml
-<uses-permission android:name="android.permission.INTERNET" />
-<uses-permission android:name="android.permission.RECORD_AUDIO" />
-<uses-permission android:name="android.permission.CAMERA" />
-<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
-<uses-permission android:name="android.permission.WAKE_LOCK" />
-<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
-<uses-permission android:name="android.permission.MANAGE_OWN_CALLS" />
-<uses-permission android:name="android.permission.BIND_TELECOM_CONNECTION_SERVICE" tools:ignore="ProtectedPermissions" />
-
-<!-- Android 14+ -->
-<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
-<uses-permission android:name="android.permission.FOREGROUND_SERVICE_PHONE_CALL" />
-<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
-<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
-
-<application>
-  <service
-    android:name="io.wazo.callkeep.RNCallKeepBackgroundMessagingService"
-    android:foregroundServiceType="phoneCall|microphone|camera"
-    android:exported="false" />
-</application>
-```
-
-The `tools` namespace must be declared on `<manifest>`: `xmlns:tools="http://schemas.android.com/tools"`.
-
-### Register FCM + handle data messages
-
-```ts
-import messaging from "@react-native-firebase/messaging";
-import RNCallKeep from "react-native-callkeep";
-
-async function setupAndroidVoipPush() {
-  await messaging().requestPermission();
-  const token = await messaging().getToken();
-  await sendFcmTokenToServer(token);
-
-  // Foreground messages — when app is open
-  messaging().onMessage(async (remoteMessage) => {
-    if (remoteMessage.data?.type === "incoming_call") {
-      handleIncomingCallPayload(remoteMessage.data);
-    }
-  });
-
-  // Background / killed app — registered in index.js (see below)
-}
-
-function handleIncomingCallPayload(data: Record<string, string>) {
-  RNCallKeep.displayIncomingCall(
-    data.sessionId,
-    data.callerUid,
-    data.callerName,
-    "generic",
-    true,
-  );
-}
-```
-
-### Background handler — must be in index.js, NOT a component
-
-```ts
-// index.js (top of file, before AppRegistry.registerComponent)
-import messaging from "@react-native-firebase/messaging";
-import RNCallKeep from "react-native-callkeep";
-
-messaging().setBackgroundMessageHandler(async (remoteMessage) => {
-  if (remoteMessage.data?.type === "incoming_call") {
-    RNCallKeep.displayIncomingCall(
-      remoteMessage.data.sessionId,
-      remoteMessage.data.callerUid,
-      remoteMessage.data.callerName,
-      "generic",
-      true,
-    );
-  }
-});
-```
-
-Background handler must register in `index.js` so it's invoked when the JS engine boots in background-headless mode.
-
----
-
-## Server-side push payload shape
-
-Your push server gets the call event from CometChat (via webhook) and dispatches:
-
-### iOS payload (PushKit — sent via APNs with `apns-push-type: voip`)
-
-```json
-{
-  "aps": {
-    "content-available": 1
-  },
-  "data": {
-    "sessionId": "session-abc-123",
-    "callerName": "Alice",
-    "callerUid": "cometchat-uid-1",
-    "callType": "video"
-  }
-}
-```
-
-Send to the **VoIP-specific** APNs endpoint with the VoIP cert. Standard APNs cert won't work.
-
-### Android payload (FCM data message)
-
-```json
-{
-  "to": "<receiver-fcm-token>",
-  "priority": "high",
-  "data": {
-    "type": "incoming_call",
-    "sessionId": "session-abc-123",
-    "callerName": "Alice",
-    "callerUid": "cometchat-uid-1",
-    "callType": "video"
-  }
-}
-```
-
-**`data` not `notification`.** ConnectionService cannot intercept `notification` payloads — they go to the system tray. Only `data` payloads invoke the background handler.
-
-`priority: "high"` is required. Without it, FCM may delay delivery by minutes — too slow to ring.
-
----
-
-## Common failure modes
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| iOS: incoming call doesn't ring on lock screen | VoIP cert not uploaded to push server, or not matched to bundle ID | Verify cert in Apple Dev portal; rotate if expired |
-| iOS: app crashes ~5s after PushKit delivery | Async work before `displayIncomingCall` | Display first, then do the rest in the answer handler |
-| iOS: PushKit token never registers | Background Modes capability missing | Re-check Xcode capabilities; uninstall + reinstall app to retrigger registration |
-| Android: incoming call shows as a regular notification (not heads-up) | Sent as `notification` instead of `data` | Server must use FCM `data` payload exclusively |
-| Android: incoming call delayed by minutes | `priority` missing or `"normal"` | Server must set `priority: "high"` |
-| Android 14+: app crashes on call start | Wrong `foregroundServiceType` | Must include `phoneCall` (silent crash with `microphone\|camera` only) |
-| Android: ConnectionService not invoked | `MANAGE_OWN_CALLS` permission denied at runtime | Show rationale dialog and re-request |
-| Both: lock-screen UI stuck after call ends | Missing `RNCallKeep.endCall` in hangup path | Add `RNCallKeep.endCall(callUUID)` to the cleanup |
-
----
-
-## Testing VoIP push (without a server)
-
-The hardest part of dev is iterating without a real push server. Two workarounds:
-
-1. **Trigger CallKit directly without push** — call `RNCallKeep.displayIncomingCall(...)` from a debug button in your app. Bypasses the server entirely. Useful for testing the in-app flow.
-2. **Use Firebase Console "Send test message"** — send a one-off FCM `data` payload to a specific token. Does NOT support PushKit — iOS still needs a real VoIP push server.
-
-For real end-to-end tests, you need a push server. The skill scaffolds a tiny Express example (`server/push.example.ts`) that the user runs locally; it's documented but not tested in CI because real APNs/FCM requires real certs.