Persistent Notification for Capacitor

A Capacitor plugin that allows a continuous background service by using a persistent notification in Android. Your background task/service is written in JavaScript, no need for platform specific code (except that required of enabling a Capacitor plugin.)

Based upon, though not a fork of, the Cordova Background Mode Plugin.

In order to allow an app written in HTML5/Javascript/CSS to continuously run in the background using a persistent foreground service notification in Android.

This plugin uses the new Ionic/Capacitor plugin system

Unfortunately, because of system limitations, this plugin ONLY works on Android! The plugin calls are NO-OP on the web platform, and non-existent in iOS and Electron. Further research may allow a persistent background service in Electron. iOS does not have a system that allows a persistent background service. (I understand there are hacky methods to make it work in iOS, but until there is a proper API I plan no updates for iOS.)

KNOWN ISSUE LIMITATION: Unfortunately because the JavaScript code used to run a Capacitor app lives in an Android Activity, it is not currently possible to restart a service upon shutdown, crash, or reboot. See Android limitation. I am currently researching possible solutions. For now try to keep memory consumption to a minimum while app is in “background” state.

Examples | API | Changelog | Donate

NPM Repository

capacitor-persistent-notification

Installation

Ensure Android is added to your Capacitor based project:

npx cap add android

Use NPM in your project directory to install the plugin.

npm install capacitor-persistent-notification@latest --save
npx cap update

Getting Started

Ensure your project includes the Capacitor plugin code.

Standard HTML import:

<script src="capacitor.js"></script>

const { Plugins } = Capacitor;
const { PersistentNotification } = Plugins;

or Node Imports:

import { Plugins } from '@capacitor/core';
const { PersistentNotification } = Plugins;

Be sure to add the plugin to your MainActivity in your Android project:

import com.flytesoft.persistent.notification.PersistentNotification;
public class MainActivity extends BridgeActivity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // Initializes the Bridge
    this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {
        {
            // Additional plugins you've installed go here
            // Ex: add(TotallyAwesomePlugin.class);
            add(PersistentNotification.class);
        }
    });
  }
}

Add the foreground service permission to the AndroidManifest.xml:

<!-- Permissions -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" ></uses-permission>

Example Code

It is recommended, although not required, to open your notification upon your app closing:

const { PersistentNotification, App, BackgroundTask } = Plugins;
...
let listener = null;
App.addListener('appStateChange', (state) => {
    // Listen for user clicks on the notification.  
    // OK to listen before opening.
    listener = constPersistentNotification.addListener('notificationclick', ({ action } => {
        console.log("Persistent notification click: ", action);
        if(!action) // A button was NOT clicked.
        {
            // Put the app in the foreground 
            // and close the notification, if desired.
            PersistentNotification.appToForeground();
            PersistentNotification.close();
        }
        else // A button was clicked by the user.
        {
            if(action === 'button-click2')
            {
                console.log("Button 2 was clicked!");
            }
        }
    });
    if (!state.isActive) // App has gone inactive or closed
    {
        // Get some work done before the app closes completely.
        const taskId = BackgroundTask.beforeExit(async () => {
            try
            {
                await PersistentNotification.open({
                    title: "Background Forever!", 
                    icon: "icons/icon.png",  
                    // Icon asset exist in www/icons/icon.png
                    // Icon asset always based upon TLD and 
                    // NOT the location of your code.
                    body: "We can run continuously!",
                    actions: [{
                            title: "button", 
                            action: "button-click", 
                            icon: "icons/icon.png"
                        },
                        {
                            title: "button2",
                            action: "button-click2", 
                            icon: "icons/icon.png"
                        }]
                });
                // See if the notification is open.
                const { isOpen } = await PersistentNotification.getState();
                console.log("Is open: ", isOpen);
            }
            catch(e)
            {
                console.log("Unable to start background service: ", e);
            }
            // Let the app close.
            BackgroundTask.finish({
                taskId
            });
        });
        /** 
         * It is recommended you stop any code that updates the DOM:  
         * The DOM will still be 'awake' but not visible to the user.  
         * So save CPU power.
         *
         * stopVisualTasks();
         * */
        // Now do your continuous background task.
        // Update the notification as necessary.
        let interval = 1;
        setInterval(() => {
            PersistentNotification.update({
                body: `Seconds gone by: ${interval}`);
            interval++;
        }, 1000);
    }
    else // App is now opening or resuming.
    {
        // OK to close un-opened notification.
        PersistentNotification.close().
            catch(e => {
                console.log("Trouble closing the persistent notification: ", e);
            });
        // remove the listener.
        if(listener != null)
        {
            listener.remove();
            listener = null;
        }
    }
});

API

The API is similar to the the standard ES6+ Notification API. However, the PersistentNotification class is completely static and all methods return Promises, as do most of the Capacitor APIs and plugins.

PersistentNotification.open([options]) ⇒ Promise

A method to open and configure your persistent notification. Returns success upon notification opening. Configuration options are only optional if you have previously called the update method.

Kind: Static instance method of PersistentNotification
Category: async
Fulfil: undefined
Throws: Error

| Param | Type | Description |
| —- | —- | —- |
| [options] | object | Similar to the Notification API options. |
| [options.title] | string | Set the title of the notification. Limited HTML may be used (Required) |
| [options.body] | string | Set the content or body area of the notification. Limited HTML may be used (Required)|
| [options.color] | string | Set the highlight color of the notification. Hex code or color names only). If undefined or invalid, defaults to blue. |
| [options.actions] | Array.<NotificationAction> | An array of one or more buttons to be included. |
| [options.icon] | string | Location of the icon to be displayed in the status bar for the notification. Must use a relative path to icon resource from your top level directory. If undefined or invalid, a default icon is provided. |

| [options.badge] | string | Location of a large (badge type) icon to be displayed in the notification. Must use a relative path to the resource from your top level directory. If undefined or invalid, no badge is displayed. |

PersistentNotification.update([options]) ⇒ Promise

A method to configure and/or update a current notification. If a notification is not already open your configuration will be maintained until open is called. Only update options you need to update. See open for parameters.

Kind: Static instance method of PersistentNotification
Category: async
Fulfil: undefined
Throws: Error

PersistentNotification.close(void) ⇒ Promise

Closes the notification. If the notification is not open, the method is NO-OP and returns success. If unable to close the notification an error is thrown.

Kind: Static instance method of PersistentNotification
Category: async
Fulfil: undefined
Throws: Error

PersistentNotification.appToForeground(void) ⇒ Promise

Brings the main application view or webview into the foreground. If the app is already in the foreground the method is NO-OP. Useful to call when the user has clicked on the notification.

Kind: Static instance method of PersistentNotification
Category: async
Fulfil: undefined

PersistentNotification.getState(void) ⇒ Promise

A promise that returns whether the notification is currently open.

Kind: Static instance method of PersistentNotification
Category: async
Fulfil: state

PersistentNotification.addListener(eventName: ‘notificationclick’, listenerFunc: (data: action) => void) : ListenerHandle

Kind: Static instance method of PersistentNotification
Category: EventListener
Returns: ListenerHandle

Add an event listener when the notification is clicked. The data object is passed to the listener function.
| Param | Type | Description |
| —- | —- | —- |
| data | object | Data object passed to event listener function |
| data.action | string | Actions string value, if a button is clicked the value will be the ‘action’ or title of that button. An empty string indicates the notification was clicked by the user. |

ListenerHandle object

Category: object

Object containing the event listener for the notification. Call remove() to delete the event listener.

NotificationAction object

Category: object

Object containing the options for a button to be displayed in the notification, similar to the NotificationAction object in ES6+.

state object

Category: object

Object containing the state information of the notification

Changelog

0.9.5

• Kill some memory leaks.
• Attempt to ready code to handle service crashes/restarts.

0.9.4

• Performance improvements.
• Longer text may be used in the body.
• Body and title of notification may use limited HTML markup.
• Readme fixes.

0.9.3

• Readme fixes.

0.9.2

• Readme fixes.

0.9.1

• Readme fixes.
• Distribution file fixes.

0.9.0

• Initial commit.

Donation / Tips

If you found this project useful and you would like to help buy me a cup of coffee, consider a donation via Paypal. (Not tax deductible. Non-charitable.) Either way, I am hoping you find this project useful.

License

MIT