cordova-plugin-run-in-backg.../README.md

171 lines
5.1 KiB
Markdown
Raw Normal View History

2013-10-08 08:51:17 +00:00
Cordova BackgroundMode-Plugin
2013-10-08 08:28:55 +00:00
==============================
2013-10-08 08:51:17 +00:00
A bunch of background mode plugins for Cordova 3.x.x
by Sebastián Katzer ([github.com/katzer](https://github.com/katzer))
2014-02-26 00:15:20 +00:00
2013-10-08 08:51:17 +00:00
## Supported Platforms
2013-10-08 14:39:40 +00:00
- **iOS** (>=5)
2014-02-13 13:22:21 +00:00
- **Android**
2013-10-10 10:38:32 +00:00
- **WP8**
2013-10-08 08:51:17 +00:00
2014-02-26 00:15:20 +00:00
2013-10-08 08:51:17 +00:00
## 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):
2014-02-13 13:15:12 +00:00
```bash
# from master:
2013-10-08 08:51:17 +00:00
cordova plugin add https://github.com/katzer/cordova-plugin-background-mode.git
2014-02-26 00:15:20 +00:00
cordova build
2014-02-13 13:15:12 +00:00
# last version:
cordova plugin add de.appplant.cordova.plugin.background-mode
2014-02-26 00:15:20 +00:00
cordova build
2013-10-08 08:51:17 +00:00
```
2014-02-26 00:15:20 +00:00
2013-10-08 08:51:17 +00:00
## 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
```
2014-02-26 00:15:20 +00:00
## 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:
```
<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).
2013-10-08 08:51:17 +00:00
## Release Notes
2014-02-13 13:22:21 +00:00
#### Version 0.5.0 (13.02.2014)
- Added Android support.
2014-02-13 13:15:12 +00:00
#### Version 0.4.1 (13.02.2014)
2013-12-09 12:36:43 +00:00
- Release under the Apache 2.0 license.
- [enhancement:] Location tracking is only activated on WP8 if the location service is available.
2014-02-13 13:15:12 +00:00
- [bigfix:] Nullpointer exception on WP8.
2013-10-10 10:42:33 +00:00
#### Version 0.4.0 (10.10.2013)
2013-10-10 10:38:32 +00:00
- Added WP8 support<br>
The plugin turns the app into an location tracking app *(for the time it runs in the background)*.
2013-10-09 12:54:23 +00:00
#### Version 0.2.1 (09.10.2013)
2013-10-09 12:16:00 +00:00
- Added js interface to manually enable/disable the background mode.
2013-10-08 14:41:24 +00:00
#### Version 0.2.0 (08.10.2013)
2013-10-08 14:39:40 +00:00
- Added iOS (>= 5) support<br>
2013-10-08 14:32:51 +00:00
The plugin turns the app into an location tracking app for the time it runs in the background.
2013-10-08 08:51:17 +00:00
## Using the plugin
2013-10-09 12:54:23 +00:00
Simply add the plugin to your project and the app will run while in background.
2013-10-09 12:16:00 +00:00
2013-10-10 10:19:50 +00:00
The plugin creates the object ```window.plugin.backgroundMode``` with two methods:
2013-10-09 12:16:00 +00:00
### 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.
2013-10-08 14:32:10 +00:00
2013-10-09 12:16:00 +00:00
```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.
```javascript
/**
* Disables the background mode. The app will pause in background as usual.
*/
window.plugin.backgroundMode.disable();
```
2013-12-01 12:49:36 +00:00
## Platform specifics
2013-10-10 10:38:32 +00:00
2013-12-01 12:49:36 +00:00
### Location tracking on iOS
2013-10-10 10:38:32 +00:00
**iOS 5-6**<br>
The app still runs in background, even if the location service is not actived.
**iOS 7**<br>
The location service needs to be enabled.
2013-12-01 12:49:36 +00:00
### Optimization on WP8
2013-10-10 10:38:32 +00:00
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#
2013-12-01 12:49:36 +00:00
// MainPage.xaml.cs
2013-10-10 10:38:32 +00:00
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();
}
}
}
```
2013-12-01 12:49:36 +00:00
## 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
```xml
<key>NSMainNibFile</key>
<string>
</string>
```
to
```xml
<key>NSMainNibFile</key>
<string></string>
```
### TypeError: Cannot read property 'currentVersion' of null
2014-02-13 13:15:12 +00:00
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
```
2013-12-01 12:57:36 +00:00
## 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
2013-12-09 12:36:43 +00:00
This software is released under the [Apache 2.0 License](http://opensource.org/licenses/Apache-2.0).