Name	Name	Last commit message	Last commit date
parent directory ..
README.md	README.md
geofencing.md	geofencing.md
http.md	http.md
timing-diagram.md	timing-diagram.md

📚 API Documentation

🔧 Configuration Options

Geolocation Options
- Common
- iOS
- Android
Activity Recognition Options
- Common
- iOS
HTTP & Persistence Options
Geofencing Options
Application Options
- Common
- iOS
- Android

📘 Guides

🔧 Configuration Options

The following Options can all be provided to the plugin's #ready method:

BackgroundGeolocation.ready({
  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
  distanceFilter: 50,
  .
  .
  .
}, function(state) {
  console.log('- BackgroundGeolocation configured and ready');
  if (!state.enabled) {  // <-- current state provided to callback
    BackgroundGeolocation.start();
  }
});

// Use #setConfig if you need to change options after you've executed #configure

BackgroundGeolocation.setConfig({
  desiredAccuracy: 10,
  distanceFilter: 10
}, function() {
  console.log('set config success');
}, function() {
  console.log('failed to setConfig');
});

🔧 Geolocation Options

[Geolocation] Common Options

Option	Type	Default	Note
`desiredAccuracy`	`Integer`	`0`	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
`distanceFilter`	`Integer`	`10`	The minimum distance (measured in meters) a device must move horizontally before an update event is generated.
`disableElasticity`	`Boolean`	`false`	Set true to disable automatic speed-based #distanceFilter elasticity. eg: When device is moving at highway speeds, locations are returned at ~ 1 / km.
`elasticityMultiplier`	`Float`	`1`	Controls the scale of automatic speed-based `distanceFilter` elasticity. Increasing `elasticityMultiplier` will result in few location samples as speed increases.
`stopAfterElapsedMinutes`	`Integer`	`0`	The plugin can optionally automatically stop tracking after some number of minutes elapses after the `#start` method was called.
`stopOnStationary`	`Boolean`	`false`	The plugin can optionally automatically stop tracking when the `stopTimeout` timer elapses.
`desiredOdometerAccuracy`	`Integer`	`100`	Location accuracy threshold in meters for odometer calculations.

[Geolocation] iOS Options

Option	Type	Default	Note
`stationaryRadius`	`Integer`	`25`	When stopped, the minimum distance the device must move beyond the stationary location for aggressive background-tracking to engage.
`useSignificantChangesOnly`	`Boolean`	`false`	Defaults to `false`. Set `true` in order to disable constant background-tracking and use only the iOS Significant Changes API.
`locationAuthorizationRequest`	`String`	`Always`	The desired iOS location-authorization request, either `Always`, `WhenInUse` or `Any`.
`locationAuthorizationAlert`	`Object`	`{}`	When you configure the plugin `locationAuthorizationRequest` `Always` or `WhenInUse` and the user changes that value in the app's location-services settings or disables location-services, the plugin will display an Alert directing the user to the Settings screen.
`disableLocationAuthorizationAlert`	`Boolean`	`false`	Disables automatic authorization alert when plugin detects the user has disabled location authorization. You will be responsible for handling disabled location authorization by listening to the `providerchange` event.

[Geolocation] Android Options

Option	Type	Default	Note
`locationUpdateInterval`	`Integer`	`1000`	With `distanceFilter: 0`, Sets the desired interval for location updates, in milliseconds. ⚠️ This setting will be ignored when `distanceFilter > 0`
`fastestLocationUpdateInterval`	`Integer`	`10000`	Explicitly set the fastest interval for location updates, in milliseconds.
`deferTime`	`Integer`	`0`	Sets the maximum wait time in milliseconds for location updates to be delivered to your callback, when they will all be delivered in a batch.
`allowIdenticalLocations`	`Boolean`	`false`	The Android plugin will ignore a received location when it is identical to the last location. Set `true` to override this behaviour and record every location, regardless if it is identical to the last location.

🔧 Activity Recognition Options

[Activity Recognition] Common Options

Option	Type	Default	Note
`activityRecognitionInterval`	`Integer`	`10000`	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.
`stopTimeout`	`Integer`	`5`	The number of minutes to wait before turning off location-services after the ActivityRecognition System (ARS) detects the device is `STILL`
`minimumActivityRecognitionConfidence`	`Integer`	`75`	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.
`stopDetectionDelay`	`Integer`	`0`	Number of minute to delay the stop-detection system from being activated.
`disableStopDetection`	`Boolean`	`false`	Disable accelerometer-based Stop-detection System. ⚠️ Not recommended

[Activity Recognition] iOS Options

Option	Type	Default	Note
`activityType`	`Integer`	`ACTIVITY_TYPE_OTHER`	Presumably, this affects ios GPS algorithm. See Apple docs for more information
`disableMotionActivityUpdates`	`Boolean`	`false`	Disable iOS motion-activity updates (eg: "walking", "in_vehicle"). This feature requires a device having the M7 co-processor (ie: iPhone 5s and up). ⚠️ The plugin is HIGHLY optimized to use this for improved battery performance. You are STRONLY recommended to NOT disable this.

🔧 HTTP & Persistence Options

📘 HTTP Guide

Option	Type	Default	Note
`url`	`String`	`null`	Your server url where you wish to HTTP POST locations to
`httpTimeout`	`Integer`	`60000`	HTTP request timeout in milliseconds.
`params`	`Object`	`null`	Optional HTTP params sent along in HTTP request to above `#url`
`extras`	`Object`	`null`	Optional meta-data to attach to each recorded location
`headers`	`Object`	`null`	Optional HTTP headers sent along in HTTP request to above `#url`
`method`	`String`	`POST`	The HTTP method. Defaults to `POST`. Some servers require `PUT`.
`httpRootProperty`	`String`	`location`	The root property of the JSON data where location-data will be appended.
`locationTemplate`	`String`	`undefined`	Optional custom location data schema (eg: `{ "lat:<%= latitude %>, "lng":<%= longitude %> }`
`geofenceTemplate`	`String`	`undefined`	Optional custom geofence data schema (eg: `{ "lat:<%= latitude %>, "lng":<%= longitude %>, "geofence":"<%= geofence.identifier %>:<%= geofence.action %>" }`
`autoSync`	`Boolean`	`true`	If you've enabeld HTTP feature by configuring an `#url`, the plugin will attempt to upload each location to your server as it is recorded.
`autoSyncThreshold`	`Integer`	`0`	The minimum number of persisted records to trigger an `#autoSync` action.
`batchSync`	`Boolean`	`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.
`maxBatchSize`	`Integer`	`-1`	If you've enabled HTTP feature by configuring an `#url` and `batchSync: true`, this parameter will limit the number of records attached to each batch.
`maxDaysToPersist`	`Integer`	`1`	Maximum number of days to store a geolocation in plugin's SQLite database.
`maxRecordsToPersist`	`Integer`	`-1`	Maximum number of records to persist in plugin's SQLite database. Defaults to `-1` (no limit). To disable persisting locations, set this to `0`
`locationsOrderDirection`	`String`	`ASC`	Controls the order that locations are selected from the database (and synced to your server). Defaults to ascending (`ASC`), where oldest locations are synced first. Descending (`DESC`) syncs latest locations first.

🔧 Application Options

[Application] Common Options

Option	Type	Default	Note
`stopOnTerminate`	`Boolean`	`true`	Set `false` to continue tracking after user teminates the app.
`startOnBoot`	`Boolean`	`false`	Set to `true` to enable background-tracking after the device reboots.
`heartbeatInterval`	`Integer`	`60`	Rate in seconds to fire `heartbeat` events.
`schedule`	`Array`	`undefined`	Defines a schedule to automatically start/stop tracking at configured times

[Application] iOS Options

Option	Type	Default	Note
`preventSuspend`	`Boolean`	`false`	Enable this to prevent iOS from suspending your app in the background while in the stationary state. Must be used in conjunction with a `#heartbeatInterval`.

[Application] Android Options

Option	Type	Default	Note
`foregroundService`	`Boolean`	`false`	Set `true` to make the plugin mostly immune to OS termination due to memory pressure from other apps.
`enableHeadless`	`Boolean`	`false`	Set to `true` to enable "Headless" mode when the user terminates the application. In this mode, you can respond to all the plugin's events in the native Android environment. For more information, see the wiki for Android Headless Mode
`notificationPriority`	`Integer`	`NOTIFICATION_PRIORITY_DEFAULT`	Controls the priority of the `foregroundService` notification and notification-bar icon.
`notificationTitle`	`String`	"Your App Name"	When running the service with `foregroundService: true`, Android requires a persistent notification in the Notification Bar. Defaults to the application name
`notificationText`	`String`	"Location service activated"	When running the service with `foregroundService: true`, Android requires a persistent notification in the Notification Bar.
`notificationColor`	`String`	`null`	When running the service with `foregroundService: true`, controls the color of the persistent notification in the Notification Bar.
`notificationSmallIcon`	`String`	Your App Icon	When running the service with `foregroundService: true`, controls your customize notification small icon. Defaults to your application icon.
`notificationLargeIcon`	`String`	`undefined`	When running the service with `foregroundService: true`, controls your customize notification large icon. Defaults to `undefined`.
`forceReloadOnMotionChange`	`Boolean`	`false`	Launch your app whenever the `#motionchange` event fires.
`forceReloadOnLocationChange`	`Boolean`	`false`	Launch your app whenever the `#location` event fires.
`forceReloadOnGeofence`	`Boolean`	`false`	Launch your app whenever the `#geofence` event fires.
`forceReloadOnHeartbeat`	`Boolean`	`false`	Launch your app whenever the `#heartbeat` event fires.
`forceReloadOnSchedule`	`Boolean`	`false`	Launch your app whenever a `schedule` event fires.
`forceReloadOnBoot`	`Boolean`	`false`	If the user reboots the device with the plugin configured for `startOnBoot: true`, your will app will launch when the device is rebooted.

🔧 Geofencing Options

📘 Geofencing Guide

Option	Type	Default	Note
`geofenceProximityRadius`	`Integer`	`1000`	Radius in meters to query for geofences within proximity.
`geofenceInitialTriggerEntry`	`Boolean`	`true`	Set `false` to disable triggering a geofence immediately if device is already inside it.

🔧 Logging & Debug Options

📘 Logging & Debugging Guide

Option	Type	Default	Note
`debug`	`Boolean`	`false`	When enabled, the plugin will emit sounds & notifications for life-cycle events of background-geolocation
`logLevel`	`Integer`	`LOG_LEVEL_VERBOSE`	Sets the verbosity of the plugin's logs from `LOG_LEVEL_OFF` to `LOG_LEVEL_VERBOSE`
`logMaxDays`	`Integer`	`3`	Maximum days to persist a log-entry in database.

⚡ Events

Event Name	Description
`location`	Fired whenever a new location is recorded.
`motionchange`	Fired when the device changes state between stationary and moving
`activitychange`	Fired when the activity-recognition system detects a change in detected-activity (`still, on_foot, in_vehicle, on_bicycle, running`)
`providerchange`	Fired when a change in the state of the device's Location Services has been detected. eg: "GPS ON", "Wifi only".
`geofence`	Fired when a geofence crossing event occurs.
`geofenceschange`	Fired when the list of monitored geofences within `#geofenceProximityRadius` changed
`http`	Fired after a successful HTTP response. `response` object is provided with `status` and `responseText`.
`heartbeat`	Fired each `#heartbeatInterval` while the plugin is in the stationary state with. Your callback will be provided with a `params {}` containing the last known `location {Object}`
`schedule`	Fired when a schedule event occurs. Your `callbackFn` will be provided with the current `state` Object.
`powersavechange`	Fired when the state of the operating-system's "Power Saving" system changes. Your `callbackFn` will be provided with a `Boolean` showing whether "Power Saving" is enabled or disabled
`connectivitychange`	Fired when the state of the device's network connectivity changes (enabled -> disabled and vice-versa)
`enabledchange`	Fired when the plugin's `enabled` state changes. For example, executing `#start` and `#stop` will fire the `enabledchange` event.

Adding event-listeners: `#on`

Event-listeners can be attached using the method #on, supplying the Event Name in the following table. #on accepts both a successFn and failureFn.

BackgroundGeolocation.on("location", successFn, failureFn);

Removing event-listeners: `#un`

Event-listeners are removed with the method #un. You must supply a reference to the exact successFn reference used with the #on method:

function onLocation(location) { 
  console.log('- location: ', location); 
}
function onLocationError(error) {
  console.log('- location error: ', error);
}
// Add a location listener
BackgroundGeolocation.on('location', onLocation, onLocationError);
.
.
.
// Remove a location listener supplying only the successFn (onLocation)
BackgroundGeolocation.un('location', onLocation);

🔷 Methods

BackgroundGeolocation Javascript API supports Promises for nearly every method (the exceptions are #watchPosition and adding event-listeners via #on method.

// Traditional API still works:
bgGeo.getCurrentPosition((location) => {
  console.log('- current position: ', location);
}, (error) => {
  console.log('- location error: ', error);
}, {samples: 1, persist: false});

// Promise API
bgGeo.getCurrentPosition({samples:1, persist: false}).then(location => {
  console.log('- current position: ', location);
}).catch(error => {
  console.log('- location error: ', error);
});

Using `await`

By marking one of your application methods as async you can use the await mechanism instead of callbacks:

async onClickGetPosition() {
  let location = await bgGeo.getCurrentPosition({samples:1, persist: false});
  conosle.log('- current position: ', location);

  let count = await bgGeo.getCount();
  console.log('- There are ', count, ' records in the database');
}

🔹 Core API Methods

Method Name	Arguments	Notes
`ready`	`{defaultConfig}`, `successFn`, `failureFn`	Initializes the plugin with previously persisted configuration. The supplied `defaultConfig` will be applied only for the first boot of you app — thereafter, the plugin will automatically load its configuration from persisent storage
`configure` ⚠️ deprecated	`{config}`, `successFn`, `failureFn`	Initializes the plugin and configures its config options. The `success` callback will be executed after the plugin has successfully configured and provided with the current `state` `Object`.
`setConfig`	`{config}`, `successFn`, `failureFn`	Re-configure the plugin with new config options.
`reset`	`{defaultConfig}`, `successFn`, `failureFn`	Resets the plugin configuration to documented default-values. If a `defaultConfig` is provided, it will be applied after the configuration reset.
`on`	`event`,`successFn`,`failureFn`	Adds an event-listener
`un`	`event`,`callbackFn`,	Removes an event-listener
`start`	`callbackFn`	Enable location tracking. Supplied `callbackFn` will be executed when tracking is successfully engaged. This is the plugin's power ON button.
`stop`	`callbackFn`	Disable location tracking. Supplied `callbackFn` will be executed when tracking is successfully halted. This is the plugin's power OFF button.
`getState`	`callbackFn`	Fetch the current-state of the plugin, including `enabled`, `isMoving`, as well as all other config params
`getCurrentPosition`	`successFn`, `failureFn`, `{options}`	Retrieves the current position using maximum power & accuracy by fetching a number of samples and returning the most accurate to your `callbackFn`.
`watchPosition`	`successFn`, `failureFn`, `{options}`	Start a stream of continuous location-updates.
`stopWatchPosition`	`successFn`, `failureFn`	Halt `#watchPosition` updates.
`changePace`	`Boolean`, `successFn`	Toggles the plugin's state between stationary and moving.
`getOdometer`	`callbackFn`	The plugin constantly tracks distance travelled. The supplied callback will be executed and provided with the `distance` (meters) as the 1st parameter.
`setOdometer`	`Integer`, `callbackFn`	Set the `odometer` to any arbitrary value. NOTE `setOdometer` will perform a `getCurrentPosition` in order to record to exact location where odometer was set; as a result, the `callback` signatures are identical to those of `getCurrentPosition`.
`resetOdometer`	`callbackFn`	Reset the odometer to `0`. Alias for `setOdometer(0)`
`startSchedule`	`callbackFn`	If a `schedule` was configured, this method will initiate that schedule.
`stopSchedule`	`callbackFn`	This method will stop the Scheduler service. Your `callbackFn` will be executed after the Scheduler has stopped
`removeListeners`	`none`	Remove all events-listeners registered with `#on` method
`startBackgroundTask`	`callbackFn`	Sends a signal to the native OS that you wish to perform a long-running task. The OS will not suspend your app until you signal completion with the `#finish` method.
`finish`	`taskId`	Sends a signal to the native OS the supplied `taskId` is complete and the OS may proceed to suspend your application if applicable.
`isPowerSaveMode`	`callbackFn`	Fetches the state of the operating-systems "Power Saving" mode, whether `enabled` or `disabled`

🔹 HTTP & Persistence Methods

Method Name	Arguments	Notes
`getLocations`	`callbackFn`	Fetch all the locations currently stored in native plugin's SQLite database. Your `callbackFn` will receive an `Array` of locations in the 1st parameter
`getCount`	`callbackFn`	Fetches count of SQLite locations table *`SELECT count() from locations`**
`destroyLocations`	`callbackFn`	Delete all records in plugin's SQLite database
`sync`	`successFn`, `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`

🔹 Geofencing Methods

Method Name	Arguments	Notes
`startGeofences`	`callbackFn`	Engages the geofences-only `trackingMode`. In this mode, no active location-tracking will occur -- only geofences will be monitored
`addGeofence`	`{config}`, `successFn`, `failureFn`	Adds a geofence to be monitored by the native plugin.
`addGeofences`	`[geofences]`, `sucessFn`, `failureFn`	Adds a list geofences to be monitored by the native plugin.
`removeGeofence`	`identifier`, `successFn`, `failureFn`	Removes a geofence identified by the provided `identifier`
`removeGeofences`	`successFn`, `failureFn`	Removes all geofences
`getGeofences`	`callbackFn`	Fetch the list of monitored geofences.

🔹 Logging Methods

Method Name	Arguments	Notes
`setLogLevel`	`Integer`, `callbackFn`	Set the Log filter: `LOG_LEVEL_OFF`, `LOG_LEVEL_ERROR`, `LOG_LEVEL_WARNING`, `LOG_LEVEL_INFO`, `LOG_LEVEL_DEBUG`, `LOG_LEVEL_VERBOSE`
`getLog`	`callbackFn`	Fetch the entire contents of the current log database as a `String`.
`destroyLog`	`callbackFn`, `failureFn`	Destroy the contents of the Log database.
`emailLog`	`email`, `callbackFn`	Fetch the entire contents of Log database and email it to a recipient using the device's native email client.
`getSensors`	`callbackFn`, `failureFn`	Returns the presense of device sensors accelerometer, gyroscope, magnetometer, in addition to iOS/Android-specific sensors
`logger.error`	`message`	Record a ❗ log message into the plugin's log database.
`logger.warn`	`message`	Record a ⚠️ log message into the plugin's log database.
`logger.debug`	`message`	Record a 🪲 log message into the plugin's log database.
`logger.info`	`message`	Record a ℹ️ log message into the plugin's log database.
`logger.notice`	`message`	Record a 🔵 log message into the plugin's log database.
`logger.header`	`message`	Record a header log message into the plugin's log database.
`logger.on`	`message`	Record a 🎾 log message into the plugin's log database.
`logger.off`	`message`	Record a 🔴 log message into the plugin's log database.
`logger.ok`	`message`	Record a ✅ log message into the plugin's
`playSound`	`Integer`	Here's a fun one. The plugin can play a number of OS system sounds for each platform. For IOS and Android. I offer this API as-is, it's up to you to figure out how this works.

🔧 Geolocation Options

🔧 [Geolocation] Common Options

`@config {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

You may also use the following constants upon BackgroundGeolocation:

Name	Value	Location Providers	Description
`DESIRED_ACCURACY_NAVIGATION`	`-2`	(iOS only) GPS + Wifi + Cellular	Highest power; highest accuracy
`DESIRED_ACCURACY_HIGH`	`-1`	GPS + Wifi + Cellular	Highest power; highest accuracy
`DESIRED_ACCURACY_MEDIUM`	`10`	Wifi + Cellular	Medium power; Medium accuracy;
`DESIRED_ACCURACY_LOW`	`100`	Wifi (low power) + Cellular	Lower power; No GPS
`DESIRED_ACCURACY_VERY_LOW`	`1000`	Cellular only	Lowest power; lowest accuracy
`DESIRED_ACCURACY_THREE_KILOMETER`	`3000`	(iOS only) Lowest power; lowest accuracy

BackgroundGeoloction.configure({
  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH
});

⚠️ Only DESIRED_ACCURACY_HIGH uses GPS. speed, heading and altitude are available only from GPS.

📘 For platform-specific information about location accuracy, see the corresponding API docs:

Android
iOS

`@config {Integer} distanceFilter`

The minimum distance (measured in meters) a device must move horizontally before an update event is generated.

However, by default, distanceFilter is elastically auto-calculated by the plugin: When speed increases, distanceFilter increases; when speed decreases, so too does distanceFilter.

ℹ️ To disable this behaviour, configure disableElasticity: true

ℹ️ To control the scale of the automatic distanceFilter calculation, see elasticityMultiplier

distanceFilter is auto calculated by rounding speed to the nearest 5 m/s and adding distanceFilter meters for each 5 m/s increment.

For example, at biking speed of 7.7 m/s with a configured distanceFilter: 30:

  rounded_speed = round(7.7, 5)
  => 10
  multiplier = rounded_speed / 5
  => 10 / 5 = 2
  adjusted_distance_filter = multiplier * distanceFilter
  => 2 * 30 = 60 meters

At highway speed of 27 m/s with a configured distanceFilter: 50:

  rounded_speed = round(27, 5)
  => 30
  multiplier = rounded_speed / 5
  => 30 / 5 = 6
  adjusted_distance_filter = multiplier * distanceFilter * elasticityMultipiler
  => 6 * 50 = 300 meters

Note the following real example of background-geolocation on highway 101 towards San Francisco as the driver slows down as he runs into slower traffic (geolocations become compressed as distanceFilter decreases)

Compare now background-geolocation in the scope of a city. In this image, the left-hand track is from a cab-ride, while the right-hand track is walking speed.

`@config {Boolean} disableElasticity [false]`

Defaults to false. Set true to disable automatic, speed-based #distanceFilter elasticity.

`@config {Float} elasticityMultiplier [1]`

Controls the scale of automatic speed-based #distanceFilter elasticity. Increasing elasticityMultiplier will result in fewer location samples as speed increases. A value of 0 has the same effect as disableElasticity: true

`@config {Integer} stopAfterElapsedMinutes`

The plugin can optionally automatically stop tracking after some number of minutes elapses after the #start method was called.

BackgroundGeolocation.configure({
  stopAfterElapsedMinutes: 30
}, function(state) {
  BackgroundGeolocation.start();  // <-- plugin will automatically #stop in 30 minutes
});

`@config {Boolean} stopOnStationary`

The plugin can optionally automatically stop tracking when the stopTimeout timer elapses. For example, when the plugin first detects a motionchange into the "moving" state, the next time a motionchange event occurs into the "stationary" state, the plugin will have automatically called #stop upon itself.

⚠️ stopOnStationary will only occur due to stopTimeout timer elapse. It will not occur by manually executing changePace(false).

BackgroundGeolocation.configure({
  stopOnStationary: true
}, function(state) {
  BackgroundGeolocation.start();
});

`@config {Integer} desiredOdometerAccuracy [100]`

Specify an accuracy threshold in meters for odometer calculations. Defaults to 100. If a location arrives having accuracy > desiredOdometerAccuracy, that location will not be used to update the odometer. If you only want to calculate odometer from GPS locations, you could set desiredOdometerAccuracy: 10. This will prevent odometer updates when a device is moving around indoors, in a shopping mall, for example.

🔧 [Geolocation] iOS Options

`@config {Integer} stationaryRadius (meters)`

When stopped, the minimum distance the device must move beyond the stationary location for aggressive background-tracking to engage.

Configuring stationaryRadius: 0 has NO EFFECT (in fact the plugin enforces a minimum stationaryRadius of 25).

The following image shows the typical distance iOS requires to detect exit of the stationaryRadius, where the green polylines represent a transition from stationary state to moving and the red circles locations where the plugin entered the stationary state.:

📘 For more information, see Philosophy of Operation

⚠️ iOS will not detect the exact moment the device moves out of the stationary-radius. In normal conditions, it will typically take ~200 meters before the plugin begins tracking.

`@config {Boolean} useSignificantChangesOnly [false]`

Defaults to false. Set true in order to disable constant background-tracking and use only the iOS Significant Changes API.

⚠️ If Apple has denied your application, refusing to grant your app the privelege of using the UIBackgroundMode: "location", this can be a solution. NOTE The Significant Changes API will report a location only every 500 to 1000 meters. Many of the plugin's configuration parameters will be ignored, such as #distanceFilter, #stationaryRadius, #activityType, etc.

`@config {Boolean} pausesLocationUpdatesAutomatically [true]`

⚠️ This option should generally be left undefined. You should only specifiy this option if you know exactly what you're doing.

The default behaviour of the plugin is to turn off location-services automatically when the device is detected to be stationary. When set to false, location-services will never be turned off (and disableStopDetection will automatically be set to true) -- it's your responsibility to turn them off when you no longer need to track the device. This feature should not generally be used. preventSuspend will no longer work either.

`@config {String} locationAuthorizationRequest [Always]`

The desired iOS location-authorization request, either Always, WhenInUse or Any. locationAuthorizationRequest tells the plugin the mode it expects to be in — if the user changes this mode in their settings, the plugin will detect this (@see locationAuthorizationAlert). Defaults to Always. WhenInUse will display a blue bar at top-of-screen informing user that location-services are on.

If you configure Any, the plugin allow the user to choose either Always or WhenInUse. The plugin will not show the location-authorization dialog when the user changes the selection in Privacy->Location Services

⚠️ Configuring WhenInUse will disable many of the plugin's features, since iOS forbids any API which operates in the background to operate (such as geofences, which the plugin relies upon to automatically engage background tracking).

`@config {Object} locationAuthorizationAlert`

When you configure the plugin location-authorization Always or WhenInUse and the user changes the value in the app's location-services settings or disabled location-services, the plugin will display an Alert directing the user to the Settings screen. This config allows you to configure all the Strings for that Alert popup and accepts an {Object} containing the following keys:

`@config {String} titleWhenOff [Location services are off]` The title of the alert if user changes, for example, the location-request to `WhenInUse` when you requested `Always`.

`@config {String} titleWhenNotEnabled [Background location is not enabled]` The title of the alert when user disables location-services or changes the authorization request to `Never`

`@config {String} instructions [To use background location, you must enable {locationAuthorizationRequest} in the Location Services settings]` The body text of the alert.

`@config {String} cancelButton [Cancel]` Cancel button label

`@config {String} settingsButton [Settings]` Settings button label

BackgroundGeolocation.configure({
  locationAuthorizationAlert: {
    titleWhenNotEnabled: "Yo, location-services not enabled",
    titleWhenOff: "Yo, location-services OFF",
    instructions: "You must enable 'Always' in location-services, buddy",
    cancelButton: "Cancel",
    settingsButton: "Settings"
  }
})

`@config {Boolean} disableLocationAuthorizationAlert [false]`

Disables automatic authorization alert when plugin detects the user has disabled location authorization. You will be responsible for handling disabled location authorization by listening to the providerchange event.

By default, the plugin automatically shows a native alert (configured via locationAuthorizationAlert) to the user when location-services are disabled, directing them to the settings screen. If you do not desire this automated behaviour, set disableLocationAuthorizationAlert: true.

BackgroundGeolocation.on('providerchange', (provider) => {
  if (!provider.enabled) {
    alert('Please enable location services');
  }
});

BackgroundGeolocation.ready({
  disableLocationAuthorizationAlert: true
}, (state) => {
  console.log('BackgroundGeolocation ready: ', state);
});

🔧 [Geolocation] Android Options

`@config {Integer millis} locationUpdateInterval`

⚠️ To use locationUpdateInterval you must also configure distanceFilter: 0. distanceFilter overrides locationUpdateInterval.

Set the desired interval for active location updates, in milliseconds.

The location client will actively try to obtain location updates for your application at this interval, so it has a direct influence on the amount of power used by your application. Choose your interval wisely.

This interval is inexact. You may not receive updates at all (if no location sources are available), or you may receive them slower than requested. You may also receive them faster than requested (if other applications are requesting location at a faster interval).

Applications with only the coarse location permission may have their interval silently throttled.

📘 Android docs

BackgroundGeolocation.configure({
  distanceFilter: 0,            // Must be 0 or locationUpdateInterval is ignored!
  locationUpdateInterval: 5000  // Get a location every 5 seconds
});

`@config {Integer millis} fastestLocationUpdateInterval`

Explicitly set the fastest interval for location updates, in milliseconds.

This controls the fastest rate at which your application will receive location updates, which might be faster than #locationUpdateInterval in some situations (for example, if other applications are triggering location updates).

This allows your application to passively acquire locations at a rate faster than it actively acquires locations, saving power.

Unlike #locationUpdateInterval, this parameter is exact. Your application will never receive updates faster than this value.

If you don't call this method, a fastest interval will be set to 30000 (30s).

An interval of 0 is allowed, but not recommended, since location updates may be extremely fast on future implementations.

If #fastestLocationUpdateInterval is set slower than #locationUpdateInterval, then your effective fastest interval is #locationUpdateInterval.

📘 Android docs

`@config {Integer} deferTime`

Defaults to 0 (no defer). Sets the maximum wait time in milliseconds for location updates. If you pass a value at least 2x larger than the interval specified with #locationUpdateInterval, then location delivery may be delayed and multiple locations can be delivered at once. Locations are determined at the #locationUpdateInterval rate, but can be delivered in batch after the interval you set in this method. This can consume less battery and give more accurate locations, depending on the device's hardware capabilities. You should set this value to be as large as possible for your needs if you don't need immediate location delivery.

`@config {Boolean} allowIdenticalLocations [false]`

By default, the Android plugin will ignore a received location when it is identical to the last location. Set true to override this behaviour and record everylocation, regardless if it is identical to the last location.

In the logs, you will see a location being ignored:

TSLocationManager:   ℹ️  IGNORED: same as last location

An identical location is often generated when changing state from stationary -> moving, where a single location is first requested (the motionchange location) before turning on regular location updates. Changing geolocation config params can also generate a duplicate location (eg: changing distanceFilter).

`@config {String} triggerActivities`

These are the comma-delimited list of activity-names returned by the ActivityRecognition API which will trigger a state-change from stationary to moving. By default, the plugin will trigger on any of the moving-states:

Activity Name
`in_vehicle`
`on_bicycle`
`on_foot`
`running`
`walking`

If you wish, you can configure the plugin to only engage the moving state for vehicles by providing only "in_vehicle".

// Only trigger tracking for vehicles
BackgroundGeolocation.configure({
  triggerActivities: 'in_vehicle'
});

// Only trigger tracking for on_foot, walking and running
BackgroundGeolocation.configure({
  triggerActivities: 'on_foot, walking, running'
});

🔧 Activity Recognition Options

🔧 [Activity Recognition] Common Options

`@config {Integer millis} [10000] activityRecognitionInterval`

Defaults to 10000 (10 seconds). 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.

`@config {Integer millis} minimumActivityRecognitionConfidence`

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 motionchange event. Defaults to 75.

`@config {Integer minutes} stopTimeout`

When in the moving state, specifies the number of minutes to wait before turning off location-services and enter stationary state after the ActivityRecognition System detects the device is STILL (Android: defaults to 0, no timeout, iOS: defaults to 5min). 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.

📘 See Philosophy of Operation

⚠️ Setting a value > 15 min is not recommended, particularly for Android.

`@config {Boolean} disableStopDetection [false]`

iOS

Disables the accelerometer-based Stop-detection System. When disabled, the plugin will use the default iOS behaviour of automatically turning off location-services when the device has stopped for exactly 15 minutes. When disabled, you will no longer have control over #stopTimeout.

iOS Stop-detection timing.

Android

Location-services will never turn OFF if you set this to true! It will be purely up to you or the user to execute changePace(false) or #stop to turn off location-services.

🔧 [Activity Recognition] iOS Options

`@config {Integer} activityType [ACTIVITY_TYPE_AUTOMOTIVE_NAVIGATION, ACTIVITY_TYPE_OTHER_NAVIGATION, ACTIVITY_TYPE_FITNESS, ACTIVITY_TYPE_OTHER]`

Presumably, this affects iOS stop-detect algorithm. Apple is vague on what exactly this configuration does.

Available values are defined as constants upon the BackgroundGeolocation plugin object:

Name	Value
`ACTIVITY_TYPE_OTHER`	`1`
`ACTIVITY_TYPE_AUTOMOTIVE_NAVIGATION`	`2`
`ACTIVITY_TYPE_FITNESS`	`3`
`ACTIVITY_TYPE_OTHER_NAVIGATION`	`4`

eg:

BackgroundGeolocation.ready({
  activityType: BackgroundGeolocation.ACTIVITY_TYPE_OTHER
});

📘 Apple docs.

`@config {Integer minutes} stopDetectionDelay [0]`

Defaults to 0. Allows the stop-detection system to be delayed from activating. When the stop-detection system is engaged, location-services will be turned off and only the accelerometer is monitored. Stop-detection will only engage if this timer expires. The timer is cancelled if any movement is detected before expiration. If a value of 0 is specified, the stop-detection system will engage as soon as the device is detected to be stationary.

`@config {Boolean} disableMotionActivityUpdates [false]`

Defaults to false. Set true to disable iOS CMMotionActivityManager updates (eg: walking, in_vehicle). This feature requires a device having the M7 co-processor (ie: iPhone 5s and up).

ℹ️ This feature will ask the user for "Health updates" permission using the MOTION_USAGE_DESCRIPTION. If you do not wish to ask the user for the "Health updates", set this option to true; However, you will no longer receive accurate activity data in the recorded locations.

⚠️ The plugin is HIGHLY optimized for motion-activity-updates. If you do disable this, the plugin will drain more battery power. You are STRONGLY advised against disabling this. You should explain to your users with the MOTION_USAGE_DESCRIPTION, for example:

"Accelerometer use increases battery efficiency by intelligently toggling location-tracking"

🔧 Geofencing Options

`@config {Integer meters} geofenceProximityRadius [1000]`

Defaults to 1000 meters. @see releated event geofenceschange. When using Geofences, the plugin activates only thoses in proximity (the maximim geofences allowed to be simultaneously monitored is limited by the platform, where iOS allows only 20 and Android. However, the plugin allows you to create as many geofences as you wish (thousands even). It stores these in its database and uses spatial queries to determine which 20 or 100 geofences to activate.

📘 See Geofencing Guide

📺 View animation of this behaviour

`@config {Boolean} geofenceInitialTriggerEntry [true]`

Defaults to true. Set false to disable triggering a geofence immediately if device is already inside it.

🔧 HTTP & Persistence Options

`@config {String} url [undefined]`

Your server url where you wish to HTTP POST location data to.

BackgroundGeolocation.configure({
  url: 'http://my-server.com/locations'
});

📘 See HTTP Guide for more information.

⚠️ It is highly recommended to let the plugin manage uploading locations to your server, particularly for Android when configured with stopOnTerminate: false, since your Cordova app (where your Javascript lives) will terminate — only the plugin's native Android background service will continue to operate, recording locations and uploading to your server. The plugin's native HTTP service is better at this task than Javascript Ajax requests, since the plugin will automatically retry on server failure.

`@config {Integer} httpTimeout [60000]`

HTTP request timeout in milliseconds. The http failureFn will execute when an HTTP timeout occurs. Defaults to 60000 ms (1 minute).

BackgroundGeolocation.on('http', function(request) {
  console.log('HTTP SUCCESS: ', response);
}, function(request) {
  console.log('HTTP FAILURE', response);
});

BackgroundGeolocation.configure({
  url: 'http://my-server.com/locations',
  httpTimeout: 3000
});

`@config {String} method [POST]`

The HTTP method to use when creating an HTTP request to your configured #url. Defaults to POST. Valid values are POST, PUT and OPTIONS.

BackgroundGeolocation.configure({
  url: 'http://my-server.com/locations',
  method: 'PUT'
});

`@config {Object} params`

Optional HTTP params sent along in each HTTP request.

BackgroundGeolocation.configure({
  url: 'http://my-server.com/locations',
  params: {
    user_id: 1234,
    device_id: 'abc123'
  }
});

POST /locations
 {
  "location": {
    "coords": {
      "latitude": 45.51927004945047,
      "longitude": -73.61650072045029
      .
      .
      .
    }
  },
  "user_id": 1234,
  "device_id": 'abc123'
}

`@config {Object} headers`

Optional HTTP params sent along in HTTP request to above #url.

`@config {String} httpRootProperty [location]`

The root property of the JSON data where location-data will be placed.

📘 See HTTP Guide for more information.

{
    "rootProperty":{
        "coords": {
            "latitude":23.232323,
            "longitude":37.373737
        }
    }
}

You may also specify the character httpRootProperty:"." to place your data in the root of the JSON:

{
    "coords": {
        "latitude":23.232323,
        "longitude":37.373737
    }
}

`@config {String} locationTemplate [undefined]`

Optional custom template for rendering location JSON request data in HTTP requests. Evaulate variables in your locationTemplate using Ruby erb-style tags:

<%= variable_name %>

📘 See HTTP Guide for more information.

BackgroundGeolocation.configure({
  locationTemplate: '{"lat":<%= latitude %>,"lng":<%= longitude %>,"event":"<%= event %>",isMoving:<%= isMoving %>}'
});

// Or use a compact [Array] template!
BackgroundGeolocation.configure({
  locationTemplate: '[<%=latitude%>, <%=longitude%>, "<%=event%>", <%=is_moving%>]'
})

⚠️ If you've configured #extras, these key-value pairs will be merged directly onto your location data. Eg:

BackgroundGeolocation.configure({
  httpRootProperty: 'data',
  locationTemplate: '{"lat":<%= latitude %>,"lng":<%= longitude %>}',
  extras: {
    "foo":"bar"
  }
})

Will result in JSON:

{
    "data": {
        "lat":23.23232323,
        "lng":37.37373737,
        "foo":"bar"
    }
}

Template Tags

Tag	Type	Description
`latitude`	`Float`
`longitude`	`Float`
`speed`	`Float`	Meters
`heading`	`Float`	Degress
`accuracy`	`Float`	Meters
`altitude`	`Float`	Meters
`altitude_accuracy`	`Float`	Meters
`timestamp`	`String`	ISO-8601
`uuid`	`String`	Unique ID
`event`	`String`	`motionchange
`odometer`	`Float`	Meters
`activity.type`	`String`	`still
`activity.confidence`	`Integer`	0-100%
`battery.level`	`Float`	0-100%
`battery.is_charging`	`Boolean`	Is device plugged in?

`@config {String} geofenceTemplate [undefined]`

Optional custom template for rendering geofence JSON request data in HTTP requests. The geofenceTemplate is similar to #locationTemplate with the addition of two extra geofence.* tags.

Evaulate variables in your geofenceTemplate using Ruby erb-style tags:

<%= variable_name %>

📘 See HTTP Guide for more information.

BackgroundGeolocation.configure({
  geofenceTemplate: '{ "lat":<%= latitude %>, "lng":<%= longitude %>, "geofence":"<%= geofence.identifier %>:<%= geofence.action %>" }'
});

// Or use a compact [Array] template!
BackgroundGeolocation.configure({
  geofenceTemplate: '[<%= latitude %>, <%= longitude %>, "<%= geofence.identifier %>", "<%= geofence.action %>"]'
})

Template Tags The tag-list is identical to #locationTemplate with the addition of geofence.identifier and geofence.action.

Tag	Type	Description
`geofence.identifier`	`String`	Which geofence?
`geofence.action`	`String`	`ENTER
`latitude`	`Float`
`longitude`	`Float`
`speed`	`Float`	Meters
`heading`	`Float`	Degress
`accuracy`	`Float`	Meters
`altitude`	`Float`	Meters
`altitude_accuracy`	`Float`	Meters
`timestamp`	`String`	ISO-8601
`uuid`	`String`	Unique ID
`event`	`String`	`motionchange
`odometer`	`Float`	Meters
`activity.type`	`String`	`still
`activity.confidence`	`Integer`	0-100%
`battery.level`	`Float`	0-100%
`battery.is_charging`	`Boolean`	Is device plugged in?

`@config {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.

`@config {Integer} maxBatchSize [undefined]`

If you've enabled HTTP feature by configuring an #url with batchSync: true, this parameter will limit the number of records attached to each batch request. If the current number of records exceeds the maxBatchSize, multiple HTTP requests will be generated until the location queue is empty.

`@config {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).

`@config {Integer} autoSyncThreshold [0]`

The minimum number of persisted records to trigger an autoSync action. If you configure a value greater-than 0, the plugin will wait until that many locations are recorded before executing HTTP requests to your server through your configured #url.

`@config {Object} extras`

Optional arbitrary key/value {} to attach to each recorded location

Eg: Every recorded location will have the following extras appended:

📘 See HTTP Guide for more information.

BackgroundGeolocation.configure({
  url: 'http://my-server.com/locations',
  extras: {
    route_id: 1234
  },
  params: {
    device_id: 'abc123'
  }
});

- POST /locations
{
  "device_id": "abc123" // <-- params appended to root of JSON
  "location": {
    "coords": {
      "latitude": 45.51927004945047,
      "longitude": -73.61650072045029,
      .
      .
      .
    },
    "extras": {  // <-- extras appended to *each* location
      "route_id": 1234
    }
  }
}

`@config {Integer} maxDaysToPersist [1]`

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.

`@config {Integer} maxRecordsToPersist [-1]`

Maximum number of records to persist in plugin's SQLite database. Default -1 means no limit.

`@config {String} locationsOrderDirection [ASC]`

Controls the order that locations are selected from the database (and synced to your server). Defaults to ascending (ASC), where oldest locations are synced first. Descending (DESC) syncs latest locations first.|

🔧 Application Options

🔧 [Application] Common Options

`@config {Boolean} stopOnTerminate [true]`

Defaults to true. When the user terminates the app, the plugin will stop tracking. Set this to false to continue tracking after application terminate.

If you do configure stopOnTerminate: false, your Javascript application will terminate at that time. However, both Android and iOS differ in their behaviour after this point:

iOS

Before an iOS app terminates, the plugin will ensure that a stationary geofence is created around the last known position. When the user moves beyond the stationary geofence (typically ~200 meters), iOS will completely reboot your application in the background, including your Javascript application and the plugin will resume tracking. iOS maintains geofence monitoring at the OS level, in spite of application terminate / device reboot.

In the following image, imagine the user terminated the application at the "red circle" on the right then continued moving: Once the device moves by about 200 meters, exiting the "stationary geofence", iOS reboots the app and tracking resumes.

ℹ️ Demo Video of stopOnTerminate: false

Android

Unlike iOS, the Android plugin's tracking will not pause at all when user terminates the app. However, only the plugin's native background service continues to operate, "headless" (in this case, you should configure an #url in order for the background-service to continue uploading locations to your server).

ℹ️ See Android Headless Mode

`@config {Boolean} startOnBoot [false]`

Defaults to false. Set true to engage background-tracking after the device reboots.

iOS

iOS cannot immediately engage tracking after a device reboot. Just like stopOnTerminate:false, iOS will not re-boot your app until the device moves beyond the stationary geofence around the last known location. In addition, iOS subscribes to "background-fetch" events, which typically fire about every 15 minutes — these too are capable of rebooting your app after a device reboot.

Android

Android will reboot the plugin's background-service immediately after device reboot. However, just like stopOnTerminate:false, the plugin will be running "headless" without your Application code. If you wish for your Application code to boot as well, you may configure forceReloadOnBoot: true

`@config {Integer} heartbeatInterval [undefined]`

Controls the rate (in seconds) the heartbeat event will fire. The plugin will not provide any updated locations to your callbackFn, since it will provide only the last-known location. If you wish for an updated location in your callbackFn, it's up to you to request one with #getCurrentPosition.

⚠️ On iOS the heartbeat event will fire only when configured with preventSuspend: true

⚠️ Android minimum interval is 60 seconds. It is impossible to have a heartbeatInterval faster than this on Android.

BackgroundGeolocation.on('heartbeat', function(params) {
  var lastKnownLocation = params.location;
  console.log('- heartbeat: ', lastKnownLocation);
  // Or you could request a new location
  BackgroundGeolocation.getCurrentPosition(function(location) {
    console.log('- current position: ', location);
  });
});

`@config {Array} schedule [undefined]`

Provides an automated schedule for the plugin to start/stop tracking at pre-defined times. The format is cron-like:

  "{DAY(s)} {START_TIME}-{END_TIME}"

The START_TIME, END_TIME are in 24h format. The DAY param corresponds to the Locale.US, such that Sunday=1; Saturday=7). You may configure a single day (eg: 1), a comma-separated list-of-days (eg: 2,4,6) or a range (eg: 2-6), eg:

BackgroundGeolocation.configure({
  .
  .
  .
  schedule: [
    '1 17:30-21:00',   // Sunday: 5:30pm-9:00pm
    '2-6 9:00-17:00',  // Mon-Fri: 9:00am to 5:00pm
    '2,4,6 20:00-00:00',// Mon, Web, Fri: 8pm to midnight (next day)
    '7 10:00-19:00'    // Sat: 10am-7pm
  ]
}, function(state) {
  // Start the Scheduler
  BackgroundGeolocation.startSchedule(function() {
    console.info('- Scheduler started');
  });
});

// Listen to "schedule" events:
BackgroundGeolocation.on('schedule', function(state) {
  console.log('- Schedule event, enabled:', state.enabled);

  if (!state.schedulerEnabled) {
    BackgroundGeolocation.startSchedule();
  }
});

// Later when you want to stop the Scheduler (eg: user logout)
BackgroundGeolocation.stopSchedule(function() {
  console.info('- Scheduler stopped');
  // You must explicitly stop tracking if currently enabled
  BackgroundGeolocation.stop();
});

// Or modify the schedule with usual #setConfig method
BackgroundGeolocation.setConfig({
  schedule: [
    '1-7 9:00-10:00',
    '1-7 11:00-12:00',
    '1-7 13:00-14:00',
    '1-7 15:00-16:00',
    '1-7 17:00-18:00',
    '2,4,6 19:00-22:00'
  ]
});

Literal Dates

The schedule can also be configured with a literal start date of the form:

  "yyyy-mm-dd HH:mm-HH:mm"

eg:

BackgroundGeolocation.configure({
  schedule: [
    "2018-01-01 09:00-17:00"
  ]

})

Or two literal dates to specify both a start and stop date (note the format here is a bit ugly):

  "yyyy-mm-dd-HH:mm yyyy-mm-dd-HH:mm"

schedule: [
    "2018-01-01-09:00 2019-01-01-17:00"  // <-- track for 1 year
  ]

iOS

iOS cannot evaluate the Schedule at the exact time you configure — it can only evaluate the schedule periodically, whenever your app comes alive. When the app is running in a scheduled off period, iOS will continue to monitor the low-power, significant location changes API (SLC) in order to ensure periodic schedule evaluation. SLC is required in order guarantee periodic schedule-evaluation when you're configured stopOnTerminate: false, since the iOS Background Fetch is halted if user manually terminates the app. SLC will awaken your app whenever a "significant location change" occurs, typically every 1000 meters. If the schedule is currently in an off period, this location will not be persisted nor will it be sent to the location event — only the schedule will be evaluated.

When a schedule is provided on iOS, it will be evaluated in the following cases:

Application pause / resume events.
Whenever a location is recorded (including SLC)
Background fetch event

Android

The Android Scheduler uses [AlarmManager](https://developer.android.com/reference/android/app/AlarmManager.html#setExactAndAllowWhileIdle(int, long, android.app.PendingIntent)) and typically operates on-the-minute.

🔧 [Application] iOS Options

`@config {Boolean} preventSuspend [false]`

Defaults to false. Set true to prevent iOS from suspending after location-services have been switched off while your application is in the background. Must be used in conjunction with a heartbeatInterval.

⚠️ preventSuspend: true should only be used in very specific use-cases and should typically not be used as it will have a very noticable impact on battery performance. You should carefully manage preventSuspend, engaging it for controlled periods-of-time. You should not expect to run your app in this mode 24 hours / day, 7 days-a-week.

🔧 [Application] Android Options

`@config {Boolean} foregroundService [false]`

Defaults to false. When the Android OS is under memory pressure from other applications (eg: a phone call), the OS can and will free up memory by terminating other processes and scheduling them for re-launch when memory becomes available. If you find your tracking being terminated unexpectedly, this is why.

If you set this option to true, the plugin will run its Android service in the foreground, supplying the ongoing notification to be shown to the user while in this state. Running as a foreground-service makes the tracking-service much more inmmune to OS killing it due to memory/battery pressure. By default services are background, meaning that if the system needs to kill them to reclaim more memory (such as to display a large page in a web browser).

ℹ️ See related config options notificationTitle, notificationText & notificationColor

📘 For more information, see the Android Service docs.

`@config {Boolean} enableHeadless [false]`

Set to true to enable "Headless" mode when the user terminates the application where you've configured stopOnTerminate: false. In this mode, you can respond to all the plugin's events in the native Android environment. For more information, see the wiki for Android Headless Mode.

ℹ️ "Headless" mode is an alternartive to using the forceReloadOnXXX configuration options below.

`@config {Boolean} forceReloadOn* [false]`

When the user terminates your Android app with BackgroundGeolocation configured with stopOnTerminate: false, the foreground MainActivity (where your Javascript app lives) will terminate — only the plugin's pure native background-service is running, "headless", in this case. The background service will continue tracking the location. However, the background-service can optionally re-launch your foreground application.

⚠️ When the background service re-launches your application, it will briefly appear in the foreground before immediately minimizing. If the user has their phone on at the time, they will see a brief flash of your app appearing and minimizing.

To "force reload" your application, set any of the following options to true:

`@config {Boolean} forceReloadOnMotionChange [false]`

Launch your app whenever the #motionchange event fires.

`@config {Boolean} forceReloadOnLocationChange [false]`

Launch your app whenever the #location event fires.

`@config {Boolean} forceReloadOnGeofence [false]`

Launch your app whenever the #geofence event fires.

`@config {Boolean} forceReloadOnHeartbeat [false]`

Launch your app whenever the #heartbeat event fires.

`@config {Boolean} forceReloadOnSchedule [false]`

Launch your app whenever a schedule event fires.

`@config {Boolean} forceReloadOnBoot [false]`

If the user reboots the device with the plugin configured for startOnBoot: true, your will app will launch when the device is rebooted.

`@config {Integer} notificationPriority [NOTIFICATION_PRIORITY_DEFAULT]`

When running the service with foregroundService: true, Android requires a persistent notification in the Notification Bar. This will control the priority of that notification as well as the position of the notificaiton-bar icon.

ℹ️ To completely hide the icon in the notification-bar, use NOTIFICATION_PRIORITY_MIN (:warning: It is no longer possible to hide the notification-bar icon in Android O)

The following notificationPriority values defined as constants on the BackgroundGeolocation object:

Value	Description
`NOTIFICATION_PRIORITY_DEFAULT`	Notification weighted to top of list; notification-bar icon weighted left
`NOTIFICATION_PRIORITY_HIGH`	Notification strongly weighted to top of list; notification-bar icon strongly weighted to left
`NOTIFICATION_PRIORITY_LOW`	Notification weighted to bottom of list; notification-bar icon weighted right
`NOTIFICATION_PRIORITY_MAX`	Same as `NOTIFICATION_PRIORITY_HIGH`
`NOTIFICATION_PRIORITY_MIN`	Notification strongly weighted to bottom of list; notification-bar icon hidden

BackgroundGeolocation.configure({
  foregroundService: true,
  notificationPriority: BackgroundGeolocation.NOTIFICATION_PRIORITY_MIN
});

`@config {String} notificationTitle [App name]`

When running the service with foregroundService: true, Android requires a persistent notification in the Notification Bar. This will configure the title of that notification. Defaults to the application name.

`@config {String} notificationText [Location service activated]`

When running the service with foregroundService: true, Android requires a persistent notification in the Notification Bar. This will configure the text of that notification. Defaults to "Location service activated".

`@config {String} notificationColor [null]`

When running the service with foregroundService: true, Android requires a persistent notification in the Notification Bar. This will configure the color of the notification icon (API >= 21).Supported formats are:

#RRGGBB
#AARRGGBB

`@config {String} notificationSmallIcon [app icon]`

When running the service with foregroundService: true, Android requires a persistent notification in the Notification Bar. This allows you customize that icon. Defaults to your application icon. NOTE You must specify the type (drawable|mipmap) of resource you wish to use in the following format:

{type}/icon_name,

⚠️ Do not append the file-extension (eg: .png)

eg:

// 1. drawable
BackgroundGeolocation.configure({
  notificationSmallIcon: "drawable/my_custom_notification_small_icon"
});

// 2. mipmap
BackgroundGeolocation.configure({
  notificationSmallIcon: "mipmap/my_custom_notification_small_icon"
});

`@config {String} notificationLargeIcon [undefined]`

When running the service with foregroundService: true, Android requires a persistent notification in the Notification Bar. This allows you customize that icon. Defaults to undefined. NOTE You must specify the type (drawable|mipmap) of resource you wish to use in the following format:

⚠️ Do not append the file-extension (eg: .png)

{type}/icon_name,

eg:

// 1. drawable
BackgroundGeolocation.configure({
  notificationLargeIcon: "drawable/my_custom_notification_large_icon"
});

// 2. mipmap
BackgroundGeolocation.configure({
  notificationLargeIcon: "mipmap/my_custom_notification_large_icon"
});

🔧 Logging & Debug Options

📘 Logging & Debugging Guide

`@config {Boolean} debug [false]`

Defaults to false. When set to true, the plugin will emit debugging sounds and notifications for life-cycle events of background-geolocation!

iOS: In you wish to hear debug sounds in the background, you must manually enable the [x] Audio and Airplay background mode in Background Capabilities of XCode.

📘 See Debugging Sounds

`@config {Integer} logLevel [5]`

BackgroundGeolocation contains powerful logging features. By default, the plugin boots with a value of LOG_LEVEL_VERBOSE, storing 3 days worth of logs (configurable with logMaxDays) in its SQLite database.

The following log-levels are defined as constants on the BackgroundGeolocation object:

logLevel	Label
`0`	`LOG_LEVEL_OFF`
`1`	`LOG_LEVEL_ERROR`
`2`	`LOG_LEVEL_WARNING`
`3`	`LOG_LEVEL_INFO`
`4`	`LOG_LEVEL_DEBUG`
`5`	`LOG_LEVEL_VERBOSE`

Eg:

BackgroundGeolocation.configure({
  logLevel: BackgroundGeolocation.LOG_LEVEL_WARNING
});

ℹ️ To retrieve the plugin's logs, see getLog & emailLog.

⚠️ When submitting your app to production, take care to configure the logLevel appropriately (eg: LOG_LEVEL_ERROR)

`@config {Integer} logMaxDays [3]`

Maximum number of days to persist a log-entry in database. Defaults to 3 days.

⚡ Events

`location`

Your successFn will be called with the following signature whenever a new location is recorded:

`successFn` Paramters

`@param {Object} location` The Location data (@see Wiki for Location Data Schema)

ℹ️ When performing a motionchange or getCurrentPosition, the plugin requests multiple location samples in order to record the most accurate location possible. These samples are not persisted to the database but they will be provided to your location listener, for your convenience, since it can take some seconds for the best possible location to arrive. For example, you might use these samples to progressively update the user's position on a map. You can detect these samples in your callbackFn via location.sample === true. If you're manually POSTing location to your server, you should ignore these locations.

BackgroundGeolocation.on('location', function(location) {
  var coords    = location.coords,
    timestamp   = location.timestamp
    latitude    = coords.latitude,
    longitude   = coords.longitude,
    speed       = coords.speed;

  console.log("- Location: ", timestamp, latitude, longitude, speed);
}, function(errorCode) {
  console.warn("- Location error: ", errorCode);
});

`failureFn` Paramters

`@param {Integer} errorCode`

Code	Error
0	Location unknown
1	Location permission denied
2	Network error
408	Location timeout

`motionchange`

Your callbackFn will be executed each time the device has changed-state between MOVING or STATIONARY. The callbackFn will be provided with the following parameters:

`@param {Boolean} isMoving`

`@param {Object} location` The location at the state-change.

BackgroundGeolocation.on('motionchange', function(isMoving, location) {
  if (isMoving) {
      console.log('Device has just started MOVING', location);
  } else {
      console.log('Device has just STOPPED', location);
  }  
});

`activitychange`

Your callbackFn will be executed each time the activity-recognition system receives an event (still, on_foot, in_vehicle, on_bicycle, running).

It will be provided an event {Object} containing the following parameters:

`@param {String} activity [still|on_foot|running|on_bicycle|in_vehicle]`

`@param {Integer} confidence [0-100%]`

BackgroundGeolocation.on('activitychange', function(event) {
  console.log('- Activity changed: ', event.activity, event.confidence);
});

`providerchange`

Your callbackFn fill be executed when a change in the state of the device's Location Services has been detected. eg: "GPS ON", "Wifi only". Your callbackFn will be provided with an {Object} provider containing the following properties

`callbackFn` Paramters

`@param {Boolean} enabled` Whether location-services is enabled

`@param {Boolean} gps` Whether gps is enabled

`@param {Boolean} network` Whether wifi geolocation is enabled.

`@param {Integer} status` Location authorization status.

Name	Value	Platform
`AUTHORIZATION_STATUS_NOT_DETERMINED`	`0`	iOS only
`AUTHORIZATION_STATUS_RESTRICTED`	`1`	iOS only
`AUTHORIZATION_STATUS_DENIED`	`2`	iOS & Android
`AUTHORIZATION_STATUS_ALWAYS`	`3`	iOS & Android
`AUTHORIZATION_STATUS_WHEN_IN_USE`	`4`	iOS only

ℹ️ When Android location permission is granted, status == AUTHORIZATION_STATUS_ALWAYS, otherwise, AUTHORIZATION_DENIED.

BackgroundGeolocation.on('providerchange', function(provider) {
  console.log('- Provider Change: ', provider);
  console.log('  enabled: ', provider.enabled);
  console.log('  gps: ', provider.gps);
  console.log('  network: ', provider.network);
  console.log('  status: ', provider.status);

  switch(provider.status) {
    case BackgroundGeolocation.AUTHORIZATION_STATUS_DENIED:
      // Android & iOS
      console.log('- Location authorization denied');
      break;
    case BackgroundGeolocation.AUTHORIZATION_STATUS_ALWAYS:
      // Android & iOS
      console.log('- Location always granted');
      break;
    case BackgroundGeolocation.AUTHORIZATION_STATUS_WHEN_IN_USE:
      // iOS only
      console.log('- Location WhenInUse granted');
      break;
  }
});

`geofence`

Adds a geofence event-listener. Your supplied callbackFn will be called when any monitored geofence crossing occurs.

`callbackFn` Paramters

`@param {Object} geofence` The geofence data, including `identifier`, `action`, `extras`, `location`

BackgroundGeolocation.on('geofence', function(geofence) {
  var location    = geofence.location;
  var identifier  = geofence.identifier;
  var action      = geofence.action;

  console.log('A geofence has been crossed: ', identifier);
  console.log('ENTER or EXIT?: ', action);
  console.log('geofence: ', JSON.stringify(geofence));
});

`geofenceschange`

Fired when the list of monitored-geofences changed. The Background Geolocation contains powerful geofencing features that allow you to monitor any number of circular geofences you wish (thousands even), in spite of limits imposed by the native platform APIs (20 for iOS; 100 for Android).

The plugin achieves this by storing your geofences in its database, using a geospatial query to determine those geofences in proximity (@see config geofenceProximityRadius), activating only those geofences closest to the device's current location (according to limit imposed by the corresponding platform).

When the device is determined to be moving, the plugin periodically queries for geofences in proximity (eg. every minute) using the latest recorded location. This geospatial query is very fast, even with tens-of-thousands geofences in the database.

It's when this list of monitored geofences changes, the plugin will fire the geofenceschange event.

📘 For more information, see Geofencing Guide

`callbackFn` Paramters

`@param {Array} on` The list of geofences just activated.

`@param {Array} off` The list of geofences just de-activated

BackgroundGeolocation.on('geofenceschange', function(event) {
  var on = event.on;   //<-- new geofences activiated.
  var off = event.off; //<-- geofences that were de-activated.

  // Create map circles
  for (var n=0,len=on.length;n<len;n++) {
    var geofence = on[n];
    createGeofenceMarker(geofence)
  }

  // Remove map circles
  for (var n=0,len=off.length;n<len;n++) {
    var identifier = off[n];
    removeGeofenceMarker(identifier);
  }
});

This event object provides only the changed geofences, those which just activated or de-activated.

When all geofences have been removed, the event object will provide an empty-array [] for both #on and #off keys, ie:

{
  on: [{}, {}, ...],  // <-- Entire geofence objects {}
  off: ['identifier_foo', 'identifier_bar']  <-- just the identifiers
}

BackgroundGeolocation.on('geofenceschange', function(event) {
  console.log("geofenceschange fired! ", event);
});

// calling remove geofences will cause the `geofenceschange` event to fire
BackgroundGeolocation.removeGeofences();

=> geofenceschange fired! {on: [], off: []}

`http`

The callbackFn will be executed for each HTTP request where the response-code is one of 200, 201 or 204. failureFn will be executed for all other HTTP response codes. The successFn and failureFn will be provided a single response {Object} parameter with the following properties:

`successFn`, `failureFn` Paramters

`@param {Boolean} success` `true` when HTTP response status indicates success (ie: `200|201|204`)

`@param {Integer} status`. The HTTP status

`@param {String} responseText` The HTTP response as text.

Example:

BackgroundGeolocation.on('http', function(response) {
  var status = response.status;
  var success = response.success;
  var responseText = response.responseText;
  var res = JSON.parse(responseText);  // <-- if your server returns JSON
  console.log("- HTTP success", status, res);
}, function(response) {
  var success = response.success;
  var status = response.status;
  var responseText = response.responseText;
  console.log("- HTTP failure: ", status, responseText);
});

`heartbeat`

The callbackFn will be executed for each #heartbeatInterval while the device is in stationary state (iOS requires preventSuspend: true as well). The callbackFn will be provided a single params {Object} parameter with the following properties:

`callbackFn` Paramters

`@param {String} motionType [still|on_foot|running|on_bicycle|in_vehicle|shaking|unknown]` The current motion-type.

`@param {Object} location` When the plugin detects movement (iOS only), it will always request a new high-accuracy location in order to determine if the device has moved beyond `stationaryRadius` and if the location has `speed > 0`. This fresh location will be provided to your `callbackFn`. Android will simply return the "last known location"

Example:

BackgroundGeolocation.on('heartbeat', function(params) {
  console.log('- hearbeat');

  // You could request a new location if you wish.
  BackgroundGeolocation.getCurrentPosition(function(location) {
    console.log('- current location: ', location);
  });
});

`schedule`

The callbackFn will be executed each time a schedule event fires. Your callbackFn will be provided with the current state object (@see #getState). state.enabled will reflect the state according to your configured schedule.

`callbackFn` Paramters

`@param {Object} state` Current plugin state.

BackgroundGeolocation.on('schedule', function(state) {
  if (state.enabled) {
    console.log('- BackgroundGeolocation scheduled start tracking');
  } else {
    console.log('- BackgroundGeolocation scheduled stop tracking');
  }
});

`powersavechange`

Fired when the state of the operating-system's "Power Saving" mode changes. Your callbackFn will be provided with a Boolean showing whether "Power Saving" is enabled or disabled. Power Saving mode can throttle certain services in the background, such as HTTP requests or GPS.

ℹ️ You can manually request the current-state of "Power Saving" mode with the method #isPowerSaveMode.

iOS

iOS Power Saving mode can be engaged manually by the user in Settings -> Battery or from an automatic OS dialog.

Android

Android Power Saving mode can be engaged manually by the user in Settings -> Battery -> Battery Saver or automatically with a user-specified "threshold" (eg: 15%).

`callbackFn` Paramters

`@param {Boolean} isPowerSaveMode`

BackgroundGeolocation.on('powersavechange', function(isPowerSaveMode) {
  console.log("- powersavechange, power-saving mode enabled? ", isPowerSaveMode);
});

`connectivitychange`

Fired when the state of the device's network-connectivity changes (enabled -> disabled and vice-versa). By default, the plugin will automatically fire a connectivitychange event with the current state network-connectivity whenever the #start method is executed.

BackgroundGeolocation.on('connectivitychange', function(event) {
  console.log("- connectivitychange, network is connected? ", event.connected);
});

`enabledchange`

Fired when the plugin's enabled state changes. For example, executing #start and #stop will cause the enabledchange event to fire. This event is primarily desigend for use with the configuration option [stopAfterElapsedMinutes], which automatically executes the plugin's #stop method.

BackgroundGeolocation.on('enabledchange', function(event) {
  console.log("- enabledchange, plugin is enabled? ", event.enabled);
});

🔷 Methods

BackgroundGeolocation Javascript API supports Promises for nearly every method (the exceptions are #watchPosition and adding event-listeners via #on method.

// Traditional API still works:
bgGeo.getCurrentPosition((location) => {
  console.log('- current position: ', location);
}, (error) => {
  console.log('- location error: ', error);
}, {samples: 1, persist: false});

// Promise API
bgGeo.getCurrentPosition({samples:1, persist: false}).then(location => {
  console.log('- current position: ', location);
}).catch(error => {
  console.log('- location error: ', error);
});

Using `await`

By marking one of your application methods as async you can use the await mechanism instead of callbacks:

async onClickGetPosition() {
  let location = await bgGeo.getCurrentPosition({samples:1, persist: false});
  conosle.log('- current position: ', location);

  let count = await bgGeo.getCount();
  console.log('- There are ', count, ' records in the database');
}

🔹 Core API Methods

`ready(defaultConfig, successFn, failureFn)`

The #ready method is your first point-of-contact with the plugin. The supplied defaultConfig will be applied only at first launch of your app — for every launch thereafter, the plugin will automatically load its last-known configuration from persisent storage. The plugin always remembers the configuration you apply to it.

Observe the following example. Imagine you've deleted the app from the device and re-installed it:

bgGeo.ready({distanceFilter: 10}, (state) => {
  console.log('- Plugin is ready.  distanceFilter: ', state.distanceFilter);  
});

In the console, you'll see

> - Plugin is ready.  distanceFilter: 10

Somewhere else in your code, you change the distanceFilter:

bgGeo.setConfig({distanceFilter: 250});

Now terminate the app and reboot. In the console, you'll see:

> - Plugin is ready.  distanceFilter: 250

⚠️ The #ready method only applies the supplied defaultConfig for the first launch of the app — Forever after, the plugin is going to remember every configuration change you apply at runtime (eg: #setConfig) and reload that same config every time your app boots.

The `#reset` Method

If you wish, you can use the #reset method to reset all configuration options to documented default-values (with optional overrides):

// Reset to documented default-values
bgGeo.reset();
// Reset to documented default-values with overrides
bgGeo.reset({distanceFilter:  10});

`reset: true`

Optionally, you can specify reset: true to #ready. This will esentially force the supplied {config} to be applied with each launch of your application, making it behave like the traditional #configure method.

bgGeo.ready({
  reset: true,  // <-- set true to ALWAYS apply supplied config; not just at first launch.
  distanceFilter: 50
}, (state) => {
  conosle.log('Ready with reset: true: ', state.distanceFilter);
});

With Promise API

bgGeo.ready({distanceFilter: 50}).then(state => {
  console.log('- BackgroundGeolocation is ready: ', state);
}).catch(error => {
  console.log('- BackgroundGeolocation ready failure: ', error);
});

`configure(config, successFn, failureFn)`

⚠️ DEPRECATED IN FAVOUR OF #ready. The #configure method is essentially the same as performing #reset + #ready.

The #configure must be called once (and only once) each time your application boots, providing the initial configuration options. The successFn will be executed after the plugin has successfully configured.

If you later need to re-configure the plugin's config options, use the setConfig method.

`successFn` Paramters

`@param {Object} state` Current plugin state.

BackgroundGeolocation.configure({
  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
  distanceFilter: 50,
  stationaryRadius: 25,
  locationUpdateInterval: 1000,
  foregroundService: true
}, function(state) {
  console.log("Background Geolocation started.  Current state: ", state.enabled);
  if (!state.enabled) {// <-- plugin persists its enabled state.  it may have already started.
    BackgroundGeolocation.start();
  }
}, function(error) {
  console.warn("Background Geolocation failed to configure");
})

ℹ️ BackgroundGeolocation persists its enabled state between application terminate or device reboot and #configure will automatically #start tracking if it finds enabled == true. However, there's no harm in calling #start while the plugin is already enabled, before your successFn is executed.

⚠️ You should not execute any of the plugin's API methods (other than adding event-listeners with #on until your successFn executes. For example:

// OK to add event-listeners before #configure callback fires.
BackgroundGeolocation.on('location', onLocation);
BackgroundGeolocation.on('motionchange', onMotionChange);

BackgroundGeolocation.configure(options, function(state) {
  // YES
  BackgroundGeolocation.getCurrentPosition(succes, fail);
});

// NO!  Wait for #configure callback to execute.
BackgroundGeolocation.getCurrentPosition(success, fail);

`setConfig(config, successFn, failureFn)`

Re-configure plugin's configuration parameters.

BackgroundGeolocation.setConfig({
  desiredAccuracy: 10,
  distanceFilter: 100
}, function(){
  console.log("- setConfig success");
}, function(){
  console.warn("- Failed to setConfig");
});

`reset([config], successFn, failureFn)`

Resets the plugin configuration to documented default-values. If a {config} is provided, it will be applied after the configuration reset.

BackgroundGeolocation.reset({distanceFilter: 50}, function(state) {
  // All config options are now reset to documented default-values
  // + distanceFilter: 50
});

`on(event, successFn, failureFn)`

Event-listeners can be attached using the method #on, supplying the event you wish to listen to. #on accepts both a successFn and failureFn. See Events for a list of available events.

`@param {String} event` The event you wish to listen to

`@param {Function} successFn` The primary event callback function

`@param {Function} failureFn` The failureFn if event failed (ignored for most events)

BackgroundGeolocation.on("location", successFn, failureFn);

`un(event, callbackFn)`

Event-listeners are removed with the method #un. You must supply a reference to the exact successFn reference used with the #on method. See Events for a list of available events.

`@param {String} event` The event you wish to un-subscribe.

`@param {Function} callbackFn` The exact `successFn` reference used to originally subscribe to the event with the `#on` method.

function onLocation(location) {   // <-- successFn
  console.log('- location: ', location); 
}
function onLocationError(error) {
  console.log('- location error: ', error);
}
// Add a location listener
BackgroundGeolocation.on('location', onLocation, onLocationError);
.
.
.
// Remove a location listener supplying only the successFn (onLocation)
BackgroundGeolocation.un('location', onLocation);

`start(successFn, failureFn)`

Enable location tracking. Supplied successFn will be executed when tracking is successfully engaged. This is the plugin's power ON button. The plugin will initially start into its stationary state, fetching an initial location before turning off location services.

Android will be monitoring its Activity Recognition System while iOS will create a stationary geofence around the current location. NOTE If you've configured a #schedule, this method will override that schedule and engage tracking immediately.

`successFn` Paramters

`@param {Object} state` Current plugin state.

BackgroundGeolocation.start(function(state) {
  console.log('- BackgroundGeolocation started, state: ', state);
});

📘 For more information, see Philosophy of Operation

`stop(successFn, failureFn)`

Disable location tracking. Supplied successFn will be executed when tracking is successfully halted. This is the plugin's power OFF button.

BackgroundGeolocation.stop();

⚠️ If you've configured a schedule, #stop will not halt the Scheduler. You must explicitly stop the Scheduler as well:

// Later when you want to stop the Scheduler (eg: user logout)
BackgroundGeolocation.stopSchedule(function() {
  console.info('- Scheduler stopped');
  // You must explicitly stop tracking if currently enabled
  BackgroundGeolocation.stop();
});

`getState(successFn)`

Fetch the current-state of the plugin, including all configuration parameters.

`successFn` Paramters

`@param {Object} state` Current plugin state.

BackgroundGeolocation.getState(function(state) {
  console.log(JSON.stringify(state));
});

{
  "stopOnTerminate": true,
  "disableMotionActivityUpdates": false,
  "params": {
    "device": {
      "manufacturer": "Apple",
       "available": true,
       "platform": "iOS",
       "cordova": "3.9.1",
       "uuid": "61CA53C7-BC4B-44D3-991B-E9021AE7F8EE",
       "model": "iPhone8,1",
       "version": "9.0.2"
    }
  },
  "url": "http://192.168.11.120:8080/locations",
  "desiredAccuracy": 0,
  "stopDetectionDelay": 0,
  "activityRecognitionInterval": 10000,
  "distanceFilter": 50,
  "activityType": 2,
  "useSignificantChangesOnly": false,
  "autoSync": false,
  "isMoving": false,
  "maxDaysToPersist": 1,
  "stopTimeout": 2,
  "enabled": false,
  "debug": true,
  "batchSync": false,
  "headers": {},
  "disableElasticity": false,
  "stationaryRadius": 20
}

`getCurrentPosition(successFn, failureFn, options)`

Retrieves the current position. This method instructs the native code to fetch exactly one location using maximum power & accuracy. 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).

If an error occurs while fetching the location, the failureFn will be executed with an Integer Error Code as the first argument.

Options

`@config {Integer} timeout [30]` An optional location-timeout. If the timeout expires before a location is retrieved, the `failureFn` will be executed.

`@config {Integer millis} maximumAge [0]` Accept the last-recorded-location if no older than supplied value in milliseconds.

`@config {Boolean} persist [true]` Defaults to `true`. Set `false` to disable persisting the retrieved location in the plugin's SQLite database.

`@config {Integer} samples [3]` Sets the maximum number of location-samples to fetch. The plugin will return the location having the best accuracy to your `successFn`. Defaults to `3`. Only the final location will be persisted.

`@config {Integer} desiredAccuracy [stationaryRadius]` Sets the desired accuracy of location you're attempting to fetch. When a location having `accuracy <= desiredAccuracy` is retrieved, the plugin will stop sampling and immediately return that location. Defaults to your configured `stationaryRadius`.

`@config {Object} extras` Optional extra-data to attach to the location. These `extras {Object}` will be merged to the recorded `location` and persisted / POSTed to your server (if you've configured the HTTP Layer).

`successFn` Parameters

`@param {Object} location` The Location data

BackgroundGeolocation.getCurrentPosition(function(location) {
  // 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);
}, function(errorCode) {
  alert('An location error occurred: ' + errorCode);
}, {
  timeout: 30,      // 30 second timeout to fetch location
  maximumAge: 5000, // Accept the last-known-location if not older than 5000 ms.
  desiredAccuracy: 10,  // Try to fetch a location with an accuracy of `10` meters.
  samples: 3,   // How many location samples to attempt.
  extras: {         // [Optional] Attach your own custom `metaData` to this location.  This metaData will be persisted to SQLite and POSTed to your server
    foo: "bar"  
  }
});

ℹ️ While the successFn will receive only one location, the plugin does request multiple location samples in order to record the most accurate location possible. These samples are not persisted to the database but they will be provided to your location event-listener, for your convenience, since it can take some seconds for the best possible location to arrive. For example, you might use these samples to progressively update the user's position on a map. You can detect these samples in your location callbackFn via location.sample === true. If you're manually POSTing location to your server, you should ignore these locations.

`failureFn` Parameters

`@param {Integer} errorCode` If a location failed to be retrieved, one of the following error-codes will be returned

Code	Error
0	Location unknown
1	Location permission denied
2	Network error
408	Location timeout

Eg:

BackgroundGeolocation.getCurrentPosition(succesFn, function(errorCode) {
  switch (errorCode) {
    case 0:
      alert('Failed to retrieve location');
      break;
    case 1:
      alert('You must enable location services in Settings');
      break;
    case 2:
      alert('Network error');
      break;
    case 408:
      alert('Location timeout');
      break;
  }
})

`watchPosition(successFn, failureFn, options)`

Start a stream of continuous location-updates. 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).

⚠️ #watchPosition is not reccommended for long term monitoring in the background — It's primarily designed for use in the foreground only. You might use it for fast-updates of the user's current position on the map, for example.

iOS

#watchPosition will continue to run in the background, preventing iOS from suspending your application. Take care to listen to suspend event and call #stopWatchPosition if you don't want your app to keep running (TODO make this configurable).

Options

`@config {Integer millis} interval [1000]` Location update interval

`@config {Integer} desiredAccuracy` [0]

`@config {Boolean} persist [true]` Whether to persist location to database

`@config {Object} extras [undefined]` Optional extras to append to each location

`successFn` Parameters

`@param {Object} location` The Location data

// Start watching position when app comes to foreground
onAppResume() {
  BackgroundGeolocation.watchPosition(function(location) {
    console.log(“- Watch position: “, location);
  }, function(errorCode) {
    alert('An location error occurred: ' + errorCode);
  }, {
    interval: 1000,    // <-- retrieve a location every 5s.
    persist: false,    // <-- default is true
  });
}

// Stop watching position when app moves to background
onAppSuspend() {
  BackgroundGeolocation.stopWatchPosition();
}

ℹ️ Also see #stopWatchPosition

`stopWatchPosition(successFn, failureFn)`

Halt #watchPosition updates.

BackgroundGeolocation.stopWatchPosition();  // <-- callbacks are optional

`changePace(enabled, successFn, failureFn)`

Manually Toggles the plugin motion state between stationary and moving. When enabled is set to true, the plugin will engage location-services and begin aggressively tracking the device's location immediately, bypassing stationary monitoring. If you were making a "Jogging" application, this would be your [Start Workout] button to immediately begin location-tracking. Send false to turn off location-services and return the plugin to the stationary state.

BackgroundGeolocation.changePace(true);  // <-- Location-services ON
BackgroundGeolocation.changePace(false); // <-- Location-services OFF

`getOdometer(callbackFn, failureFn)`

The plugin constantly tracks distance travelled, computing the distance between the current location and last and maintaining the sum. To fetch the current odometer reading:

BackgroundGeolocation.getOdometer(function(distance) {
  console.log("Distance travelled: ", distance);
});

ℹ️ Also see desiredOdometerAccuracy to set discard poor accuracy locations being used in odometer calculations.

⚠️ Odometer calculations are dependant upon the accuracy of received locations. If location accuracy is poor, this will necessarily introduce error into odometer calculations.

`setOdometer(value, callbackFn, failureFn)`

Set the odometer to any arbitrary value. NOTE setOdometer will perform a getCurrentPosition in order to record to exact location where odometer was set; as a result, the callback signatures are identical to those of getCurrentPosition.

BackgroundGeolocation.setOdometer(1234.56, function(location) {
  // Callback is called with the location where odometer was set at.
  console.log('- setOdometer success: ', location);
}, function(errorCode) {
  // If the plugin failed to fetch a location, it will still have set your odometer to your desired value.
  console.log('- Error: ', errorCode);
});

`resetOdometer(callbackFn, failureFn)`

Reset the odometer to 0. Alias for setOdometer(0)

`startSchedule(callbackFn)`

If a #schedule was configured, this method will initiate that schedule. The plugin will automatically be started or stopped according to the configured #schedule.

BackgroundGeolocation.startSchedule(function() {
  console.log('- Scheduler started');
});

`stopSchedule(callbackFn)`

This method will stop the Scheduler service.

BackgroundGeolocation.stopSchedule(function() {
  console.log('- Scheduler stopped');
});

⚠️ #stopSchedule will not execute #stop if the plugin is currently tracking. You must explicitly execute #stop.

// Later when you want to stop the Scheduler (eg: user logout)
BackgroundGeolocation.stopSchedule(function() {
  // You must explicitly stop tracking if currently enabled
  BackgroundGeolocation.stop();
});

`startBackgroundTask(callbackFn)`

Sends a signal to iOS that you wish to perform a long-running task. The OS will not suspend your app until you signal completion with the #finish method. The callbackFn will be provided with a single parameter taskId which you will send to the #finish method.

`callbackFn` Parameters

`@param {Integer} taskId` The taskId to send to the `#finish` method.

Eg:

BackgroundGeolocation.setOdometer(0, function(location) {
  console.log('- setOdometer at location: ', location);

  BackgroundGeolocation.startBackgroundTask(function(taskId) {  // <-- taskId provided to callback
  // Perform some long-running task (eg: HTTP request)
    performLongRunningTask(function() {
      // When long running task is complete, signal completion of taskId.
      BackgroundGeolocation.finish(taskId);
    });
  });
});

⚠️ iOS provides exactly 180s of background-running time. If your long-running task exceeds this time, the plugin has a fail-safe which will automatically #finish your taskId to prevent the OS from force-killing your application.

`finish(taskId)`

Sends a signal to the native OS that your long-running task, addressed by taskId is complete and the OS may proceed to suspend your application if applicable.

Eg:

BackgroundGeolocation.setOdometer(0, function(location) {
  console.log('- setOdometer at location: ', location);

  BackgroundGeolocation.startBackgroundTask(function(taskId) {  // <-- taskId provided to callback
    // Perform some long-running task (eg: HTTP request)
    performLongRunningTask(function() {
      // When long running task is complete, signal completion of taskId.
      BackgroundGeolocation.finish(taskId);
    });
  });
});

`isPowerSaveMode(callbackFn)`

Fetches the state of the operating-systems "Power Saving" mode, whether enabled or disabled. Power Saving mode can throttle certain services in the background, such as HTTP requests or GPS.

ℹ️ You can listen to changes in the state of "Power Saving" mode with the event #powersavechange.

iOS

iOS Power Saving mode can be engaged manually by the user in Settings -> Battery or from an automatic OS dialog.

Android

Android Power Saving mode can be engaged manually by the user in Settings -> Battery -> Battery Saver or automatically with a user-specified "threshold" (eg: 15%).

Eg:

BackgroundGeolocation.isPowerSaveMode(function(isPowerSaveMode) {
  console.log('- is Power Saving mode enabled?', isPowerSaveMode);
});

`removeListeners(successFn, failureFn)`

Remove all event-listeners registered with #on method. You're free to add more listeners again after executing #removeListeners.

BackgroundGeolocation.on('location', function(location) {
  console.log('- Location', location);  
})
.
.
.
BackgroundGeolocation.removeListeners();

BackgroundGeolocation.on('location', function(location) {
  console.log('- Location listener added again: ', location);
});

🔹 HTTP & Persistence Methods

`getLocations(successFn, 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:

`successFn` Parameters:

`@param {Array} locations` The list of locations stored in SQLite database.

BackgroundGeolocation.getLocations(function(locations) {
  console.log("locations: ", locations);
});

`getCount(successFn, failureFn)`

Fetches count of SQLite locations table SELECT count(*) from locations. The successFn will be executed with count as the only parameter.

`successFn` Parameters:

`@param {Integer} count` Number of locations in the database.

BackgroundGeolocation.getCount(function(count) {
  console.log('- count: ', count);
});

`insertLocation(config, successFn, failureFn)`

Manually insert a location into the native plugin's SQLite database. Your successFn will be executed if the operation was successful. The inserted location's schema must match this plugin's published Location Data Schema. The plugin will have no problem inserting a location retrieved from the plugin itself.

Config Options

`@config {Object} config` The location params/object matching the Location Data Schema.

BackgroundGeolocation.insertLocation({
  "uuid": "f8424926-ff3e-46f3-bd48-2ec788c9e761", // <-- required
  "timestamp": "2016-02-10T22:25:54.905Z"     // <-- required
  "coords": {                   // <-- required
    "latitude": 45.5192746,
    "longitude": -73.616909,
    "accuracy": 22.531999588012695,
    "speed": 0,
    "heading": 0,
    "altitude": 0
  }
}, function() {
  console.log('- Inserted location success');
}, function(error) {
  console.warn('- Failed to insert location: ', error);
});

// insertLocation can easily consume any location which it returned.  Note that #getCurrentPosition ALWAYS persists so this example
// will manually persist a 2nd version of the same location.  The purpose here is to show that the plugin can consume any location object which it generated.
BackgroundGeolocation.getCurrentPosition(function(location) {
  location.extras = {foo: 'bar'}; // <-- add some arbitrary extras-data

  // Insert it.
  BackgroundGeolocation.insertLocation(location, function() {
    console.log('- Inserted location success');
  });
});

`clearDatabase(successFn, failureFn)`

DEPRECATED. Use #destroyLocations.

`destroyLocations(successFn, failureFn)`

Remove all records in plugin's SQLite database.

BackgroundGeolocation.destroyLocations(function() {
  console.log('- cleared database'); 
});

`sync(successFn, 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. When your HTTP server returns a response of 200 OK, that record(s) 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 will delete all records from its SQLite datbase. Eg:

Your callback will be provided with the following params

`successFn` Parameters

`@param {Array} locations` The list of locations stored in SQLite database.

BackgroundGeolocation.sync(function(locations) {
  // Here are all the locations from the database.  The database is now EMPTY.
  console.log('synced locations: ', locations);  
}, function(errorMessage) {
  console.warn('Sync FAILURE: ', errorMessage);
});

📘 For more information, see HTTP Guide

🔹 Geofencing Methods

`startGeofences(callbackFn)`

Engages the geofences-only trackingMode. In this mode, no active location-tracking will occur -- only geofences will be monitored. To stop monitoring "geofences" trackingMode, simply use the usual #stop method. The state object now contains the new key trackingMode [location|geofence].

BackgroundGeolocation.configure(config, function(state) {
  // Add some geofences.
  BackgroundGeolocation.addGeofences([
    notifyOnExit: true,
    radius: 200,
    identifier: 'ZONE_OF_INTEREST',
    latitude: 37.234232,
    longitude: 42.234234 
  ]);

  if (!state.enabled) {
    BackgroundGeolocation.startGeofences(function(state) {
      console.log('- Geofence-only monitoring started', state.trackingMode);
    });
  }
});

// Listen to geofences
BackgroundGeolocation.on('geofence', function(params) {
  if (params.identifier == 'ZONE_OF_INTEREST') {
    // If you wish, you can choose to engage location-tracking mode when a 
    // particular geofence event occurs.
    BackgroundGeolocation.start();
  }
});

`addGeofence(config, successFn, failureFn)`

Adds a geofence to be monitored by the native plugin. If a geofence already exists with the configured identifier, the previous one will be deleted before the new one is inserted.

Config Options

`@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 {Boolean} notifyOnDwell` Whether to listen to DWELL events

`@config {Integer milliseconds} loiteringDelay` When `notifyOnDwell` is `true`, the delay before DWELL event is fired after entering a geofence (@see Creating and Monitoring Geofences)

`@config {Object} extras` Optional arbitrary meta-data.

BackgroundGeolocation.addGeofence({
  identifier: "Home",
  radius: 150,
  latitude: 45.51921926,
  longitude: -73.61678581,
  notifyOnEntry: true,
  notifyOnExit: false,
  notifyOnDwell: true,
  loiteringDelay: 30000,  // 30 seconds
  extras: {               // Optional arbitrary meta-data
    zone_id: 1234
  }
}, function() {
  console.log("Successfully added geofence");
}, function(error) {
  console.warn("Failed to add geofence", error);
});

ℹ️ When adding a list-of-geofences, it's about 10 faster* to use #addGeofences instead.

📘 See Geofencing Guide for more information.

`successFn` Parameters:

`@param {String} identifier` The name of your geofence, eg: "Home", "Office"

`failureFn` Parameters

`@param {String} errorMessage`

`addGeofences(geofences, successFn, failureFn)`

Adds a list of geofences to be monitored by the native plugin. If a geofence already exists with the configured identifier, the previous one will be deleted before the new one is inserted. The geofences param is an Array of geofence Objects {} with the following params:

Config Options

`@config {Array} geofences` An list of geofences configured with the same parmeters as `#addGeofence`

`@config {Function} callbackFn` Executed when geofences successfully added.

`@config {Function} failureFn` Executed when failed to add geofence.

Example:

BackgroundGeolocation.addGeofences([{
  identifier: "Home",
  radius: 150,
  latitude: 45.51921926,
  longitude: -73.61678581,
  notifyOnEntry: true,
  notifyOnExit: false,
  notifyOnDwell: true,
  loiteringDelay: 30000,   // 30 seconds
  extras: {                // Optional arbitrary meta-data
    zone_id: 1234
  }
}], function() {
  console.log("Successfully added geofence");
}, function(error) {
  console.warn("Failed to add geofence", error);
});

`successFn` Parameters:

`@param {String} message`

`failureFn` Parameters:

`@param {String} errorMessage`

`removeGeofence(identifier, successFn, failureFn)`

Removes a geofence having the given {String} identifier.

Config Options

`@config {String} identifier` Identifier of geofence to remove.

`@config {Function} callbackFn` successfully removed geofence.

`@config {Function} failureFn` failed to remove geofence

BackgroundGeolocation.removeGeofence("Home", function() {
  console.log("Successfully removed geofence");
}, function(error) {
  console.warn("Failed to remove geofence", error);
});

`successFn` Parameters:

`@param {String} identifier`

`failureFn` Parameters:

`@param {String} errorMessage`

`removeGeofences(callbackFn, failureFn)`

Removes all geofences.

`@config {Function} callbackFn` successfully removed geofences.

`@config {Function} failureFn` failed to remove geofences

BackgroundGeolocation.removeGeofences(function() {
  console.log("Successfully removed alll geofences");
}, function(error) {
  console.warn("Failed to remove geofence", error);
});

`successFn` Parameters:

`@param {String} message`

`failureFn` Parameters:

`@param {String} errorMessage`

`getGeofences(successFn, failureFn)`

Fetch the list of monitored geofences. Your successFn will be provided with an Array of geofences. If there are no geofences being monitored, you'll receive an empty Array [].

`successFn` Parameters

`@param {Array} geofences` List of all geofences in the database.

Example:

BackgroundGeolocation.getGeofences(function(geofences) {
  for (var n=0,len=geofences.length;n<len;n++) {
    console.log("Geofence: ", geofence.identifier, geofence.radius, geofence.latitude, geofence.longitude);
  }
}, function(error) {
  console.warn("Failed to fetch geofences from server");
});

`failureFn` Parameters

🔹 Logging Methods

`setLogLevel(logLevel, callbackFn)`

Config Options

`@config {Integer} logLevel` The desired log level

`@config {Function} callbackFn` Executed when `logLevel` is changed.

logLevel	Label
`0`	`LOG_LEVEL_OFF`
`1`	`LOG_LEVEL_ERROR`
`2`	`LOG_LEVEL_WARNING`
`3`	`LOG_LEVEL_INFO`
`4`	`LOG_LEVEL_DEBUG`
`5`	`LOG_LEVEL_VERBOSE`

BackgroundGeolocation.setLogLevel(BackgroundGeolocation.LOG_LEVEL_VERBOSE,function() {
  console.log("Changed logLevel success");
});

`getLog(callbackFn)`

Fetches the entire contents of the current circular-log and return it as a String.

`callbackFn` Parameters

`@param {String} log` The complete log in a single string. You can split this string on `\n` to convert to an Array of lines.

BackgroundGeolocation.getLog(function(log) {
  console.log(log);  // <-- send log to console.  copy/paste result into your own text file.
});

`emailLog(email, callbackFn)`

Fetch the entire contents of the current circular log and email it to a recipient using the device's native email client.

Config Options:

`@param {String} email` Email address to send log to.

`@param {Function} callbackFn` Executed after successfully emailed.

`callbackFn` Parameters:

None

BackgroundGeolocation.emailLog("[email protected]");

`destroyLog(successFn, failureFn)`

Destory the entire contents of Log database.

BackgroundGeolocation.destroyLog(function() {
  console.log('- Destroyed log');
}, function() {
  console.log('- Destroy log failure');
});

`successFn` Parameters

None

`failureFn` Parameters

None

`logger`

Send your own log-messages into the plugin's logging database. The following methods are available on the BackgroundGeolocation.logger object:

Methods

method	logLevel	icon
`error`	`ERROR`	❗
`warn`	`WARNING`	⚠️
`debug`	`DEBUG`	🪲
`info`	`INFO`	ℹ️
`notice`	`INFO`	🔵
`header`	`INFO`	message wrapped in box
`on`	`INFO`	🎾
`off`	`INFO`	🔴
`ok`	`INFO`	✅

Javascript Caller Method

Log messages will be recorded in the following format, including the name of name of your javascript caller method where the log message was executed:

2017-08-18 10:12:25.324 ⚠️-[TSLocationManager log:message:caller:] [javascriptCallerMethod] Message

Examples

BackgroundGeolocation.logger.error("Something bad happened");
BackgroundGeolocation.logger.warn("Something weird happened");
BackgroundGeolocation.logger.debug("Debug message");
BackgroundGeolocation.logger.info("Something informative");
BackgroundGeolocation.logger.notice("Something interesting");
BackgroundGeolocation.logger.header("Something bold");
BackgroundGeolocation.logger.on("Something on or positive");
BackgroundGeolocation.logger.off("Something off or negative");
BackgroundGeolocation.logger.ok("Something affirmative happened");

`getSensors(callbackFn, failureFn)`

Returns the presense of device sensors accelerometer, gyroscope, magnetometer, in addition to iOS/Android-specific sensors. These core sensors are used by the motion activity-recognition system — when any of these sensors are missing from a device (particularly on cheap Android devices), the performance of the motion activity-recognition system will be severly degraded and highly inaccurate.

Your callbackFn will be provided an event {Object} containing the following parameters:

`callbackFn` Parameters

`@param {String} platform` "ios" | "android"

`@param {Boolean} accelerometer` Presense of device accelerometer

`@param {Boolean} gyroscope` Presense of device gyroscope

`@param {Boolean} magnetometer` Presense of device magnetometer (compass)

iOS

`@param {Boolean} motion_hardware` Presense of device motion hardware (ie: M7 chip)

Android

`@param {Boolean} significant_motion` Presense of significant motion sensor

BackgroundGeolocation.getSensors(function(sensors) {
  console.log('- has accelerometer? ', sensors.accelerometer);
  console.log('- has gyroscope? ', sensors.gyroscope);
  console.log('- has magnetometer? ', sensors.magnetometer);
  if (sensors.platform === 'ios') {
    console.log('- has motion hardware (M7 chip)?', sensors.motion_hardware);
  } else if (sensors.platform === 'android') {
    console.log('- has significant motion sensor? ', sensors.significant_motion);
  }
});

`playSound(soundId)`

Here's a fun one. The plugin can play a number of OS system sounds for each platform. For IOS and Android. I offer this API as-is, it's up to you to figure out how this works.

// A soundId iOS recognizes
BackgroundGeolocation.playSound(1303);

// An Android soundId
BackgroundGeolocation.playSound(90);

Files

docs

Directory actions

More options

Directory actions

More options

Latest commit

History

docs

Folders and files

parent directory

README.md

📚 API Documentation

🔧 Configuration Options

⚡ Events

🔹 Methods

📘 Guides

🔧 Configuration Options

🔧 Geolocation Options

[Geolocation] Common Options

[Geolocation] iOS Options

[Geolocation] Android Options

🔧 Activity Recognition Options

[Activity Recognition] Common Options

[Activity Recognition] iOS Options

🔧 HTTP & Persistence Options

🔧 Application Options

[Application] Common Options

[Application] iOS Options

[Application] Android Options

🔧 Geofencing Options

🔧 Logging & Debug Options

⚡ Events

Adding event-listeners: #on

Removing event-listeners: #un

🔷 Methods

Using await

🔹 Core API Methods

🔹 HTTP & Persistence Methods

🔹 Geofencing Methods

🔹 Logging Methods

🔧 Geolocation Options

🔧 [Geolocation] Common Options

@config {Integer} desiredAccuracy [0, 10, 100, 1000] in meters

@config {Integer} distanceFilter

@config {Boolean} disableElasticity [false]

@config {Float} elasticityMultiplier [1]

@config {Integer} stopAfterElapsedMinutes

@config {Boolean} stopOnStationary

@config {Integer} desiredOdometerAccuracy [100]

🔧 [Geolocation] iOS Options

@config {Integer} stationaryRadius (meters)

@config {Boolean} useSignificantChangesOnly [false]

@config {Boolean} pausesLocationUpdatesAutomatically [true]

@config {String} locationAuthorizationRequest [Always]

@config {Object} locationAuthorizationAlert

@config {String} titleWhenOff [Location services are off] The title of the alert if user changes, for example, the location-request to WhenInUse when you requested Always.

@config {String} titleWhenNotEnabled [Background location is not enabled] The title of the alert when user disables location-services or changes the authorization request to Never

@config {String} instructions [To use background location, you must enable {locationAuthorizationRequest} in the Location Services settings] The body text of the alert.

@config {String} cancelButton [Cancel] Cancel button label

@config {String} settingsButton [Settings] Settings button label

@config {Boolean} disableLocationAuthorizationAlert [false]

🔧 [Geolocation] Android Options

@config {Integer millis} locationUpdateInterval

@config {Integer millis} fastestLocationUpdateInterval

@config {Integer} deferTime

@config {Boolean} allowIdenticalLocations [false]

@config {String} triggerActivities

🔧 Activity Recognition Options

🔧 [Activity Recognition] Common Options

@config {Integer millis} [10000] activityRecognitionInterval

@config {Integer millis} minimumActivityRecognitionConfidence

@config {Integer minutes} stopTimeout

@config {Boolean} disableStopDetection [false]

🔧 [Activity Recognition] iOS Options

@config {Integer} activityType [ACTIVITY_TYPE_AUTOMOTIVE_NAVIGATION, ACTIVITY_TYPE_OTHER_NAVIGATION, ACTIVITY_TYPE_FITNESS, ACTIVITY_TYPE_OTHER]

@config {Integer minutes} stopDetectionDelay [0]

@config {Boolean} disableMotionActivityUpdates [false]

🔧 Geofencing Options

@config {Integer meters} geofenceProximityRadius [1000]

Adding event-listeners: `#on`

Removing event-listeners: `#un`

Using `await`

`@config {Integer} desiredAccuracy [0, 10, 100, 1000] in meters`

`@config {Integer} distanceFilter`

`@config {Boolean} disableElasticity [false]`

`@config {Float} elasticityMultiplier [1]`

`@config {Integer} stopAfterElapsedMinutes`

`@config {Boolean} stopOnStationary`

`@config {Integer} desiredOdometerAccuracy [100]`

`@config {Integer} stationaryRadius (meters)`

`@config {Boolean} useSignificantChangesOnly [false]`

`@config {Boolean} pausesLocationUpdatesAutomatically [true]`

`@config {String} locationAuthorizationRequest [Always]`

`@config {Object} locationAuthorizationAlert`

`@config {String} titleWhenOff [Location services are off]` The title of the alert if user changes, for example, the location-request to `WhenInUse` when you requested `Always`.

`@config {String} titleWhenNotEnabled [Background location is not enabled]` The title of the alert when user disables location-services or changes the authorization request to `Never`

`@config {String} instructions [To use background location, you must enable {locationAuthorizationRequest} in the Location Services settings]` The body text of the alert.

`@config {String} cancelButton [Cancel]` Cancel button label

`@config {String} settingsButton [Settings]` Settings button label

`@config {Boolean} disableLocationAuthorizationAlert [false]`

`@config {Integer millis} locationUpdateInterval`

`@config {Integer millis} fastestLocationUpdateInterval`

`@config {Integer} deferTime`

`@config {Boolean} allowIdenticalLocations [false]`

`@config {String} triggerActivities`

`@config {Integer millis} [10000] activityRecognitionInterval`

`@config {Integer millis} minimumActivityRecognitionConfidence`

`@config {Integer minutes} stopTimeout`

`@config {Boolean} disableStopDetection [false]`

`@config {Integer} activityType [ACTIVITY_TYPE_AUTOMOTIVE_NAVIGATION, ACTIVITY_TYPE_OTHER_NAVIGATION, ACTIVITY_TYPE_FITNESS, ACTIVITY_TYPE_OTHER]`

`@config {Integer minutes} stopDetectionDelay [0]`

`@config {Boolean} disableMotionActivityUpdates [false]`

`@config {Integer meters} geofenceProximityRadius [1000]`

`@config {Boolean} geofenceInitialTriggerEntry [true]`

`@config {String} url [undefined]`

`@config {Integer} httpTimeout [60000]`

`@config {String} method [POST]`

`@config {Object} params`

`@config {Object} headers`

`@config {String} httpRootProperty [location]`

`@config {String} locationTemplate [undefined]`

`@config {String} geofenceTemplate [undefined]`

`@config {String} batchSync [false]`

`@config {Integer} maxBatchSize [undefined]`

`@config {String} autoSync [true]`

`@config {Integer} autoSyncThreshold [0]`

`@config {Object} extras`

`@config {Integer} maxDaysToPersist [1]`

`@config {Integer} maxRecordsToPersist [-1]`

`@config {String} locationsOrderDirection [ASC]`

`@config {Boolean} stopOnTerminate [true]`

`@config {Boolean} startOnBoot [false]`

`@config {Integer} heartbeatInterval [undefined]`

`@config {Array} schedule [undefined]`

`@config {Boolean} preventSuspend [false]`

`@config {Boolean} foregroundService [false]`

`@config {Boolean} enableHeadless [false]`

`@config {Boolean} forceReloadOn* [false]`

`@config {Boolean} forceReloadOnMotionChange [false]`

`@config {Boolean} forceReloadOnLocationChange [false]`

`@config {Boolean} forceReloadOnGeofence [false]`

`@config {Boolean} forceReloadOnHeartbeat [false]`

`@config {Boolean} forceReloadOnSchedule [false]`

`@config {Boolean} forceReloadOnBoot [false]`

`@config {Integer} notificationPriority [NOTIFICATION_PRIORITY_DEFAULT]`

`@config {String} notificationTitle [App name]`

`@config {String} notificationText [Location service activated]`

`@config {String} notificationColor [null]`

`@config {String} notificationSmallIcon [app icon]`

`@config {String} notificationLargeIcon [undefined]`

`@config {Boolean} debug [false]`

`@config {Integer} logLevel [5]`

`@config {Integer} logMaxDays [3]`

`location`

`successFn` Paramters

`@param {Object} location` The Location data (@see Wiki for Location Data Schema)

`failureFn` Paramters

`@param {Integer} errorCode`

`motionchange`