cordova-plugin-foreground-service

NOTE: This plugin does not on its own allow the user to execute javascript while the app is in the background. This must be accompanied by another plugin that will create a background process that will give the application background cycles. This plugin mainly exists to solve the problem outlined here. An app will have restricted background processing if it is not considered a "foreground app" for android API 26+ and will prevent background pluggins from functioning properly. With this plugin your application will be a foreground app and let your background services run properly. This plugin may also help with android doze where an application may not run in the background unless it also has a foreground process. Do not expect this plugin on its own to allow your app to execute javascript while in the background.

This plugin allows for android devices to continue running services in the background, using a foreground ongoing notification. This is targeted towards use with plugins such as 'cordova-geolocation' that will not run while the app is in the background on android API 26+.

Requirements

• cordova-android version >= 7.0.0
• android-sdk api >= 26

NOTE: Using cordova version >= 8.0.0 is recommended.

Setup and Usage

Install

cordova plugin add cordova-plugin-foreground-service

#or

cordova plugin add https://github.com/DavidBriglio/cordova-plugin-foreground-service

Start Method

To enable the foreground service, call the start method:

cordova.plugins.foregroundService.start('Notification Title', 'Notification Text', 'drawable-icon-name', [notification importance], [notification id]);

// High priority with notification id 10
// ('myicon.png' is in the 'res/drawable' folder)
cordova.plugins.foregroundService.start('GPS Running', 'Background Service', 'myicon', 3, 10);

// Notification id is optional
cordova.plugins.foregroundService.start('GPS Running', 'Background Service', 'myicon', 3);

// Notification importance is optional, the default is 1 - Low (no sound or vibration)
cordova.plugins.foregroundService.start('GPS Running', 'Background Service', 'myicon');

// Icon is optional, but will use a 'star' icon as the default
cordova.plugins.foregroundService.start('GPS Running', 'Background Service');

Stop Method

To disable the foreground service, call the stop method:

cordova.plugins.foregroundService.stop();

Parameters

Icon

The drawable icon can be any drawable image that exists in the resource folder. This means you must copy the icon you want to use into the platforms/android/app/src/main/res/drawable folder set. If no icon can be found using the icon name parameter, a default star icon will be used.

NOTE: The normal android drawable (R.drawable) icons are not available for use as icons. You cannot reference these icons through the start icon parameter. Include your icon manually in the folders mentioned above.

Notification ID

The notification id is a customizable integer that is used to reference the notification that will be launched. This is customizable to avoid conflicting with any other notifications. If this is not included, a default id will be used.

Notification Importance

Notification importance dictates how the notification is initially presented:

Value | Importance | Description --- | --- | --- 1|IMPORTANCE_LOW|Does not make a sound or heads-up display. (Default) 2|IMPORTANCE_DEFAULT|Makes a sound, but no heads-up display. 3|IMPORTANCE_HIGH|Makes a sound and heads-up display.

Questions?

Please feel free to open an issue or make a pull request!

License

MIT - Please see the LICENSE file for details.

David Briglio (2018)