@voximplant/react-native-foreground-service

    2.0.0 • Public • Published

    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"> </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

    Install

    npm i @voximplant/react-native-foreground-service

    DownloadsWeekly Downloads

    1,480

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    26 kB

    Total Files

    13

    Last publish

    Collaborators

    • yulia_grigorieva
    • sgorshkov
    • voxadmin
    • vindi
    • irgalamarr
    • p4ud
    • npugachev
    • tgodzhiev
    • tatiana_shestakova
    • todti
    • nsladkii
    • taffik