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)
Manual installation (Android only, React Native <= 0.59)
- 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
- 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')
- Insert the following lines inside the dependencies block in
android/app/build.gradle
:
implementation project(':@voximplant_react-native-foreground-service')
- Add the FOREGROUND_SERVICE permission to the application's
AndroidManifest.xml
:
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
- Add VIForegroundService as a service to the application's
AndroidManifest.xml
:
<service android:name="com.voximplant.foregroundservice.VIForegroundService"> </service>
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
};
VIForegroundService.createNotificationChannel(channelConfig);
Start foreground service
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);
}
}
Stop foreground service
VIForegroundService.stopService();
Reference
Methods
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
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 |
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 |