FCE-2111: Document background calls API (#192)

## Description

Docs for background calls on iOS

---------

Co-authored-by: Tomasz Mazur <[email protected]>

Author: MiloszFilimowski

docs/how-to/react-native/background-streaming.mdx

@@ -5,9 +5,12 @@ sidebar_position: 6
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# Streaming from background
+# Background calls
 
-On Android, it is possible to continue streaming when app is in background. Unfortunately this functionality is not available on iOS (due to Apple limitations)
+Both Android and iOS support calls running in the background, but they use different approaches:
+
+- **Android**: Uses foreground services to keep the app active in the background
+- **iOS**: Uses CallKit integration to maintain VoIP calls in the background
 
 Below is configuration required to make it work:
 
@@ -28,6 +31,9 @@ You need to modify `app.json` file and add our plugin:
         {
           "android": {
             "enableForegroundService": true
+          },
+          "ios": {
+            "enableVoIPBackgroundMode": true
           }
         }
       ],
@@ -40,7 +46,9 @@ You need to modify `app.json` file and add our plugin:
   </TabItem>
   <TabItem value="rn" label="Bare workflow">
 
-You need to modify `AndroidManifest.xml` file and add below service:
+**Android Configuration**
+
+You need to add the following service to `AndroidManifest.xml`:
 
 ```xml title='AndroidManifest.xml'
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
@@ -50,14 +58,25 @@ You need to modify `AndroidManifest.xml` file and add below service:
     <service android:name="io.fishjam.reactnative.FishjamForegroundService" android:foregroundServiceType="camera|microphone|mediaProjection"/>
   </application>
 </manifest>
+```
+
+**iOS Configuration**
+
+You need to add VoIP background mode in `Info.plist`:
+
+```xml title='Info.plist'
+<key>UIBackgroundModes</key>
+<array>
+  <string>voip</string>
+</array>
 ```
 
   </TabItem>
 </Tabs>
 
 ## Usage
 
-<Tabs groupId="app-type">
+<Tabs groupId="platform">
 
   <TabItem value="android" label="Android">
 
@@ -93,6 +112,92 @@ useForegroundService({
 
   </TabItem>
   <TabItem value="ios" label="iOS">
-This feature is unavailable on iOS.
+
+On iOS, background calls are achieved through CallKit integration. You can use the CallKit hooks to manage VoIP calls that continue running in the background.
+
+### Manual CallKit Management
+
+Use the [`useCallKit`](../../api/mobile/variables/useCallKit) hook for fine-grained control over CallKit sessions:
+
+```tsx
+import { useCallKit } from "@fishjam-cloud/react-native-client";
+
+const { startCallKitSession, endCallKitSession } = useCallKit();
+
+// Start CallKit session when joining a room
+const handleJoinRoom = async () => {
+  await startCallKitSession({
+    displayName: "John Doe",
+    isVideo: true,
+  });
+  // ... join room logic
+};
+
+// End CallKit session when leaving
+const handleLeaveRoom = async () => {
+  await endCallKitSession();
+  // ... leave room logic
+};
+```
+
+### Automatic CallKit Management
+
+Use the [`useCallKitService`](../../api/mobile/variables/useCallKitService) hook for automatic session lifecycle management:
+
+```tsx
+import React from "react";
+import { useCallKitService } from "@fishjam-cloud/react-native-client";
+import { View } from "react-native";
+
+function CallScreen({ username }: { username: string }) {
+  // CallKit session automatically starts when component mounts
+  // and ends when component unmounts
+  useCallKitService({
+    displayName: username,
+    isVideo: true,
+  });
+
+  return <View>...</View>;
+}
+```
+
+### Listening to CallKit Events
+
+Use the [`useCallKitEvent`](../../api/mobile/variables/useCallKitEvent) hook to respond to user interactions with the native CallKit interface:
+
+```tsx
+import {
+  useCallKitEvent,
+  useCamera,
+  useMicrophone,
+  useConnection,
+} from "@fishjam-cloud/react-native-client";
+
+const { toggleCamera } = useCamera();
+const { startMicrophone, stopMicrophone } = useMicrophone();
+const { leaveRoom } = useConnection();
+
+// Listen for mute toggle from CallKit UI
+useCallKitEvent("muted", (isMuted: boolean) => {
+  if (isMuted) {
+    stopMicrophone();
+  } else {
+    startMicrophone();
+  }
+});
+
+// Listen for hold state changes
+useCallKitEvent("held", (isOnHold: boolean) => {
+  console.log("Call hold state:", isOnHold);
+  // Handle hold state in your app
+});
+
+// Listen for call end from CallKit UI
+useCallKitEvent("ended", () => {
+  // Handle call termination
+  leaveRoom();
+});
+```
+
   </TabItem>
 </Tabs>

docs/how-to/react-native/metadata-and-broadcasting.mdx

@@ -14,7 +14,7 @@ import ReadingMetadata from "../_common/metadata/reading.mdx";
 <JoiningRoom>
 
 ```tsx
-const FISHJAM_URL = "some-fishjam-url";
+const FISHJAM_ID = "some-fishjam-id";
 const PEER_TOKEN = "some-peer-token";
 // ---cut---
 import React, { useCallback } from "react";
@@ -30,7 +30,7 @@ export function JoinRoomButton() {
 
   const onPressJoin = useCallback(async () => {
     await joinRoom<PeerMetadata>({
-      url: FISHJAM_URL,
+      fishjamId: FISHJAM_ID,
       peerToken: PEER_TOKEN,
       peerMetadata: { displayName: "John Wick" }, // [!code highlight]
     });

docs/how-to/react-native/screensharing.mdx

@@ -17,7 +17,18 @@ To enable screen sharing on android, you need enable foreground services. Here i
 
 ### iOS
 
-To enable screen share feature on iOS, you need to follow below steps
+To enable screen sharing on iOS, you need to follow the steps below.
+
+:::tip[Background streaming during screen sharing]
+
+If you want to continue screen sharing when the app goes to the background, you need to:
+
+1. Enable VoIP background mode by setting `enableVoIPBackgroundMode: true` in the plugin configuration or adding the VoIP background mode to your `Info.plist`
+2. Use the [`useCallKitService`](../../api/mobile/variables/useCallKitService) hook in your component to manage the CallKit session
+
+See the [background calls documentation](./background-streaming) for detailed instructions and code examples.
+
+:::
 
 <Tabs groupId="app-type">
 
@@ -34,7 +45,8 @@ You need to modify `app.json` file and add our plugin:
         "@fishjam-cloud/react-native-client",
         {
           "ios": {
-            "enableScreensharing": true
+            "enableScreensharing": true,
+            "enableVoIPBackgroundMode": true
           },
           "android": {
             "enableForegroundService": true
@@ -145,6 +157,15 @@ Configuring screen sharing on iOS is a little complicated.
    <string>{{BUNDLE_IDENTIFIER}}.FishjamScreenBroadcastExtension</string>
    ```
 
+1. If you want to enable background streaming during screen sharing, add VoIP background mode to your `Info.plist`:
+
+   ```xml title='Info.plist'
+   <key>UIBackgroundModes</key>
+   <array>
+     <string>voip</string>
+   </array>
+   ```
+
 1. Run `pod install`, rebuild your app and enjoy!
 
   </TabItem>