Keeping The Call Alive In Background

Keep calls alive when the app goes to the background. Users continue hearing remote audio streams while the app is backgrounded.

Best Practices

Install Notifee - Required for foreground service management on Android
Declare permissions - Add foreground service permissions to AndroidManifest.xml
Request notification permissions - Required for Android 13+ foreground services
Enable audio background mode - Add audio to UIBackgroundModes on iOS
Customize notifications - Configure foreground service notification appearance

Android Setup

Android uses a foreground service to keep calls alive. The SDK manages the foreground service automatically. First, install the Notifee library:

Notifee version 9 or above is required to handle foreground service permissions for the calls.

npx expo install @notifee/react-native

The next step is, in order to be able to use the foreground service, some declarations need to be added the AndroidManifest.xml. In app.json, in the plugins field, add true to the androidKeepCallAlive property in the @stream-io/video-react-native-sdk plugin. This will add the declarations automatically.

{
 "plugins": [
      [
        "@stream-io/video-react-native-sdk",
        {
           "androidKeepCallAlive": true
        }
      ],
      // your other plugins
  ]
}

If Expo EAS build is not used, please do npx expo prebuild --clean to edit the AndroidManifest.xml again after adding the config plugin property.

yarn add @notifee/react-native
npx pod-install

The next step is, in order to be able to use the foreground service, some declarations need to be added in the AndroidManifest.xml:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<!-- We declare the permissions needed for using foreground service to keep call alive -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />

<service
    android:name="app.notifee.core.ForegroundService"
    tools:replace="android:foregroundServiceType"
    android:stopWithTask="true"
    android:foregroundServiceType="shortService|camera|microphone|mediaPlayback" />

When uploading the app to the Play Store, it is essential to declare the permissions for foreground services in the Play Console and provide an explanation for their use. This includes adding a link to a video that demonstrates how the foreground service is utilized during video and audio calls. This procedure is required only once. For more details, click here. The added permissions are:

android.permission.FOREGROUND_SERVICE_CAMERA - To access camera when app goes to background
android.permission.FOREGROUND_SERVICE_MICROPHONE - To access microphone when app goes to background
android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK - To play video and audio tracks when the app goes to background

Request notification permissions

At an appropriate place in your app, request notification permissions from the user. Below is an example of how to request notification permissions using the react-native-permissions library:

import { requestNotifications } from "react-native-permissions";

// This will request POST_NOTIFICATION runtime permission for Anroid 13+
await requestNotifications(["alert", "sound"]);

For a comprehensive guide on requesting all required permissions (camera, microphone, bluetooth, and notifications), see Manage Native Permissions.

Optional: override the default configuration of the foreground service notifications

import { StreamVideoRN } from "@stream-io/video-react-native-sdk";
import { AndroidImportance } from "@notifee/react-native";

StreamVideoRN.updateConfig({
  foregroundService: {
    android: {
      // see https://notifee.app/react-native/reference/nativeandroidchannel
      // for the various properties that can be used
      channel: {
        id: "stream_call_foreground_service",
        name: "Service to keep call alive",
        lights: false,
        vibration: false,
        importance: AndroidImportance.DEFAULT,
      },
      // you can edit the title and body of the notification here
      notificationTexts: {
        title: "Video call is in progress",
        body: "Tap to return to the call",
      },
      // you can optionally add a promise to run in the foreground service
      taskToRun: (call) =>
        new Promise(() => {
          console.log(
            "jumping to foreground service foreground service with call-cid",
            call.cid,
          );
        }),
    },
  },
});

iOS Setup

Enable the audio background mode to keep audio alive when users lock their device or switch apps. In Xcode, add audio to UIBackgroundModes in Info.plist:

<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
</array>

Querying Call Members

Manage Native Permissions