Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

cordova-plugin-background-mode-alex

katzer7Apache 2.00.7.3

Prevent app from going to sleep in background.

appplant, background, cordova, ecosystem:cordova

readme

SAMPLE APP :point_right:

Cordova Background Plugin npm version Build Status codebeat badge

Plugin for the Cordova framework to perform infinite background execution.

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

Store Compliance

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

Use the plugin by your own risk!

Supported Platforms

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

Installation

The plugin can be installed via Cordova-CLI and is publicly available on NPM.

Execute from the projects root folder:

$ cordova plugin add cordova-plugin-background-mode

Or install a specific version:

$ cordova plugin add de.appplant.cordova.plugin.background-mode@VERSION

Or install the latest head version:

$ cordova plugin add https://github.com/katzer/cordova-plugin-background-mode.git

Or install from local source:

$ cordova plugin add cordova-plugin-background-mode --searchpath <path>

Usage

The plugin creates the object cordova.plugins.backgroundMode and is accessible after the deviceready event has been fired.

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

Enable the background mode

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();
// or
cordova.plugins.backgroundMode.setEnabled(true);

To disable the background mode:

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

Check if running in background

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.

Listen for events

The plugin fires an event each time its status has been changed. These events are enable, disable, activate, deactivate and failure.

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

To remove an event listeners:

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

Android specifics

Transit between application states

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

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

Back button

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

cordova.plugins.backgroundMode.overrideBackButton();

Recent task list

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

cordova.plugins.backgroundMode.excludeFromTaskList();

Detect screen status

The method works async instead of isActive() or isEnabled().

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

Unlock and wake-up

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

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

Notification

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

Override defaults

The title, text and icon for that notification can be customized as below. Also, by default the app will come to foreground when tapping on the notification. That can be changed by setting resume to false. On Android 5.0+, the color option will set the background color of the notification circle. Also on Android 5.0+, setting hidden to false will make the 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|mipmap
    color: String // hex format like 'F14F4D'
    resume: Boolean,
    hidden: Boolean,
    bigText: Boolean
})

To modify the currently displayed notification

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

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

Run in background without notification

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

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

Quirks

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

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

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

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

License

This software is released under the Apache 2.0 License.

Made with :yum: from Leipzig

© 2017 appPlant GmbH

changelog

ChangeLog

Version 0.7.3 (not yet released)

  • Check if screen is off on Android
  • Wake-up device on Android
  • Unlock device on Android

Version 0.7.2 (02.02.2017)

  • Fixed app freeze on iOS using wkwebview-engine
  • Websocket sample in SampleApp

Version 0.7.1 (30.01.2017)

  • Bug fixes for iOS9 and Android
  • Allow app to be excluded from recent list on Android

Version 0.7.0 (27.01.2017)

  • Features
    • Support for tAmazon FireOS
    • Support for the browser platform
    • Ability to configure icon and color on Android
    • Allow app to move to foreground on Android
    • Allow app to move to background on Android
    • Allow app to override back button behaviour on Android
    • New events for when the mode has been enabled/disabled
  • Improvements
    • Various enhancements and bug fixes for all platforms
    • Support for latest platform and OS versions
    • Multi line text on Android
    • Multiple listeners for same event
    • Compatibility with cordova-plugin-geolocation
    • Compatibility with cordova-plugin-crosswalk-webview
    • Compatibility with cordova-plugin-wkwebview-engine
    • New sample app
  • Fixes
    • Silent mode issues on Android
    • Lock screen issues on Android
    • Callback not called on Android
    • Notification shows app info with cordova-android@6
    • Other apps audio interruption on iOS
  • Changes
    • Deprecate event callbacks
    • Notification not visible by default on lock screen
    • Remove ticker property on Android
    • Remove unexpected back button handler
    • Remove support for wp8 platform

Version 0.6.5 (29.02.2016)

  • Published on npm
  • Updated dependency ID for the device plug-in

Version 0.6.4 (03.03.2015)

  • Resolve possibly dependency conflict

Version 0.6.3 (01.01.2015)

  • [feature:] Silent mode for Android

Version 0.6.2 (14.12.2014)

  • [bugfix:] Type error
  • [bugfix:] Wrong default values for isEnabled and isActive.

Version 0.6.1 (14.12.2014)

  • [enhancement:] Set default settings through setDefaults.
  • [enhancement:] New method isEnabled to receive if mode is enabled.
  • [enhancement:] New method isActive to receive if mode is active.
  • [bugfix:] Events caused thread collision.

Version 0.6.0 (14.12.2014)

  • [feature:] Android support
  • [feature:] Change Android notification through configure.
  • [feature:] onactivate, ondeactivate and onfailure callbacks.
  • [change:] Disabled by default
  • [enhancement:] Get default settings through getDefaults.
  • [enhancement:] iOS does not require user permissions, internet connection and geo location anymore.

Version 0.5.0 (13.02.2014)

  • retired

Version 0.4.1 (13.02.2014)

  • Release under the Apache 2.0 license.
  • [enhancement:] Location tracking is only activated on WP8 if the location service is available.
  • [bigfix:] Nullpointer exception on WP8.

Version 0.4.0 (10.10.2013)

  • Added WP8 support
    The plugin turns the app into an location tracking app (for the time it runs in the background).

Version 0.2.1 (09.10.2013)

  • Added js interface to manually enable/disable the background mode.

Version 0.2.0 (08.10.2013)

  • Added iOS (>= 5) support
    The plugin turns the app into an location tracking app for the time it runs in the background.