Cordova plugin to prevent the app from going to sleep while in background.
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.
This cordova plug-in can be used for applications, who rely on continuous network communication independent of from direct user interactions and remote push notifications.
The plugin focuses on enterprise-only distribution and may not compliant with all public store vendors.
- iOS
- Android
- WP8
The plugin can either be installed from git repository, from local file system through the Command-line Interface. Or cloud based through PhoneGap Build.
From master:
# ~~ from master branch ~~
cordova plugin add https://github.com/katzer/cordova-plugin-background-mode.git
from a local folder:
# ~~ local folder ~~
cordova plugin add de.appplant.cordova.plugin.background-mode --searchpath path
or to use the last stable version:
# ~~ stable version ~~
cordova plugin add [email protected]
Add the following xml to your config.xml to always use the latest version of this plugin:
<gap:plugin name="de.appplant.cordova.plugin.background-mode" version="0.5.0" />
More informations can be found here.
- [feature:] Android support
- [change:] Disabled by default
- [enhancement:] iOS does not require user permissions, internet connection and geo location anymore.
- The former
plugin.backgroundMode
namespace has been deprecated and will be removed with the next major release. - See CHANGELOG.md to get the full changelog for the plugin.
The plugin creates the object cordova.plugins.backgroundMode
with the following methods:
The plugin and its methods are not available before the deviceready event has been fired.
document.addEventListener('deviceready', function () {
// cordova.plugins.backgroundMode is now available
}, false);
To prevent the app from being paused while in background, the backroundMode.enable
interface has to be called.
- The background mode will be activated once the app has entered the background and will be deactivated after the app has entered the foreground.
- To activate the background mode the app needs to be in foreground.
window.plugin.backgroundMode.enable();
The background mode can be disabled through the backgroundMode.disable
interface.
- Once the background mode has been disabled, the app will be paused when in background.
window.plugin.backgroundMode.disable();
The following example demonstrates how to enable the background mode after device is ready. The mode itself will be activated when the app has entered the background.
document.addEventListener('deviceready', function () {
// Enable background mode
cordova.plugins.backgroundMode.enable();
// Android customization
cordova.plugins.backgroundMode.configure({ text:'Doing heavy tasks.'});
}, false);
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.
The title, ticker and text for that notification can be customized in the following way at any time:
cordova.plugins.backgroundMode.configure({
title: String,
ticker: String,
text: String
})
By default the app will come to foreground when taping on the notification. That can be changed also.
cordova.plugins.backgroundMode.configure({
resume: false
})
By default the plugin will track for geo updates while the application is in background and foreground. To stop tracking in foreground, the MainPage.xaml.cs
file needs the following 2 methods:
// MainPage.xaml.cs
namespace your.own.namespace
{
public partial class MainPage : PhoneApplicationPage
{
/// </summary>
/// The page (the app) will enter the background and the background mode
/// needs to be activated.
/// </summary>
protected override void OnNavigatingFrom(System.Windows.Navigation.NavigatingCancelEventArgs e)
{
Cordova.Extension.Commands.BackgroundMode.Activate();
}
/// </summary>
/// The page (the app) will enter the foreground and the background mode
/// needs to be deactivated.
/// </summary>
protected override void OnNavigatedTo(System.Windows.Navigation.NavigationEventArgs e)
{
Cordova.Extension.Commands.BackgroundMode.Deactivate();
}
}
}
If the app crashes after installing the plugin, make sure that your *-Info.plist
is valid and reset all occurences of blank strings
<key>NSMainNibFile</key>
<string>
</string>
to
<key>NSMainNibFile</key>
<string></string>
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
This software is released under the Apache 2.0 License.
© 2013-2014 appPlant UG, Inc. All rights reserved