// Do your HTTP request here to POST location to your server.
//
/**
//
* This would be your own callback for Ajax-requests after POSTing background geolocation to your server.
* eg:
* $.post({url: url, success: yourAjaxCallback});
*/
var yourAjaxCallback = function(response) {
////
// IMPORTANT: You must execute the #finish, providing the taskId provided to callbackFn above in order to inform the native plugin that you're finished,
// and the background-task may be completed. You must do this regardless if your HTTP request is successful or not.
// IF YOU DON'T, ios will CRASH YOUR APP for spending too much time in the background.
//
//
bgGeo.finish(taskId);
};
yourAjaxCallback.call(this);
yourAjaxCallback.call(this);
};
};
...
@@ -79,7 +91,7 @@ function onDeviceReady() {
...
@@ -79,7 +91,7 @@ function onDeviceReady() {
// BackgroundGeoLocation is highly configurable.
// BackgroundGeoLocation is highly configurable.
bgGeo.configure(callbackFn, failureFn, {
bgGeo.configure(callbackFn, failureFn, {
debug: true, // <-- enable this hear sounds for background-geolocation life-cycle.
// Geolocation config
desiredAccuracy: 0,
desiredAccuracy: 0,
stationaryRadius: 50,
stationaryRadius: 50,
distanceFilter: 50,
distanceFilter: 50,
...
@@ -89,16 +101,20 @@ function onDeviceReady() {
...
@@ -89,16 +101,20 @@ function onDeviceReady() {
fastestLocationUpdateInterval: 5000,
fastestLocationUpdateInterval: 5000,
activityRecognitionInterval: 10000,
activityRecognitionInterval: 10000,
stopTimeout: 0,
stopTimeout: 0,
forceReload: true, // <-- [Android] If the user closes the app **while location-tracking is started** , reboot app (WARNING: possibly distruptive to user)
stopOnTerminate: false, // <-- [Android] Allow the background-service to run headless when user closes the app.
startOnBoot: true, // <-- [Android] Auto start background-service in headless mode when device is powered-up.
activityType: 'AutomotiveNavigation',
activityType: 'AutomotiveNavigation',
/**
* HTTP Feature: set an url to allow the native background service to POST locations to your server
// Application config
*/
debug: true, // <-- enable this hear sounds for background-geolocation life-cycle.
forceReloadOnLocationChange: false, // <-- [Android] If the user closes the app **while location-tracking is started** , reboot app when a new location is recorded (WARNING: possibly distruptive to user)
forceReloadOnMotionChange: false, // <-- [Android] If the user closes the app **while location-tracking is started** , reboot app when device changes stationary-state (stationary->moving or vice-versa) --WARNING: possibly distruptive to user)
forceReloadOnGeofence: false, // <-- [Android] If the user closes the app **while location-tracking is started** , reboot app when a geofence crossing occurs --WARNING: possibly distruptive to user)
stopOnTerminate: false, // <-- [Android] Allow the background-service to run headless when user closes the app.
startOnBoot: true, // <-- [Android] Auto start background-service in headless mode when device is powered-up.
batchSync: false, // <-- [Default: false] Set true to sync locations to server in 1 HTTP request.
batchSync: true, // <-- [Default: false] Set true to sync locations to server in a single HTTP request.
autoSync: true,// <-- [Default: true] Set true to sync each location to server as it arrives.
autoSync: true,// <-- [Default: true] Set true to sync each location to server as it arrives.
maxDaysToPersist: 1, // <-- Maximum days to persist a location in plugin's SQLite database when HTTP fails
maxDaysToPersist: 1, // <-- Maximum days to persist a location in plugin's SQLite database when HTTP fails
headers: {
headers: {
"X-FOO": "bar"
"X-FOO": "bar"
...
@@ -118,11 +134,22 @@ function onDeviceReady() {
...
@@ -118,11 +134,22 @@ function onDeviceReady() {
```
```
## Example Application
## Advanced Sample Application for Field-testing
A fully-featured [SampleApp](https://github.com/christocracy/cordova-background-geolocation-SampleApp) is available in its own public repo. After first cloning that repo, follow the installation instructions in the **README** there. This SampleApp includes a settings-screen allowing you to quickly experiment with all the different settings available for each platform.
This plugin itself hosts a more rudimentary SampleApp in ```example/SampleApp``` folder. This SampleApp should be used for reference only -- for actual field-testing, please use the **more advanced**[SampleApp](https://github.com/christocracy/cordova-background-geolocation-SampleApp) above.
This SampleApp contains no plugins so you must first start by adding its required plugins (most importantly, this one). **NOTE** In order to use the SampleApp, it's important to make a copy of it **outside** of the plugin itself.
![SampleApp](/android-sample-app.png"SampleApp")
![SampleApp](/android-sample-app.png"SampleApp")
This plugin hosts a SampleApp in ```example/SampleApp``` folder. This SampleApp contains no plugins so you must first start by adding its required plugins (most importantly, this one). **NOTE** In order to use the SampleApp, it's important to make a copy of it outside of the plugin itself.
Configures the plugin's parameters (@see following [Config](https://github.com/christocracy/cordova-background-geolocation/blob/edge/README.md#config) section for accepted ```config``` params. The ```locationCallback``` will be executed each time a new Geolocation is recorded and provided with the following parameters:
Configures the plugin's parameters (@see following [Config](https://github.com/christocracy/cordova-background-geolocation/blob/edge/README.md#config) section for accepted ```config``` params. The ```locationCallback``` will be executed each time a new Geolocation is recorded.
######@param {Object} location The Location data
######@param {Integer} taskId The taskId used to send to bgGeo.finish(taskId) in order to signal completion of your callbackFn
#####`setConfig(successFn, failureFn, config)`
```
bgGeo.configure(function(location, taskId) {
try {
var coords = location.coords,
timestamp = location.timestamp
latitude = coords.latitude,
longitude = coords.longitude,
speed = coords.speed;
console.log("A location has arrived:", timestamp, latitude, longitude, speed);
} catch(e) {
console.error("An error occurred in my application code", e);
}
// The plugin runs your callback in a background-thread:
// you MUST signal to the native plugin when your callback is finished so it can halt the thread.
// IF YOU DON'T, iOS WILL KILL YOUR APP
bgGeo.finish(taskId);
}, failureFn, {
distanceFilter: 50,
desiredAccuracy: 0,
stationaryRadius: 25
});
```
####`setConfig(successFn, failureFn, config)`
Reconfigure plugin's configuration (@see followign ##Config## section for accepted ```config``` params. **NOTE** The plugin will continue to send recorded Geolocation to the ```locationCallback``` you provided to ```configure``` method -- use this method only to change configuration params (eg: ```distanceFilter```, ```stationaryRadius```, etc).
Reconfigure plugin's configuration (@see followign ##Config## section for accepted ```config``` params. **NOTE** The plugin will continue to send recorded Geolocation to the ```locationCallback``` you provided to ```configure``` method -- use this method only to change configuration params (eg: ```distanceFilter```, ```stationaryRadius```, etc).
Retrieves the current position. This method instructs the native code to fetch exactly one location using maximum power & accuracy. **NOTE:** The plugin **MUST** be enabled via `#start` to use this method (otherwise the plugin will call your `failureFn` with a status-code `401` (UNAUTHORIZED). The native code will persist the fetched location to its SQLite database just as any other location in addition to POSTing to your configured `#url` (if you've enabled the HTTP features). In addition to your supplied `callbackFn`, the plugin will also execute the `callback` provided to `#configure`. Your provided `successFn` will be executed with the same signature as that provided to `#configure`:
######@param {Object} location The Location data
######@param {Integer} taskId The taskId used to send to bgGeo.finish(taskId) in order to signal completion of your callbackFn
// This location is already persisted to plugin’s SQLite db.
// If you’ve configured #autoSync: true, the HTTP POST has already started.
console.log(“- Current position received: “, location);
bgGeo.finish(taskId);
});
```
####`changePace(enabled, successFn, failureFn)`
Initiate or cancel immediate background tracking. When set to ```true```, the plugin will begin aggressively tracking the devices Geolocation, bypassing stationary monitoring. If you were making a "Jogging" application, this would be your [Start Workout] button to immediately begin GPS tracking. Send ```false``` to disable aggressive GPS monitoring and return to stationary-monitoring mode.
Initiate or cancel immediate background tracking. When set to ```true```, the plugin will begin aggressively tracking the devices Geolocation, bypassing stationary monitoring. If you were making a "Jogging" application, this would be your [Start Workout] button to immediately begin GPS tracking. Send ```false``` to disable aggressive GPS monitoring and return to stationary-monitoring mode.
Your ```callbackFn``` will be executed each time the device has entered stationary-monitoring mode. The ```callbackFn``` will be provided with a ```Geolocation``` object as the 1st param, with the usual params (```latitude, longitude, accuracy, speed, bearing, altitude```).
Your ```callbackFn``` will be executed each time the device has changed-state between **MOVING** or **STATIONARY**. The ```callbackFn``` will be provided with a ```Location``` object as the 1st param, with the usual params (```latitude, longitude, accuracy, speed, bearing, altitude```), in addition to a ```taskId``` used to signal that your callback is finished.
######@param {Boolean} isMoving `false` if entered **STATIONARY** mode; `true` if entered **MOVING** mode.
######@param {Object} location The location at the state-change.
######@param {Integer} taskId The taskId used to send to bgGeo.finish(taskId) in order to signal completion of your callbackFn
console.log('Device has just started MOVING', location);
} else {
console.log('Device has just STOPPED', location);
}
bgGeo.finish(taskId);
})
```
####`onStationary(callbackFn, failureFn)`
**DEPRECATED**— Use [onMotionChange](https://github.com/christocracy/cordova-background-geolocation/tree/trigger-activities#onmotionchangecallbackfn-failurefn) instead.
Your ```callbackFn``` will be executed each time the device has entered stationary-monitoring mode. The ```callbackFn``` will be provided with a ```Location``` object as the 1st param, with the usual params (```latitude, longitude, accuracy, speed, bearing, altitude```), in addition to a ```taskId``` used to signal that your callback is finished.
######@param {Object} location The Location data
######@param {Integer} taskId The taskId used to send to bgGeo.finish(taskId) in order to signal completion of your callbackFn
```
bgGeo.onStationary(function(location, taskId) {
try {
console.log('- Device is stopped: ', location.latitude, location.longitude);
} catch(e) {
console.error('An error occurred in my application code', e);
}
// The plugin runs your callback in a background-thread:
// you MUST signal to the native plugin when your callback is finished so it can halt the thread.
// IF YOU DON'T, iOS WILL KILL YOUR APP
bgGeo.finish(taskId);
});
```
####`addGeofence(config, callbackFn, failureFn)`
Adds a geofence to be monitored by the native plugin. Monitoring of a geofence is halted after a crossing occurs. The `config` object accepts the following params.
######@config {String} identifier The name of your geofence, eg: "Home", "Office"
######@config {Float} radius The radius (meters) of the geofence. In practice, you should make this >= 100 meters.
######@config {Float} latitude Latitude of the center-point of the circular geofence.
######@config {Float} longitude Longitude of the center-point of the circular geofence.
######@config {Boolean} notifyOnExit Whether to listen to EXIT events
######@config {Boolean} notifyOnEntry Whether to listen to ENTER events
######@config {Function} failureFn failed to remove geofence
```
bgGeo.removeGeofence("Home", function() {
console.log("Successfully removed geofence");
}, function(error) {
console.warn("Failed to remove geofence", error);
});
```
####`getGeofences(callbackFn, failureFn)`
Fetch the list of monitored geofences. Your `callbackFn` will be provided with an `Array` of geofences. If there are no geofences being monitored, you'll receive an empty Array `[]`.
```
```
bgGeo.onStationary(function(location) {
bgGeo.getGeofences(function(geofences) {
console.log('- Device is stopped: ', location.latitude, location.longitude);
console.warn("Failed to fetch geofences from server");
});
```
####`onGeofence(callbackFn)`
Adds a geofence event-listener. Your supplied callback will be called when any monitored geofence crossing occurs. The `callbackFn` will be provided the following parameters:
######@param {Object} params. This object contains 2 keys: `@param {String} identifier` and `@param {String} action [ENTER|EXIT]`.
######@param {Integer} taskId The background taskId which you must send back to the native plugin via `bgGeo.finish(taskId)` in order to signal that your callback is complete.
```
bgGeo.onGeofence(function(params, taskId) {
try {
console.log('A geofence has been crossed: ', params.identifier);
console.log('ENTER or EXIT?: ', params.action);
} catch(e) {
console.error('An error occurred in my application code', e);
}
// The plugin runs your callback in a background-thread:
// you MUST signal to the native plugin when your callback is finished so it can halt the thread.
// IF YOU DON'T, iOS WILL KILL YOUR APP
bgGeo.finish(taskId);
});
});
```
```
#####`getLocations(callbackFn, failureFn)`
####`getLocations(callbackFn, failureFn)`
Fetch all the locations currently stored in native plugin's SQLite database. Your ```callbackFn`` will receive an ```Array``` of locations in the 1st parameter. Eg:
Fetch all the locations currently stored in native plugin's SQLite database. Your ```callbackFn`` will receive an ```Array``` of locations in the 1st parameter. Eg:
The `callbackFn` will be executed with following params:
######@param {Array} locations. The list of locations stored in SQLite database.
######@param {Integer} taskId The background taskId which you must send back to the native plugin via `bgGeo.finish(taskId)` in order to signal the end of your background thread.
```
```
bgGeo.getLocations(function(locations) {
bgGeo.getLocations(function(locations, taskId) {
console.log("locations: ", locations);
try {
console.log("locations: ", locations);
} catch(e) {
console.error("An error occurred in my application code");
}
bgGeo.finish(taskId);
});
});
```
```
#####`sync(callbackFn, failureFn)`
####`sync(callbackFn, failureFn)`
If the plugin is configured for HTTP with an ```#url``` and ```#autoSync: false```, this method will initiate POSTing the locations currently stored in the native SQLite database to your configured ```#url```. All records in the database will be DELETED. If you configured ```batchSync: true```, all the locations will be sent to your server in a single HTTP POST request, otherwise the plugin will create execute an HTTP post for **each** location in the database (REST-style). Your ```callbackFn``` will be executed and provided with an Array of all the locations from the SQLite database. If the plugin failed to sync to your server (possibly because of no network connection), the ```failureFn``` will be called with an ```errorMessage```. If you are **not** using the HTTP features, ```sync``` is the only way to clear the native SQLite datbase. Eg:
If the plugin is configured for HTTP with an ```#url``` and ```#autoSync: false```, this method will initiate POSTing the locations currently stored in the native SQLite database to your configured ```#url```. All records in the database will be DELETED. If you configured ```batchSync: true```, all the locations will be sent to your server in a single HTTP POST request, otherwise the plugin will create execute an HTTP post for **each** location in the database (REST-style). Your ```callbackFn``` will be executed and provided with an Array of all the locations from the SQLite database. If you configured the plugin for HTTP (by configuring an `#url`, your `callbackFn` will be executed after the HTTP request(s) have completed. If the plugin failed to sync to your server (possibly because of no network connection), the ```failureFn``` will be called with an ```errorMessage```. If you are **not** using the HTTP features, ```sync``` is the only way to clear the native SQLite datbase. Eg:
Your callback will be provided with the following params
######@param {Array} locations. The list of locations stored in SQLite database.
######@param {Integer} taskId The background taskId which you must send back to the native plugin via `bgGeo.finish(taskId)` in order to signal the end of your background thread.
```
```
bgGeo.sync(function(locations) {
bgGeo.sync(function(locations, taskId) {
// Here are all the locations from the database. The database is now EMPTY.
try {
console.log('synced locations: ', locations);
// Here are all the locations from the database. The database is now EMPTY.
console.log('synced locations: ', locations);
} catch(e) {
console.error('An error occurred in my application code', e);
}
// Be sure to call finish(taskId) in order to signal the end of the background-thread.
bgGeo.finish(taskId);
}, function(errorMessage) {
}, function(errorMessage) {
console.warn('Sync FAILURE: ', errorMessage);
console.warn('Sync FAILURE: ', errorMessage);
});
});
```
```
#####`getOdometer(callbackFn, failureFn)`
####`getOdometer(callbackFn, failureFn)`
The plugin constantly tracks distance travelled. To fetch the current **odometer** reading:
The plugin constantly tracks distance travelled. To fetch the current **odometer** reading:
...
@@ -271,15 +473,28 @@ The plugin constantly tracks distance travelled. To fetch the current **odomete
...
@@ -271,15 +473,28 @@ The plugin constantly tracks distance travelled. To fetch the current **odomete
});
});
```
```
#####`resetOdometer(callbackFn, failureFn)`
####`resetOdometer(callbackFn, failureFn)`
Reset the **odometer** to zero. The plugin never automatically resets the odometer so it's up to you to reset it as desired.
Reset the **odometer** to zero. The plugin never automatically resets the odometer so it's up to you to reset it as desired.
####`playSound(soundId)`
Here's a fun one. The plugin can play a number of OS system sounds for each platform. For [IOS](http://iphonedevwiki.net/index.php/AudioServices) and [Android](http://developer.android.com/reference/android/media/ToneGenerator.html). I offer this API as-is, it's up to you to figure out how this works.
```
// A soundId iOS recognizes
bgGeo.playSound(1303);
// An Android soundId
bgGeo.playSound(90);
```
## Config
## Config
Use the following config-parameters with the #configure method:
Use the following config-parameters with the #configure method:
#####`@param {Boolean} debug`
####`@param {Boolean} debug`
When enabled, the plugin will emit sounds for life-cycle events of background-geolocation! **NOTE iOS**: In addition, you must manually enable the *Audio and Airplay* background mode in *Background Capabilities* to hear these debugging sounds.
When enabled, the plugin will emit sounds for life-cycle events of background-geolocation! **NOTE iOS**: In addition, you must manually enable the *Audio and Airplay* background mode in *Background Capabilities* to hear these debugging sounds.
...
@@ -291,18 +506,18 @@ When enabled, the plugin will emit sounds for life-cycle events of background-ge
...
@@ -291,18 +506,18 @@ When enabled, the plugin will emit sounds for life-cycle events of background-ge
#####`@param {Integer} desiredAccuracy [0, 10, 100, 1000] in meters`
####`@param {Integer} desiredAccuracy [0, 10, 100, 1000] in meters`
Specify the desired-accuracy of the geolocation system with 1 of 4 values, ```0, 10, 100, 1000``` where ```0``` means HIGHEST POWER, HIGHEST ACCURACY and ```1000``` means LOWEST POWER, LOWEST ACCURACY
Specify the desired-accuracy of the geolocation system with 1 of 4 values, ```0, 10, 100, 1000``` where ```0``` means HIGHEST POWER, HIGHEST ACCURACY and ```1000``` means LOWEST POWER, LOWEST ACCURACY
When stopped, the minimum distance the device must move beyond the stationary location for aggressive background-tracking to engage. Note, since the plugin uses iOS significant-changes API, the plugin cannot detect the exact moment the device moves out of the stationary-radius. In normal conditions, it can take as much as 3 city-blocks to 1/2 km before staionary-region exit is detected.
When stopped, the minimum distance the device must move beyond the stationary location for aggressive background-tracking to engage. Note, since the plugin uses iOS significant-changes API, the plugin cannot detect the exact moment the device moves out of the stationary-radius. In normal conditions, it can take as much as 3 city-blocks to 1/2 km before staionary-region exit is detected.
#####`@param {Integer} distanceFilter`
####`@param {Integer} distanceFilter`
The minimum distance (measured in meters) a device must move horizontally before an update event is generated. @see [Apple docs](https://developer.apple.com/library/ios/documentation/CoreLocation/Reference/CLLocationManager_Class/CLLocationManager/CLLocationManager.html#//apple_ref/occ/instp/CLLocationManager/distanceFilter). However, #distanceFilter is elastically auto-calculated by the plugin: When speed increases, #distanceFilter increases; when speed decreases, so does distanceFilter.
The minimum distance (measured in meters) a device must move horizontally before an update event is generated. @see [Apple docs](https://developer.apple.com/library/ios/documentation/CoreLocation/Reference/CLLocationManager_Class/CLLocationManager/CLLocationManager.html#//apple_ref/occ/instp/CLLocationManager/distanceFilter). However, #distanceFilter is elastically auto-calculated by the plugin: When speed increases, #distanceFilter increases; when speed decreases, so does distanceFilter.
...
@@ -336,14 +551,14 @@ Compare now background-geolocation in the scope of a city. In this image, the l
...
@@ -336,14 +551,14 @@ Compare now background-geolocation in the scope of a city. In this image, the l
#####`@param {Boolean} stopOnTerminate`
####`@param {Boolean} stopOnTerminate`
Enable this in order to force a stop() when the application terminated (e.g. on iOS, double-tap home button, swipe away the app). On Android, ```stopOnTerminate: false``` will cause the plugin to operate as a headless background-service (in this case, you should configure an #url in order for the background-service to send the location to your server)
Enable this in order to force a stop() when the application terminated (e.g. on iOS, double-tap home button, swipe away the app). On Android, ```stopOnTerminate: false``` will cause the plugin to operate as a headless background-service (in this case, you should configure an #url in order for the background-service to send the location to your server)
#####`@param {Boolean} stopAfterElapsedMinutes`
####`@param {Boolean} stopAfterElapsedMinutes`
The plugin can optionally auto-stop monitoring location when some number of minutes elapse after being the #start method was called.
The plugin can optionally auto-stop monitoring location when some number of minutes elapse after being the #start method was called.
#### In-Plugin SQLite Storage
### In-Plugin SQLite Storage
The plugin will cache **every** recorded geolocation to its internal SQLite database -- when you sync the locations and your server responds with HTTP ```200, 201 or 204```, the plugin will **DELETE** the stored location from cache. The plugin has a cache-pruning feature with ```@config {Integer} maxDaysToPersist``` -- If the plugin hasn't successfully synced these these records in the database before ```maxDaysToPersist``` expires, the plugin will give up and those geolocation records will be pruned from the database.
The plugin will cache **every** recorded geolocation to its internal SQLite database -- when you sync the locations and your server responds with HTTP ```200, 201 or 204```, the plugin will **DELETE** the stored location from cache. The plugin has a cache-pruning feature with ```@config {Integer} maxDaysToPersist``` -- If the plugin hasn't successfully synced these these records in the database before ```maxDaysToPersist``` expires, the plugin will give up and those geolocation records will be pruned from the database.
...
@@ -356,34 +571,36 @@ If you **don't** configure the optional HTTP feature, the only way to delete the
...
@@ -356,34 +571,36 @@ If you **don't** configure the optional HTTP feature, the only way to delete the
});
});
```
```
#### HTTP Features
### HTTP Features
#####`@param {String} url`
####`@param {String} url`
Your server url where you wish to HTTP POST location data to.
Your server url where you wish to HTTP POST location data to.
#####`@param {String} batchSync [false]`
####`@param {String} batchSync [false]`
Default is ```false```. If you've enabled HTTP feature by configuring an ```#url```, ```batchSync: true``` will POST all the locations currently stored in native SQLite datbase to your server in a single HTTP POST request. With ```batchSync: false```, an HTTP POST request will be initiated for **each** location in database.
Default is ```false```. If you've enabled HTTP feature by configuring an ```#url```, ```batchSync: true``` will POST all the locations currently stored in native SQLite datbase to your server in a single HTTP POST request. With ```batchSync: false```, an HTTP POST request will be initiated for **each** location in database.
#####`@param {String} autoSync [true]`
####`@param {String} autoSync [true]`
Default is ```true```. If you've enabeld HTTP feature by configuring an ```#url```, the plugin will attempt to HTTP POST each location to your server **as it is recorded**. If you set ```autoSync: false```, it's up to you to **manually** execute the ```#sync``` method to initate the HTTP POST (**NOTE** The plugin will continue to persist **every** recorded location in the SQLite database until you execute ```#sync```).
Default is ```true```. If you've enabeld HTTP feature by configuring an ```#url```, the plugin will attempt to HTTP POST each location to your server **as it is recorded**. If you set ```autoSync: false```, it's up to you to **manually** execute the ```#sync``` method to initate the HTTP POST (**NOTE** The plugin will continue to persist **every** recorded location in the SQLite database until you execute ```#sync```).
#####`@param {Object} params`
####`@param {Object} params`
Optional HTTP params sent along in HTTP request to above ```#url```.
Optional HTTP params sent along in HTTP request to above ```#url```.
#####`@param {Object} headers`
####`@param {Object} headers`
Optional HTTP params sent along in HTTP request to above ```#url```.
Optional HTTP params sent along in HTTP request to above ```#url```.
#####`@param {Integer} maxDaysToPersist`
####`@param {Integer} maxDaysToPersist`
Maximum number of days to store a geolocation in plugin's SQLite database when your server fails to respond with ```HTTP 200 OK```. The plugin will continue attempting to sync with your server until ```maxDaysToPersist``` when it will give up and remove the location from the database.
Maximum number of days to store a geolocation in plugin's SQLite database when your server fails to respond with ```HTTP 200 OK```. The plugin will continue attempting to sync with your server until ```maxDaysToPersist``` when it will give up and remove the location from the database.
Both iOS and Android can send the Geolocation to your server simply by configuring an ```#url``` in addition to optional ```#headers``` and ```#params```. This is the preferred way to send the Geolocation to your server, rather than doing it yourself with Ajax in your javascript.
Both iOS and Android can send the Geolocation to your server simply by configuring an ```#url``` in addition to optional ```#headers``` and ```#params```. This is the preferred way to send the Geolocation to your server, rather than doing it yourself with Ajax in your javascript.
the desired time between activity detections. Larger values will result in fewer activity detections while improving battery life. A value of 0 will result in activity detections at the fastest possible rate.
the desired time between activity detections. Larger values will result in fewer activity detections while improving battery life. A value of 0 will result in activity detections at the fastest possible rate.
Each activity-recognition-result returned by the API is tagged with a "confidence" level expressed as a %. You can set your desired confidence to trigger a state-change. Defaults to `80`.
####`@param {String} triggerActivities`
These are the comma-delimited list of [activity-names](https://developers.google.com/android/reference/com/google/android/gms/location/DetectedActivity) returned by the `ActivityRecognition` API which will trigger a state-change from **stationary** to **moving**. By default, this list is set to all five **moving-states**: `"in_vehicle, on_bicycle, on_foot, running, walking"`. If you wish, you could configure the plugin to only engage **moving-mode** for vehicles by providing only `"in_vehicle"`.
####`@param {Integer minutes} stopTimeout`
The number of miutes to wait before turning off the GPS after the ActivityRecognition System (ARS) detects the device is ```STILL``` (defaults to 0, no timeout). If you don't set a value, the plugin is eager to turn off the GPS ASAP. An example use-case for this configuration is to delay GPS OFF while in a car waiting at a traffic light.
The number of miutes to wait before turning off the GPS after the ActivityRecognition System (ARS) detects the device is ```STILL``` (defaults to 0, no timeout). If you don't set a value, the plugin is eager to turn off the GPS ASAP. An example use-case for this configuration is to delay GPS OFF while in a car waiting at a traffic light.
#####`@param {Boolean} forceReload`
####`@param {Boolean} forceReloadOnMotionChange`
If the user closes the application while the background-tracking has been started, location-tracking will continue on if ```stopOnTerminate: false```. You may choose to force the foreground application to reload (since this is where your Javascript runs). `forceReloadOnMotionChange: true` will reload the app only when a state-change occurs from **stationary -> moving** or vice-versa. (**WARNING** possibly disruptive to user).
If the user closes the application while the background-tracking has been started, location-tracking will continue on if ```stopOnTerminate: false```. You may choose to force the foreground application to reload (since this is where your Javascript runs) by setting ```foreceReload: true```. This will guarantee that locations are always sent to your Javascript callback (**WARNING** possibly disruptive to user).
If the user closes the application while the background-tracking has been started, location-tracking will continue on if ```stopOnTerminate: false```. You may choose to force the foreground application to reload (since this is where your Javascript runs). `forceReloadOnLocationChange: true` will reload the app when a new location is recorded.
####`@param {Boolean} forceReloadOnGeofence`
If the user closes the application while the background-tracking has been started, location-tracking will continue on if ```stopOnTerminate: false```. You may choose to force the foreground application to reload (since this is where your Javascript runs). `forceReloadOnGeolocation: true` will reload the app only when a geofence crossing event has occurred.
####`@param {Boolean} startOnBoot`
Set to ```true``` to start the background-service whenever the device boots. Unless you configure the plugin to ```forceReload``` (ie: boot your app), you should configure the plugin's HTTP features so it can POST to your server in "headless" mode.
Set to ```true``` to start the background-service whenever the device boots. Unless you configure the plugin to ```forceReload``` (ie: boot your app), you should configure the plugin's HTTP features so it can POST to your server in "headless" mode.
...
@@ -496,21 +729,99 @@ Set to ```true``` to start the background-service whenever the device boots. Un
...
@@ -496,21 +729,99 @@ Set to ```true``` to start the background-service whenever the device boots. Un
### iOS Config
### iOS Config
#####`@param {Boolean} disableElasticity [false]`
####`@param {Boolean} disableElasticity [false]`
Defaults to ```false```. Set ```true``` to disable automatic speed-based ```#distanceFilter``` elasticity. eg: When device is moving at highway speeds, locations are returned at ~ 1 / km.
Defaults to ```false```. Set ```true``` to disable automatic speed-based ```#distanceFilter``` elasticity. eg: When device is moving at highway speeds, locations are returned at ~ 1 / km.
Presumably, this affects ios GPS algorithm. See [Apple docs](https://developer.apple.com/library/ios/documentation/CoreLocation/Reference/CLLocationManager_Class/CLLocationManager/CLLocationManager.html#//apple_ref/occ/instp/CLLocationManager/activityType) for more information
Presumably, this affects ios GPS algorithm. See [Apple docs](https://developer.apple.com/library/ios/documentation/CoreLocation/Reference/CLLocationManager_Class/CLLocationManager/CLLocationManager.html#//apple_ref/occ/instp/CLLocationManager/activityType) for more information
The underlying GeoLocator you can choose to use 'DesiredAccuracy' or 'DesiredAccuracyInMeters'. Since this plugins default configuration accepts meters, the default desiredAccuracy is mapped to the Windows Phone DesiredAccuracyInMeters leaving the DesiredAccuracy enum empty. For more info see the [MS docs](http://msdn.microsoft.com/en-us/library/windows/apps/windows.devices.geolocation.geolocator.desiredaccuracyinmeters) for more information.
The underlying GeoLocator you can choose to use 'DesiredAccuracy' or 'DesiredAccuracyInMeters'. Since this plugins default configuration accepts meters, the default desiredAccuracy is mapped to the Windows Phone DesiredAccuracyInMeters leaving the DesiredAccuracy enum empty. For more info see the [MS docs](http://msdn.microsoft.com/en-us/library/windows/apps/windows.devices.geolocation.geolocator.desiredaccuracyinmeters) for more information.
The plugin includes native **geofencing** features. You may add, remove and query the list of monitored geofences from the native plugin. The native plugin will persist monitored geofences and re-initiate them when the app boots or the device is restarted.
A monitored geofence **will remain active** until you explicity remove it via `bgGeo.removeGeofence(identifier)`.
#### Geofence Model
#####`@param {String} identifier`
A unique `String` to identify your Geofence, eg: "Home", "Office".
#####`@param {Integer} radius`
The radius of the circular geofence. A radius of >100 meters works best.
#####`@param {Boolean} notifyOnEntry`
Transitioning **into** the geofence will generate an event.
#####`@param {Boolean} notifyOnExit`
Transitioning **out of** the geofence will generate an event.
#### Listening to Geofence Events
Listen to geofence transition events using the method `#onGeofence`. You may set up any number of `#onGeofence` event-listeners throughout your code -- they will all be executed.
console.error("An error occurred in my code!", e);
}
// Be sure to call #finish!!
bgGeo.finish(taskId);
});
```
#### Removing Geofences
The native plugin will continue to monitor geofences and fire transition-events until you explicity tell the plugin to remove a geofence via `#removeGeofence(identifier)`.
```
bgGeo.removeGeofence("Home");
```
#### Querying Geofences
The native plugin persists monitored geofences between application boots and device restarts. When your app boots, you can fetch the currently monitored geofences from the native plugin and, for example, re-draw markers on your map.
```
bgGeo.getGeofences(function(geofences) {
for (var n=0,len=geofences.length;n<len;n++) {
var geofence = geofences[n];
var marker = new google.maps.Circle({
radius: parseInt(geofence.radius, 10),
center: new google.maps.LatLng(geofence.latitude, geofence.longitude),
// After you Ajax callback is complete, you MUST signal to the native code, which is running a background-thread, that you're done and it can gracefully kill that thread.
// After you Ajax callback is complete, you MUST signal to the native code, which is running a background-thread, that you're done and it can gracefully kill that thread.
yourAjaxCallback.call(this);
/**
* This would be your own callback for Ajax-requests after POSTing background geolocation to your server.
*/
varyourAjaxCallback=function(response){
// Very important to call #finish -- it signals to the native plugin that it can destroy the background thread, which your callbackFn is running in.
// IF YOU DON'T, THE OS CAN KILL YOUR APP FOR RUNNING TOO LONG IN THE BACKGROUND
debug:true,// <-- enable this hear sounds for background-geolocation life-cycle.
debug:true,// <-- enable this hear sounds for background-geolocation life-cycle.
desiredAccuracy:0,
desiredAccuracy:0,
stationaryRadius:50,
stationaryRadius:50,
distanceFilter:25,
distanceFilter:50,
disableElasticity:false,// <-- [iOS] Default is 'false'. Set true to disable speed-based distanceFilter elasticity
disableElasticity:false,// <-- [iOS] Default is 'false'. Set true to disable speed-based distanceFilter elasticity
locationUpdateInterval:5000,
locationUpdateInterval:5000,
minimumActivityRecognitionConfidence:80,// 0-100%. Minimum activity-confidence for a state-change
minimumActivityRecognitionConfidence:80,// 0-100%. Minimum activity-confidence for a state-change
fastestLocationUpdateInterval:5000,
fastestLocationUpdateInterval:5000,
activityRecognitionInterval:10000,
activityRecognitionInterval:10000,
stopTimeout:0,
stopTimeout:0,
forceReload:true,// <-- [Android] If the user closes the app **while location-tracking is started** , reboot app (WARNING: possibly distruptive to user)
forceReload:false,// <-- [Android] If the user closes the app **while location-tracking is started** , reboot app (WARNING: possibly distruptive to user)
stopOnTerminate:false,// <-- [Android] Allow the background-service to run headless when user closes the app.
stopOnTerminate:true,// <-- [Android] Allow the background-service to run headless when user closes the app.
startOnBoot:true,// <-- [Android] Auto start background-service in headless mode when device is powered-up.
startOnBoot:false,// <-- [Android] Auto start background-service in headless mode when device is powered-up.
activityType:'AutomotiveNavigation',
activityType:'AutomotiveNavigation',
/**
/**
* HTTP Feature: set an url to allow the native background service to POST locations to your server
* HTTP Feature: set an url to allow the native background service to POST locations to your server
CDVPluginResult*result=[CDVPluginResultresultWithStatus:CDVCommandStatus_ERRORmessageAsString:@"Failed to sync to server. Is there a network connection?"];
}
// Important to set these before we execute #sync since this fires a *very fast* async NSNotification event!
syncCallbackId=command.callbackId;
syncTaskId=[bgGeocreateBackgroundTask];
NSArray*locations=[bgGeosync];
if(locations==nil){
syncCallbackId=nil;
syncTaskId=UIBackgroundTaskInvalid;
CDVPluginResult*result=[CDVPluginResultresultWithStatus:CDVCommandStatus_ERRORmessageAsString:@"Sync failed. Is there a network connection?"];
throw"BackgroundGeolocation#finish must now be provided with a taskId as 1st param, eg: bgGeo.finish(taskId). taskId is provided by 2nd param in callback";
}
exec(success||function(){},
exec(success||function(){},
failure||function(){},
failure||function(){},
'BackgroundGeoLocation',
'BackgroundGeoLocation',
'finish',
'finish',
[]);
[taskId]);
},
error:function(taskId,message){
if(!taskId){
throw"BackgroundGeolocation#error must now be provided with a taskId as 1st param, eg: bgGeo.finish(taskId). taskId is provided by 2nd param in callback";
}
exec(function(){},
function(){},
'BackgroundGeoLocation',
'error',
[taskId,message]);
},
},
changePace:function(isMoving,success,failure){
changePace:function(isMoving,success,failure){
exec(success||function(){},
exec(success||function(){},
failure||function(){},
failure||function(){},
'BackgroundGeoLocation',
'BackgroundGeoLocation',
'onPaceChange',
'changePace',
[isMoving]);
[isMoving]);
},
},
/**
/**
...
@@ -70,7 +93,7 @@ module.exports = {
...
@@ -70,7 +93,7 @@ module.exports = {
* @param {Integer} timeout
* @param {Integer} timeout
*/
*/
setConfig:function(success,failure,config){
setConfig:function(success,failure,config){
this.apply(this.config,config);
this._apply(this.config,config);
exec(success||function(){},
exec(success||function(){},
failure||function(){},
failure||function(){},
'BackgroundGeoLocation',
'BackgroundGeoLocation',
...
@@ -89,15 +112,24 @@ module.exports = {
...
@@ -89,15 +112,24 @@ module.exports = {
},
},
/**
/**
* Add a stationary-region listener. Whenever the devices enters "stationary-mode", your #success callback will be executed with #location param containing #radius of region
* Add a stationary-region listener. Whenever the devices enters "stationary-mode", your #success callback will be executed with #location param containing #radius of region
* @deprecated in favour of dual-function #onMotionChange
* @param {Function} success
* @param {Function} success
* @param {Function} failure [optional] NOT IMPLEMENTED
* @param {Function} failure [optional] NOT IMPLEMENTED
*/
*/
onStationary:function(success,failure){
onStationary:function(success,failure){
varme=this;
varme=this;
success=success||function(){};
success=success||function(location,taskId){
varcallback=function(region){
me.finish(taskId);
me.stationaryRegion=region;
};
success.apply(me,arguments);
varcallback=function(params){
varlocation=params.location||params,
taskId=params.taskId||'task-id-undefined';
me.stationaryLocation=location;
me._runBackgroundTask(taskId,function(){
success.call(me,location,taskId);
},failure);
};
};
exec(callback,
exec(callback,
failure||function(){},
failure||function(){},
...
@@ -105,13 +137,46 @@ module.exports = {
...
@@ -105,13 +137,46 @@ module.exports = {
'addStationaryRegionListener',
'addStationaryRegionListener',
[]);
[]);
},
},
/**
* Add a movement-state-change listener. Whenever the devices enters "stationary" or "moving" mode, your #success callback will be executed with #location param containing #radius of region
* @param {Function} success
* @param {Function} failure [optional] NOT IMPLEMENTED
