react-native-foreground-service-android

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.

This app is a library created by forking @voximplant/react-native-foreground-service.

Getting started

$ npm install react-native-foreground-service-android --save

OR

$ yarn add react-native-foreground-service-android

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 LTForegroundService as a service to the application's AndroidManifest.xml:

     <service android:name="com.leetaehong.foregroundservice.LTForegroundService"
     android:exported="true" <- If you want it to be maintained even after the app is turned off, default : "false"
     />
     

android:exported

• Indicates whether components of other applications can call or interact with the service. If a call or interaction is possible, it is "true", otherwise "false". If this value is "false", only applications with the same application component or the same user ID can start or bind to the service. The default value depends on whether the service contains an intent filter. If there is no filter, the service can be called only when the exact class name is specified. This suggests that the service is designed only for internal application purposes (because others do not know the class name). Therefore, in this case, the default value is "false", whereas if there is more than one filter, it implies that the service is designed for external purposes, so the default value is "true". In addition to this characteristic, there is a way to limit services from being exposed to other applications. You can also use permission to restrict external entities that can interact with the service (see permission attributes).

• React Native <= 0.59

  $ react-native link @leetaehong/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 LTForegroundService as a service to the application's AndroidManifest.xml:

     <service android:name="com.leetaehong.foregroundservice.LTForegroundService"> </service>
     

  3. If you want to use the background service, you add LTForegroundTask as a service to the application's AndroidManifest.xml:

     <service android:name="com.leetaehong.foregroundservice.LTForegroundTask"/>
     

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

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

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

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

   implementation project(':@leetaehong_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 LTForegroundService as a service to the application's AndroidManifest.xml:

   <service android:name="com.leetaehong.foregroundservice.LTForegroundService"> </service>
   

6. If you want to use the background service, you add LTForegroundTask as a service to the application's AndroidManifest.xml:

   <service android:name="com.leetaehong.foregroundservice.LTForegroundTask"/>
   

Demo project

Demo application: none

Usage

Import module

import LTForegroundService, {
  IChannelConfig,
  INotificationConfig,
} from "react-native-foreground-service-android";

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: IChannelConfig = {
  id: "channelId",
  name: "Channel name",
  description: "Channel description",
  enableVibration: false,
};
LTForegroundService.createNotificationChannel(channelConfig);

Update foreground service

async startForegroundService() {
    const notificationConfig: INotificationConfig = {
        channelId: 'channelId', // you must same channelId and id
        id: 3456,
        title: 'Title',
        text: 'Some text',
        icon: 'ic_icon',
        ongoing: true // default false
    };
    try {
        await LTForegroundService.updateService(notificationConfig);
    } catch (e) {
        console.error(e);
    }
}

Start foreground service

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

Stop foreground service

LTForegroundService.stopService();

Start background foreground service

async backgroundStartService() {
    const backgroundConfig : IBackgroundConfig = {
        channelId: 'channelId',
        id: 3456,
        title: 'Title',
        text: 'Some text',
        icon: 'ic_icon',
        ongoing: true, // default false
        taskName: "BackgroundTask",
        delay: 1000
    };

    const exampleTask = async (taskDataArguments?: IBackgroundConfig) => {
        await new Promise(() => {
            while (ForegroundService.getIsBackgroundRunning()) {
                // you can do anything
                console.log("taskDataArguments")
            }
        });
    };

    try {
        await LTForegroundService.backgroundStartService(exampleTask,backgroundConfig);
    } catch (e) {
        console.error(e);
    }
}

Stop background foreground service

LTForegroundService.backgroundStopService();

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

---

static async updateService(notificationConfig)

It is used to update the foreground service.

• NOTE : When using the update function, the channel ID must be the same.

---

static async backgroundStartService(backgroundConfig)

It is used when you want a notification to run a task in the background.

static async backgroundStopService()

This is used when you want to stop background task notifications.

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
ongoing	To keep the notification or prevent the user from erasing the notification even if the user shuts down the app,	no

BackgroundConfig;

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
ongoing	To keep the notification or prevent the user from erasing the notification even if the user shuts down the app,	no
delay	Set the time to run the task regularly.	no
taskname	Please enter the background task name.	no