react-native-foreground-service

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.

Getting started

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

Automatic installation (Android only)

• 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>
     

Manual installation (Android only, React Native <= 0.59)

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"
            android:exported="false"> </service>
   

6. For targetSdkVersion Android API >= 31

   Add android:exported="true" to the application's AndroidManifest.xml activity section

   <activity
       android:name=".MainActivity"
       android:label="@string/app_name"
       android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
       android:windowSoftInputMode="adjustResize"
       android:exported="true">        <===== Add this line
   

Demo project

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

Usage

Import module

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

Create notification channel (Android 8+)

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
};
await VIForegroundService.getInstance().createNotificationChannel(channelConfig);

Start foreground service

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

Stop foreground service

await VIForegroundService.getInstance().stopService();

Reference

Methods

async startService(notificationConfig)

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

---

async stopService()

Stops the foreground service

---

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

---

on(event, handler)

Adds a handler to be invoked when a button on the notification is pressed. Supported event: VIForegroundServiceButtonPressed.

---

off(event, handler)

Removes the registered handler for the VIForegroundServiceButtonPressed event. If handler is not provided, this function will remove all registered handlers.

Configs

NotificationChannelConfig

Property name	Description	Required
id	Unique channel id	yes
name	Notification channel name	yes
description	Notification channel description	no
importance	Notification channel importance. One of: 1 – 'min' 2 – 'low' (by default) 3 – 'default' 4 – 'high' 5 – 'max'	no
enableVibration	Sets whether notification posted to this channel should vibrate. False by default.	no

NotificationConfig

Property name	Description	Required
channelId	Notification channel id to display the notification	yes (Android 8+ only)
id	Unique notification id	yes
title	Notification title	yes
text	Notification text	yes
icon	Icon name	yes
button	Button text	no
priority	Priority of this notification. One of:  0 – PRIORITY_DEFAULT (by default) -1 – PRIORITY_LOW -2 – PRIORITY_MIN  1 – PRIORITY_HIGH  2 – PRIORITY_MAX	no