A foreground service performs some operation that is noticeable to the user. For example, an audio app would use a foreground service to play an audio track. Foreground services must display a notification. Foreground services continue running even when the user isn't interacting with the app.

See the Android official documentation for details on the concept.

$ npm install @voximplant/react-native-foreground-service --save

• React Native 0.60+

  CLI autolink feature links the module while building the app.

  1. Add the FOREGROUND_SERVICE permission to the application's AndroidManifest.xml:

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

  2. Add VIForegroundService as a service to the application's AndroidManifest.xml:

     <service android:name="com.voximplant.foregroundservice.VIForegroundService"> </service>
     
     

• React Native <= 0.59

  $ react-native link @voximplant/react-native-foreground-service

  1. Add the FOREGROUND_SERVICE permission to the application's AndroidManifest.xml:

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

  2. Add VIForegroundService as a service to the application's AndroidManifest.xml:

     <service android:name="com.voximplant.foregroundservice.VIForegroundService"> </service>
     

1. Open up android/app/src/main/java/[...]/MainActivity.java
   • Add import com.voximplant.foregroundservice.VIForegroundServicePackage; to the imports at the top of the file
   • Add new VIForegroundServicePackage() to the list returned by the getPackages() method
2. Append the following lines to android/settings.gradle:

   include ':@voximplant_react-native-foreground-service'
   project(':@voximplant_react-native-foreground-service').projectDir = new File(rootProject.projectDir, '../node_modules/@voximplant/react-native-foreground-service/android')
   

3. Insert the following lines inside the dependencies block in android/app/build.gradle:

   implementation project(':@voximplant_react-native-foreground-service')
   

4. Add the FOREGROUND_SERVICE permission to the application's AndroidManifest.xml:

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

5. Add VIForegroundService as a service to the application's AndroidManifest.xml:

   <service android:name="com.voximplant.foregroundservice.VIForegroundService"> </service>
   

Demo application: react-native-foreground-service-demo

import VIForegroundService from '@voximplant/react-native-foreground-service';

Since the foreground service must display a notification, for Android 8+ it is required to create a notification channel first:

const channelConfig = {
    id: 'channelId',
    name: 'Channel name',
    description: 'Channel description',
    enableVibration: false
};
VIForegroundService.createNotificationChannel(channelConfig);

async startForegroundService() {
    const notificationConfig = {
        channelId: 'channelId',
        id: 3456,
        title: 'Title',
        text: 'Some text',
        icon: 'ic_icon'
    };
    try {
        await VIForegroundService.startService(notificationConfig);
    } catch (e) {
        console.error(e);
    }
}

VIForegroundService.stopService();

static async startService(notificationConfig)

Starts the foreground service and displays a notification with the defined configuration

static async stopService()

Stops the foreground service

static async createNotificationChannel(channelConfig)

Creates a notification channel for the foreground service. For Android 8+ the notification channel should be created before starting the foreground service

NotificationChannelConfig

NotificationConfig