react-native-foreground-service-update

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",
  lockscreenVisibility: 1, //VISIBILITY_PRIVATE (0), VISIBILITY_PUBLIC (1), VISIBILITY_SECRET (-1)
  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',
        subText: 'Notification subtext',
        autoCancel: true,
        ongoing: true,
        onlyAlertOnce: true,
        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