Update readme to be up-to-date
This commit is contained in:
Sebastián Katzer
parent
c005ed9d06
commit
fc49b48d14
274
README.md
274
README.md
@ -1,131 +1,53 @@
|
|||||||
[](http://badge.fury.io/js/cordova-plugin-background-mode)
|
|
||||||
|
|
||||||
<p align="right">
|
<p align="left">
|
||||||
<a href="https://github.com/katzer/cordova-plugin-background-mode/tree/example">EXAMPLE :point_right:</a>
|
<b><a href="https://github.com/katzer/cordova-plugin-background-mode/tree/example">SAMPLE APP</a> :point_right:</b>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
Cordova Background Plug-in
|
Cordova Background Plugin [](http://badge.fury.io/js/cordova-plugin-background-mode) [](https://travis-ci.org/katzer/cordova-plugin-background-mode)
|
||||||
==========================
|
=========================
|
||||||
|
|
||||||
[Cordova][cordova] plugin to prevent the app from going to sleep while in background.
|
Plugin for the [Cordova][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.
|
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.
|
The system keeps all network connections open while in background, but does not deliver the data until the app resumes.
|
||||||
|
|
||||||
### Plugin's Purpose
|
#### Store Compliance
|
||||||
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.
|
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.
|
||||||
|
|
||||||
### :bangbang: Store Compliance :bangbang:
|
Use the plugin by your own risk!
|
||||||
The plugin focuses on enterprise-only distribution and may not compliant with all public store vendors.
|
|
||||||
|
|
||||||
__Update:__ The plugin ID has changed to cordova-plugin-background-mode and is available under npm. An updated version comes later!
|
|
||||||
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
1. [Supported Platforms](#supported-platforms)
|
|
||||||
2. [Installation](#installation)
|
|
||||||
3. [ChangeLog](#changelog)
|
|
||||||
4. [Usage](#usage)
|
|
||||||
5. [Examples](#examples)
|
|
||||||
6. [Platform specifics](#platform-specifics)
|
|
||||||
|
|
||||||
|
|
||||||
## Supported Platforms
|
## Supported Platforms
|
||||||
- __iOS__ (_including iOS8_)
|
- __iOS__
|
||||||
- __Android__ _(SDK >=11)_
|
- __Android__
|
||||||
- __WP8__
|
- __Amazon FireOS__
|
||||||
- __Windows 10__
|
- __Windows__ _(see #222)_
|
||||||
|
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
The plugin can either be installed from git repository, from local file system through the [Command-line Interface][CLI]. Or cloud based through [PhoneGap Build][PGB].
|
The plugin can be installed via [Cordova-CLI][CLI] and is publicly available on [NPM][npm].
|
||||||
|
|
||||||
### Local development environment
|
Execute from the projects root folder:
|
||||||
From master:
|
|
||||||
```bash
|
|
||||||
# ~~ from master branch ~~
|
|
||||||
cordova plugin add https://github.com/katzer/cordova-plugin-background-mode.git
|
|
||||||
```
|
|
||||||
from a local folder:
|
|
||||||
```bash
|
|
||||||
# ~~ local folder ~~
|
|
||||||
cordova plugin add de.appplant.cordova.plugin.background-mode --searchpath path
|
|
||||||
```
|
|
||||||
or to use the last stable version:
|
|
||||||
```bash
|
|
||||||
# ~~ stable version ~~
|
|
||||||
cordova plugin add de.appplant.cordova.plugin.background-mode@0.6.3
|
|
||||||
```
|
|
||||||
|
|
||||||
To remove the plug-in, run the following command:
|
$ cordova plugin add cordova-plugin-background-mode
|
||||||
```bash
|
|
||||||
cordova plugin rm de.appplant.cordova.plugin.background-mode
|
|
||||||
```
|
|
||||||
|
|
||||||
### PhoneGap Build
|
Or install a specific version:
|
||||||
Add the following xml to your config.xml to always use the latest version of this plugin:
|
|
||||||
```xml
|
|
||||||
<gap:plugin name="de.appplant.cordova.plugin.background-mode" version="0.6.3" />
|
|
||||||
```
|
|
||||||
|
|
||||||
More informations can be found [here][PGB_plugin].
|
$ cordova plugin add de.appplant.cordova.plugin.background-mode@VERSION
|
||||||
|
|
||||||
|
Or install the latest head version:
|
||||||
|
|
||||||
## ChangeLog
|
$ cordova plugin add https://github.com/katzer/cordova-plugin-background-mode.git
|
||||||
#### Version 0.7.0 (not yet released)
|
|
||||||
- __Features__
|
|
||||||
- Support for Amazon FireOS
|
|
||||||
- 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 anymore on lock screen
|
|
||||||
- Remove ticker property on Android
|
|
||||||
- Remove unexpected back button handler
|
|
||||||
- Remove support for wp8 platform
|
|
||||||
|
|
||||||
#### Further informations
|
Or install from local source:
|
||||||
- See [CHANGELOG.md][changelog] to get the full changelog for the plugin.
|
|
||||||
- Master branch contains experimental support for the windows platform. See #222
|
|
||||||
|
|
||||||
#### Known issues
|
$ cordova plugin add cordova-plugin-background-mode --searchpath <path>
|
||||||
- README is out of date !!!
|
|
||||||
|
__Note:__ In combination with the `cordova-plugin-wkwebview-engine` plugin the UIBackgroundModes section added by the plugin inside the *-Info.plist can be removed. That might increase the chance to submit the app to the app store.
|
||||||
|
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
The plugin creates the object `cordova.plugins.backgroundMode` with the following methods:
|
The plugin creates the object `cordova.plugins.backgroundMode` and is accessible after the *deviceready* event has been fired.
|
||||||
|
|
||||||
1. [backgroundMode.enable][enable]
|
|
||||||
2. [backgroundMode.disable][disable]
|
|
||||||
3. [backgroundMode.isEnabled][is_enabled]
|
|
||||||
4. [backgroundMode.isActive][is_active]
|
|
||||||
5. [backgroundMode.getDefaults][android_specifics]
|
|
||||||
6. [backgroundMode.setDefaults][android_specifics]
|
|
||||||
7. [backgroundMode.configure][configure]
|
|
||||||
8. [backgroundMode.onactivate][onactivate]
|
|
||||||
9. [backgroundMode.ondeactivate][ondeactivate]
|
|
||||||
10. [backgroundMode.onfailure][onfailure]
|
|
||||||
|
|
||||||
### Plugin initialization
|
|
||||||
The plugin and its methods are not available before the *deviceready* event has been fired.
|
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
document.addEventListener('deviceready', function () {
|
document.addEventListener('deviceready', function () {
|
||||||
@ -133,134 +55,110 @@ document.addEventListener('deviceready', function () {
|
|||||||
}, false);
|
}, false);
|
||||||
```
|
```
|
||||||
|
|
||||||
### Prevent the app from going to sleep in background
|
### Enable the background mode
|
||||||
To prevent the app from being paused while in background, the `backgroundMode.enable` interface has to be called.
|
The plugin is not enabled by default. Once it has been enabled the mode becomes active if the app moves to background.
|
||||||
|
|
||||||
#### Further informations
|
|
||||||
- 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.
|
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
cordova.plugins.backgroundMode.enable();
|
cordova.plugins.backgroundMode.enable();
|
||||||
|
// or
|
||||||
|
cordova.plugins.backgroundMode.setEnabled(true);
|
||||||
```
|
```
|
||||||
|
|
||||||
### Pause the app while in background
|
To disable the background mode:
|
||||||
The background mode can be disabled through the `backgroundMode.disable` interface.
|
|
||||||
|
|
||||||
#### Further informations
|
|
||||||
- Once the background mode has been disabled, the app will be paused when in background.
|
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
cordova.plugins.backgroundMode.disable();
|
cordova.plugins.backgroundMode.disable();
|
||||||
|
// or
|
||||||
|
cordova.plugins.backgroundMode.setEnabled(false);
|
||||||
```
|
```
|
||||||
|
|
||||||
### Receive if the background mode is enabled
|
__Note:__ By using `wkwebview-engine` on iOS, the plugin is enabled by default and cannot be disabled.
|
||||||
The `backgroundMode.isEnabled` interface can be used to get the information if the background mode is enabled or disabled.
|
|
||||||
|
|
||||||
```javascript
|
### Check if running in background
|
||||||
cordova.plugins.backgroundMode.isEnabled(); // => boolean
|
Once the plugin has been enabled and the app has entered the background, the background mode becomes active.
|
||||||
```
|
|
||||||
|
|
||||||
### Receive if the background mode is active (Android/iOS only)
|
|
||||||
The `backgroundMode.isActive` interface can be used to get the information if the background mode is active.
|
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
cordova.plugins.backgroundMode.isActive(); // => boolean
|
cordova.plugins.backgroundMode.isActive(); // => boolean
|
||||||
```
|
```
|
||||||
|
|
||||||
### Get informed when the background mode has been activated (Android/iOS only)
|
A non-active mode means that the app is in foreground.
|
||||||
The `backgroundMode.onactivate` interface can be used to get notified when the background mode has been activated.
|
|
||||||
|
### Listen for events
|
||||||
|
The plugin fires an event each time its status has been changed. These events are `enable`, `disable`, `activate`, `deactivate` and `failure`.
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
cordova.plugins.backgroundMode.onactivate = function() {};
|
cordova.plugins.backgroundMode.on('EVENT', function);
|
||||||
```
|
```
|
||||||
|
|
||||||
### Get informed when the background mode has been deactivated (Android/iOS only)
|
To remove an event listeners:
|
||||||
The `backgroundMode.ondeactivate` interface can be used to get notified when the background mode has been deactivated.
|
|
||||||
|
|
||||||
#### Further informations
|
|
||||||
- Once the mode has been deactivated the app will be paused soon after the callback has been fired.
|
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
cordova.plugins.backgroundMode.ondeactivate = function() {};
|
cordova.plugins.backgroundMode.un('EVENT', function);
|
||||||
```
|
|
||||||
|
|
||||||
### Get informed when the background mode could not been activated
|
|
||||||
The `backgroundMode.onfailure` interface can be used to get notified when the background mode could not be activated (Android/iOS) or enabled (Windows 10).
|
|
||||||
|
|
||||||
The listener has to be a function and takes the following arguments:
|
|
||||||
- errorCode: Error code which describes the error
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
cordova.plugins.backgroundMode.onfailure = function(errorCode) {};
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
## Examples
|
## Android specifics
|
||||||
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.
|
|
||||||
|
### Transit between application states
|
||||||
|
Android allows to programmatically move from foreground to background or vice versa.
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
document.addEventListener('deviceready', function () {
|
cordova.plugins.backgroundMode.moveToBackground();
|
||||||
// Android customization
|
// or
|
||||||
cordova.plugins.backgroundMode.setDefaults({ text:'Doing heavy tasks.'});
|
cordova.plugins.backgroundMode.moveToForeground();
|
||||||
// Enable background mode
|
|
||||||
cordova.plugins.backgroundMode.enable();
|
|
||||||
|
|
||||||
// Called when background mode has been activated
|
|
||||||
cordova.plugins.backgroundMode.onactivate = function () {
|
|
||||||
setTimeout(function () {
|
|
||||||
// Modify the currently displayed notification
|
|
||||||
cordova.plugins.backgroundMode.configure({
|
|
||||||
text:'Running in background for more than 5s now.'
|
|
||||||
});
|
|
||||||
}, 5000);
|
|
||||||
}
|
|
||||||
}, false);
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Back button
|
||||||
|
Override the back button on Android to go to background instead of closing the app.
|
||||||
|
|
||||||
## Platform specifics
|
```javascript
|
||||||
|
cordova.plugins.backgroundMode.overrideBackButton();
|
||||||
|
```
|
||||||
|
|
||||||
### Android customization
|
### 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.
|
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
|
#### Override defaults
|
||||||
The title, ticker, 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 isPublic to true will make the full notification show on a secure lockscreen.
|
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.
|
||||||
|
|
||||||
All of these fields are optional - only override the things you need to.
|
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
cordova.plugins.backgroundMode.setDefaults({
|
cordova.plugins.backgroundMode.setDefaults({
|
||||||
title: String,
|
title: String,
|
||||||
ticker: String,
|
|
||||||
text: String,
|
text: String,
|
||||||
icon: "icon" // this will look for icon.png in platforms/android/res/drawable
|
icon: 'icon' // this will look for icon.png in platforms/android/res/drawable|mipmap
|
||||||
resume: true / false,
|
color: String // hex format like 'F14F4D'
|
||||||
color: "#123456",
|
resume: Boolean,
|
||||||
isPublic: true / false,
|
hidden: Boolean,
|
||||||
|
bigText: Boolean
|
||||||
})
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Modify the currently displayed notification
|
To modify the currently displayed notification
|
||||||
It's also possible to modify the currently displayed notification while in background.
|
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
cordova.plugins.backgroundMode.configure({
|
cordova.plugins.backgroundMode.configure({ ... });
|
||||||
title: String,
|
|
||||||
...
|
|
||||||
})
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
__Note:__ All properties are optional - only override the things you need to.
|
||||||
|
|
||||||
#### Run in background without notification
|
#### 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.
|
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.
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
cordova.plugins.backgroundMode.configure({
|
cordova.plugins.backgroundMode.configure({ silent: true });
|
||||||
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.
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
cordova.plugins.backgroundMode.on('active', function() {
|
||||||
|
cordova.plugins.backgroundMode.disableWebViewOptimizations();
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
__Note:__ Calling the method led to increased resource and power consumption.
|
||||||
|
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
1. Fork it
|
1. Fork it
|
||||||
@ -274,22 +172,14 @@ cordova.plugins.backgroundMode.configure({
|
|||||||
|
|
||||||
This software is released under the [Apache 2.0 License][apache2_license].
|
This software is released under the [Apache 2.0 License][apache2_license].
|
||||||
|
|
||||||
© 2013-2017 appPlant GmbH, Inc. All rights reserved
|
Made with :yum: from Leipzig
|
||||||
|
|
||||||
|
© 2017 [appPlant GmbH][appplant]
|
||||||
|
|
||||||
|
|
||||||
[cordova]: https://cordova.apache.org
|
[cordova]: https://cordova.apache.org
|
||||||
[CLI]: http://cordova.apache.org/docs/en/edge/guide_cli_index.md.html#The%20Command-line%20Interface
|
[CLI]: http://cordova.apache.org/docs/en/edge/guide_cli_index.md.html#The%20Command-line%20Interface
|
||||||
[PGB]: http://docs.build.phonegap.com/en_US/index.html
|
[NPM]: ???
|
||||||
[PGB_plugin]: https://build.phonegap.com/plugins/2056
|
|
||||||
[changelog]: CHANGELOG.md
|
[changelog]: CHANGELOG.md
|
||||||
[enable]: #prevent-the-app-from-going-to-sleep-in-background
|
|
||||||
[disable]: #pause-the-app-while-in-background
|
|
||||||
[is_enabled]: #receive-if-the-background-mode-is-enabled
|
|
||||||
[is_active]: #receive-if-the-background-mode-is-active
|
|
||||||
[android_specifics]: #android-customization
|
|
||||||
[configure]: #modify-the-currently-displayed-notification
|
|
||||||
[onactivate]: #get-informed-when-the-background-mode-has-been-activated
|
|
||||||
[ondeactivate]: #get-informed-when-the-background-mode-has-been-deactivated
|
|
||||||
[onfailure]: #get-informed-when-the-background-mode-could-not-been-activated
|
|
||||||
[apache2_license]: http://opensource.org/licenses/Apache-2.0
|
[apache2_license]: http://opensource.org/licenses/Apache-2.0
|
||||||
[appplant]: http://appplant.de
|
[appplant]: http://appplant.de
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user