Repository files navigation

SAMPLE APP 👉

Plugin for theCordova framework to perform infinite background execution.

Most mobile operating systems are multitasking capable, but most apps don't need to run while in background and notpresent for the user. Therefore, they pause the app in background mode and resume the app before switching to foregroundmode.The system keeps all network connections open while in background, but does not deliver the data until the app resumes.

• Cordova Background Plugin
  • Store Compliance
  • Supported Platforms
  • Installation
  • Usage
    • Enable the background mode
    • Check if running in background
    • Listen for events
  • Android specifics
    • Transit between application states
    • Back button
    • Recent task list
    • Detect screen status
    • Unlock and wake-up
    • Notification
      • Override defaults
      • Add an icon file
      • Run in background without notification
  • Quirks
  • License

Infinite background tasks are not official supported on most mobile operating systems and thus not compliant with publicstore vendors. A successful submssion isn't garanteed.

Use the plugin by your own risk!

• Android/Amazon FireOS
• Browser
• iOS
• Windows(see #222)

The plugin can be installed viaCordova-CLI.

Execute from the projects root folder:

cordova plugin add https://github.com/nextivity/cordova-plugin-background-mode

The plugin creates the objectcordova.plugins.backgroundMode and is accessible after thedeviceready event has beenfired.

document.addEventListener('deviceready',function(){// cordova.plugins.backgroundMode is now available},false);

The plugin is not enabled by default. Once it has been enabled the mode becomes active if the app moves to background.

cordova.plugins.backgroundMode.enable();// orcordova.plugins.backgroundMode.setEnabled(true);

To disable the background mode:

cordova.plugins.backgroundMode.disable();// orcordova.plugins.backgroundMode.setEnabled(false);

Once the plugin has been enabled and the app has entered the background, the background mode becomes active.

cordova.plugins.backgroundMode.isActive();// => boolean

A non-active mode means that the app is in foreground.

The plugin fires an event each time its status has been changed. These eventsareenable,disable,activate,deactivate andfailure.

cordova.plugins.backgroundMode.on('EVENT',function);

To remove an event listeners:

cordova.plugins.backgroundMode.un('EVENT',function);

Android allows to programmatically move from foreground to background or vice versa.

cordova.plugins.backgroundMode.moveToBackground();// orcordova.plugins.backgroundMode.moveToForeground();

Override the back button on Android to go to background instead of closing the app.

cordova.plugins.backgroundMode.overrideBackButton();

Exclude the app from the recent task list works on Android 5.0+.

cordova.plugins.backgroundMode.excludeFromTaskList();

The method works async instead ofisActive() orisEnabled().

cordova.plugins.backgroundMode.isScreenOff(function(bool){...});

A wake-up turns on the screen while unlocking moves the app to foreground even the device is locked.

// Turn screen oncordova.plugins.backgroundMode.wakeUp();// Turn screen on and show app even lockedcordova.plugins.backgroundMode.unlock();

To indicate that the app is executing tasks in background and being paused would disrupt the user, the plug-in has tocreate a notification while in background - like a download progress bar.

The title, text and icon for that notification can be customized as below. Also, by default the app will come toforeground when tapping on the notification. That can be changed by setting resume to false. On Android 5.0+, the coloroption will set the background color of the notification circle. Also on Android 5.0+, setting hidden to false will makethe notification visible on lockscreen.

cordova.plugins.backgroundMode.setDefaults({title:String,text:String,icon:'icon',// this will look for icon.png in platforms/android/res/drawable|mipmapcolor:String,// hex format like 'F14F4D'resume:Boolean,hidden:Boolean,bigText:Boolean})

Note: All properties are optional - only override the things you need to.

To add an image asset to be used as a notification icon add a resource file definition to the projectsconfig.xml.

<!-- config.xml--><platformname="android"><!-- Add a notification icon image--><!-- "src" is where the image is; from the project root--><!-- "target" needs to be the `drawable` dir inside `platforms/android` and the file name must match the `icon` string given in  `cordova.plugins.backgroundMode.setDefaults`-->  <resource-filesrc="res/icon/android/icon.png"target="app/src/main/res/drawable/icon.png"/></platform>

To modify the currently displayed notification

cordova.plugins.backgroundMode.configure({...});

In silent mode the plugin will not display a notification - which is not the default. Be aware that Android recommendsadding a notification otherwise the OS may pause the app.

cordova.plugins.backgroundMode.setDefaults({silent:true});

Various APIs like playing media or tracking GPS position in background might not work while in background even thebackground mode is active. To fix such issues the plugin provides a method to disable most optimizations done byAndroid/CrossWalk.

cordova.plugins.backgroundMode.on('activate',function(){cordova.plugins.backgroundMode.disableWebViewOptimizations();});

Note: Calling the method led to increased resource and power consumption.

This software is released under theApache 2.0 License.

Made with 😋 from Leipzig

? 2017appPlant GmbH &meshfields