mirror of
https://bitbucket.org/TheBosZ/cordova-plugin-run-in-background
synced 2024-12-23 13:57:35 +00:00
Update README
This commit is contained in:
Sebastián Katzer
parent
ffd81e00c2
commit
a60716620a
24
CHANGELOG.md
Normal file
24
CHANGELOG.md
Normal file
@ -0,0 +1,24 @@
|
||||
## ChangeLog
|
||||
#### Version 0.6.0 (not yet released)
|
||||
- [feature:] Android support
|
||||
- [___change___:] Disabled by default
|
||||
- [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<br>
|
||||
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<br>
|
||||
The plugin turns the app into an location tracking app for the time it runs in the background.
|
||||
223
README.md
223
README.md
@ -1,108 +1,158 @@
|
||||
Cordova BackgroundMode-Plugin
|
||||
==============================
|
||||
|
||||
A bunch of background mode plugins for Cordova 3.x.x
|
||||
<p align="right">
|
||||
<a href="https://github.com/katzer/cordova-plugin-background-mode/tree/example">EXAMPLE :point_right:</a>
|
||||
</p>
|
||||
|
||||
by Sebastián Katzer ([github.com/katzer](https://github.com/katzer))
|
||||
Cordova Background Plug-in
|
||||
==========================
|
||||
|
||||
[Cordova][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.
|
||||
|
||||
### Plugin's Purpose
|
||||
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.
|
||||
|
||||
### :bangbang: Store Compliance :bangbang:
|
||||
The plugin focuses on enterprise-only distribution and may not compliant with all public store vendors.
|
||||
|
||||
|
||||
## Overview
|
||||
1. [Supported Platforms](#supported-platforms)
|
||||
2. [Installation](#installation)
|
||||
3. [ChangeLog](#changelog)
|
||||
4. [Using the plugin](#using-the-plugin)
|
||||
5. [Examples](#examples)
|
||||
6. [Platform specifics](#platform-specifics)
|
||||
7. [Quirks](#quirks)
|
||||
|
||||
|
||||
## Supported Platforms
|
||||
- **iOS** (>=5)
|
||||
- **Android**
|
||||
- **WP8**
|
||||
- __iOS__
|
||||
- __Android__
|
||||
- __WP8__
|
||||
|
||||
|
||||
## Adding the Plugin to your project
|
||||
Through the [Command-line Interface](http://cordova.apache.org/docs/en/3.0.0/guide_cli_index.md.html#The%20Command-line%20Interface):
|
||||
## 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].
|
||||
|
||||
### Local development environment
|
||||
From master:
|
||||
```bash
|
||||
# from master:
|
||||
# ~~ from master branch ~~
|
||||
cordova plugin add https://github.com/katzer/cordova-plugin-background-mode.git
|
||||
cordova build
|
||||
|
||||
# last version:
|
||||
cordova plugin add de.appplant.cordova.plugin.background-mode
|
||||
cordova build
|
||||
```
|
||||
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.5.0
|
||||
```
|
||||
|
||||
|
||||
## Removing the Plugin from your project
|
||||
Through the [Command-line Interface](http://cordova.apache.org/docs/en/3.0.0/guide_cli_index.md.html#The%20Command-line%20Interface):
|
||||
```
|
||||
cordova plugin rm de.appplant.cordova.plugin.background-mode
|
||||
```
|
||||
|
||||
|
||||
## PhoneGap Build
|
||||
### PhoneGap Build
|
||||
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" />
|
||||
```
|
||||
or to use this exact version:
|
||||
```
|
||||
```xml
|
||||
<gap:plugin name="de.appplant.cordova.plugin.background-mode" version="0.5.0" />
|
||||
```
|
||||
More informations can be found [here](https://build.phonegap.com/plugins/490).
|
||||
|
||||
More informations can be found [here][PGB_plugin].
|
||||
|
||||
|
||||
## Release Notes
|
||||
#### Version 0.5.0 (13.02.2014)
|
||||
- Added Android support.
|
||||
## ChangeLog
|
||||
#### Version 0.6.0 (not yet released)
|
||||
- [feature:] Android support
|
||||
- [___change___:] Disabled by default
|
||||
- [enhancement:] iOS does not require user permissions, internet connection and geo location anymore.
|
||||
|
||||
#### 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.
|
||||
#### Further informations
|
||||
- The former `plugin.backgroundMode` namespace has been deprecated and will be removed with the next major release.
|
||||
- See [CHANGELOG.md][changelog] to get the full changelog for the plugin.
|
||||
|
||||
#### Version 0.4.0 (10.10.2013)
|
||||
- Added WP8 support<br>
|
||||
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<br>
|
||||
The plugin turns the app into an location tracking app for the time it runs in the background.
|
||||
|
||||
## Using the plugin
|
||||
Simply add the plugin to your project and the app will run while in background.
|
||||
The plugin creates the object ```cordova.plugins.backgroundMode``` with the following methods:
|
||||
|
||||
The plugin creates the object ```window.plugin.backgroundMode``` with two methods:
|
||||
1. [backgroundMode.enable][enable]
|
||||
2. [backgroundMode.disable][disable]
|
||||
2. [backgroundMode.configure][configure]
|
||||
|
||||
### enable()
|
||||
The method enables the background mode. The mode is activated once the app has entered the background and will be deactivated after the app has entered the foreground.<br>
|
||||
Please be aware, to activate the background mode the app needs to be in foreground.
|
||||
### Plugin initialization
|
||||
The plugin and its methods are not available before the *deviceready* event has been fired.
|
||||
|
||||
```javascript
|
||||
document.addEventListener('deviceready', function () {
|
||||
// cordova.plugins.backgroundMode is now available
|
||||
}, false);
|
||||
```
|
||||
|
||||
### Prevent the app from going to sleep in background
|
||||
To prevent the app from being paused while in background, the `backroundMode.enable` interface has to be called.
|
||||
|
||||
#### 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
|
||||
/**
|
||||
* Enables the background mode. The app will not pause while in background.
|
||||
*/
|
||||
window.plugin.backgroundMode.enable();
|
||||
```
|
||||
|
||||
### disable()
|
||||
The method disables the background mode. If the mode is disabled while the app is running in the background, the app will be paused immediately.
|
||||
### Pause the app while in background
|
||||
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
|
||||
/**
|
||||
* Disables the background mode. The app will pause in background as usual.
|
||||
*/
|
||||
window.plugin.backgroundMode.disable();
|
||||
```
|
||||
|
||||
|
||||
## Examples
|
||||
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.
|
||||
|
||||
```javascript
|
||||
document.addEventListener('deviceready', function () {
|
||||
// Enable background mode
|
||||
cordova.plugins.backgroundMode.enable();
|
||||
// Android customization
|
||||
cordova.plugins.backgroundMode.configure({ text:'Doing heavy tasks.'});
|
||||
}, false);
|
||||
```
|
||||
|
||||
|
||||
## Platform specifics
|
||||
|
||||
### Location tracking on iOS
|
||||
**iOS 5-6**<br>
|
||||
The app still runs in background, even if the location service is not actived.
|
||||
### Android Customization
|
||||
|
||||
**iOS 7**<br>
|
||||
The location service needs to be enabled.
|
||||
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.
|
||||
|
||||
**AppStore**<br>
|
||||
Warning: if you use this plugin but your app does not require any persistent geolocation (eg you do nothing with the geolocation values), your app will be rejected by the AppStore review team (there is at least one predecedent).
|
||||
The title, ticker and text for that notification can be customized in the following way at any time:
|
||||
|
||||
### Optimization on WP8
|
||||
```javascript
|
||||
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.
|
||||
|
||||
```javascript
|
||||
cordova.plugins.backgroundMode.configure({
|
||||
resume: false
|
||||
})
|
||||
```
|
||||
|
||||
|
||||
### WP8 Optimization
|
||||
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:
|
||||
|
||||
```c#
|
||||
// MainPage.xaml.cs
|
||||
|
||||
@ -131,34 +181,26 @@ namespace your.own.namespace
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Quirks
|
||||
|
||||
### The app crashes on iOS
|
||||
If the app crashes after installing the plugin, make sure that your `*-Info.plist` is valid.
|
||||
Do to some bugs in cordova or Plugman please reset all occurences like
|
||||
### iOS Crash
|
||||
If the app crashes after installing the plugin, make sure that your `*-Info.plist` is valid and reset all occurences of blank strings
|
||||
|
||||
```xml
|
||||
<key>NSMainNibFile</key>
|
||||
<string>
|
||||
|
||||
</string>
|
||||
```
|
||||
|
||||
to
|
||||
|
||||
```xml
|
||||
<key>NSMainNibFile</key>
|
||||
<string></string>
|
||||
```
|
||||
|
||||
### TypeError: Cannot read property 'currentVersion' of null
|
||||
The error occurs while trying to install the plugin from master. As a workaround the **version.bat** script has to be renamed to **version**.
|
||||
|
||||
On Mac or Linux
|
||||
```
|
||||
mv platforms/wp8/cordova/version.bat platforms/wp8/cordova/version
|
||||
```
|
||||
On Windows
|
||||
```
|
||||
ren platforms\wp8\cordova\version.bat platforms\wp8\cordova\version
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
@ -168,6 +210,21 @@ ren platforms\wp8\cordova\version.bat platforms\wp8\cordova\version
|
||||
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](http://opensource.org/licenses/Apache-2.0).
|
||||
This software is released under the [Apache 2.0 License][apache2_license].
|
||||
|
||||
© 2013-2014 appPlant UG, Inc. All rights reserved
|
||||
|
||||
|
||||
[cordova]: https://cordova.apache.org
|
||||
[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
|
||||
[PGB_plugin]: https://build.phonegap.com/plugins/490
|
||||
[changelog]: CHANGELOG.md
|
||||
[enable]: #prevent-the-app-from-going-to-sleep-in-background
|
||||
[disable]: #pause-the-app-while-in-background
|
||||
[configure]: #android-customization
|
||||
[apache2_license]: http://opensource.org/licenses/Apache-2.0
|
||||
[appplant]: http://appplant.de
|
||||
|
||||
12
plugin.xml
12
plugin.xml
@ -7,9 +7,14 @@
|
||||
|
||||
<name>BackgroundMode</name>
|
||||
|
||||
<description>A bunch of background mode plugins for Cordova 3.x.x</description>
|
||||
<description>
|
||||
Cordova plugin to prevent the app from going to sleep in background.
|
||||
</description>
|
||||
|
||||
<repo>https://github.com/katzer/cordova-plugin-background-mode.git</repo>
|
||||
<keywords>background, ios, windows phone 8, wp8, android</keywords>
|
||||
|
||||
<keywords>appplant, background, ios, wp8, android</keywords>
|
||||
|
||||
<license>Apache 2.0</license>
|
||||
|
||||
<author>Sebastián Katzer</author>
|
||||
@ -34,8 +39,7 @@
|
||||
<platform name="ios">
|
||||
<config-file target="config.xml" parent="/*">
|
||||
<feature name="BackgroundMode">
|
||||
<param name="ios-package" value="APPBackgroundMode" onload="true" />
|
||||
<param name="onload" value="true" />
|
||||
<param name="ios-package" value="APPBackgroundMode" />
|
||||
</feature>
|
||||
</config-file>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user