API
Note that all methods now return a Promise in case the success and fail callbacks are not provided, allowing the usage of async/await.
We also recommend using the typescript definitions provided in this repo which have better chance of being up-to-date.
configure(options, success, fail)
Configure options:
| Parameter | Type | Platform | Description | Provider* | Default |
|---|---|---|---|---|---|
locationProvider | Number | all | Set location provider @see PROVIDERS | N/A | DISTANCE_FILTER_PROVIDER |
desiredAccuracy | Number | all | Desired accuracy in meters. Possible values [HIGH_ACCURACY, MEDIUM_ACCURACY, LOW_ACCURACY, PASSIVE_ACCURACY]. Accuracy has direct effect on power drain. Lower accuracy = lower power drain. | all | MEDIUM_ACCURACY |
stationaryRadius | Number | all | Stationary radius in meters. When stopped, the minimum distance the device must move beyond the stationary location for aggressive background-tracking to engage. | DIS | 50 |
debug | Boolean | all | When enabled, the plugin will emit sounds for life-cycle events of background-geolocation! See debugging sounds table. | all | false |
distanceFilter | Number | all | The minimum distance (measured in meters) a device must move horizontally before an update event is generated. @see Apple docs. | DIS,RAW | 500 |
stopOnTerminate | Boolean | all | Enable this in order to force a stop() when the application terminated (e.g. on iOS, double-tap home button, swipe away the app). | all | true |
startOnBoot | Boolean | Android | Start background service on device boot. | all | false |
interval | Number | Android | The minimum time interval between location updates in milliseconds. @see Android docs for more information. | all | 60000 |
fastestInterval | Number | Android | Fastest rate in milliseconds at which your app can handle location updates. @see Android docs. | ACT | 120000 |
activitiesInterval | Number | Android | Rate in milliseconds at which activity recognition occurs. Larger values will result in fewer activity detections while improving battery life. | ACT | 10000 |
stopOnStillActivity | Boolean | Android | @deprecated stop location updates, when the STILL activity is detected | ACT | true |
notificationsEnabled | Boolean | Android | Enable/disable local notifications when tracking and syncing locations | all | true |
startForeground | Boolean | Android | Allow location sync service to run in foreground state. Foreground state also requires a notification to be presented to the user. | all | false |
notificationTitle | String optional | Android | Custom notification title in the drawer. (goes with startForeground) | all | “Background tracking” |
notificationText | String optional | Android | Custom notification text in the drawer. (goes with startForeground) | all | “ENABLED” |
notificationIconColor | String optional | Android | The accent color to use for notification. Eg. #4CAF50. (goes with startForeground) | all | |
notificationIconLarge | String optional | Android | The filename of a custom notification icon. @see Android quirks. (goes with startForeground) | all | |
notificationIconSmall | String optional | Android | The filename of a custom notification icon. @see Android quirks. (goes with startForeground) | all | |
activityType | String | iOS | [AutomotiveNavigation, OtherNavigation, Fitness, Other] Presumably, this affects iOS GPS algorithm. @see Apple docs for more information | all | “OtherNavigation” |
pauseLocationUpdates | Boolean | iOS | Pauses location updates when app is paused. *@see Apple docs | all | false |
saveBatteryOnBackground | Boolean | iOS | Switch to less accurate significant changes and region monitory when in background | all | false |
url | String | all | Server url where to send HTTP POST with recorded locations @see HTTP locations posting | all | |
syncUrl | String | all | Server url where to send fail to post locations @see HTTP locations posting | all | |
syncThreshold | Number | all | Specifies how many previously failed locations will be sent to server at once | all | 100 |
httpHeaders | Object | all | Optional HTTP headers sent along in HTTP request | all | |
maxLocations | Number | all | Limit maximum number of locations stored into db | all | 10000 |
postTemplate | Object\|Array | all | Customization post template @see Custom post template | all |
* DIS = DISTANCE_FILTER_PROVIDER ACT = ACTIVITY_PROVIDER RAW = RAW_PROVIDER
Partial reconfiguration is possible by later providing a subset of the configuration options:
BackgroundGeolocation.configure({
debug: true
});
In this case new configuration options will be merged with stored configuration options and changes will be applied immediately.
Important: Because configuration options are applied partially, it’s not possible to reset option to default value just by omitting it’s key name and calling configure method. To reset configuration option to the default value, it’s key must be set to null!
// Example: reset postTemplate to default
BackgroundGeolocation.configure({
postTemplate: null
});
getConfig(success, fail)
Platform: iOS, Android
Get current configuration. Method will return all configuration options and their values in success callback. Because configure method can be called with subset of the configuration options only, getConfig method can be used to check the actual applied configuration.
BackgroundGeolocation.getConfig(function(config) {
console.log(config);
});
start()
Platform: iOS, Android
Start background geolocation.
stop()
Platform: iOS, Android
Stop background geolocation.
getCurrentLocation(success, fail, options)
Platform: iOS, Android
One time location check to get current location of the device.
| Option parameter | Type | Description |
|---|---|---|
timeout | Number | Maximum time in milliseconds device will wait for location |
maximumAge | Number | Maximum age in milliseconds of a possible cached location that is acceptable to return |
enableHighAccuracy | Boolean | if true and if the device is able to provide a more accurate position, it will do so |
| Success callback parameter | Type | Description |
|---|---|---|
location | Object | location object (@see Location event) |
| Error callback parameter | Type | Description |
|---|---|---|
code | Number | Reason of an error occurring when using the geolocating device |
message | String | Message describing the details of the error |
Error codes:
| Value | Associated constant | Description |
|---|---|---|
| 1 | PERMISSION_DENIED | Request failed due missing permissions |
| 2 | LOCATION_UNAVAILABLE | Internal source of location returned an internal error |
| 3 | TIMEOUT | Timeout defined by `option.timeout was exceeded |
isLocationEnabled(success, fail)
Deprecated: This method is deprecated and will be removed in next major version. Use checkStatus as replacement.
Platform: iOS, Android
One time check for status of location services. In case of error, fail callback will be executed.
| Success callback parameter | Type | Description |
|---|---|---|
enabled | Boolean | true/false (true when location services are enabled) |
checkStatus(success, fail)
Check status of the service
| Success callback parameter | Type | Description |
|---|---|---|
isRunning | Boolean | true/false (true if service is running) |
locationServicesEnabled | Boolean | true/false (true if location services are enabled) |
authorization | Number | authorization status |
Authorization statuses:
- NOT_AUTHORIZED
- AUTHORIZED - authorization to run in background and foreground
- AUTHORIZED_FOREGROUND iOS only authorization to run in foreground only
Note: In the Android concept of authorization, these represent application permissions.
showAppSettings()
Platform: Android >= 6, iOS >= 8.0
Show app settings to allow change of app location permissions.
showLocationSettings()
Platform: Android
Show system settings to allow configuration of current location sources.
getLocations(success, fail)
Platform: iOS, Android
Method will return all stored locations. This method is useful for initial rendering of user location on a map just after application launch.
| Success callback parameter | Type | Description |
|---|---|---|
locations | Array | collection of stored locations |
BackgroundGeolocation.getLocations(
function (locations) {
console.log(locations);
}
);
getValidLocations(success, fail)
Platform: iOS, Android
Method will return locations which have not yet been posted to server.
| Success callback parameter | Type | Description |
|---|---|---|
locations | Array | collection of stored locations |
getValidLocationsAndDelete(success, fail)
Platform: iOS, Android
Method will return locations which have not yet been posted to server and delete to avoid getting them again.
| Success callback parameter | Type | Description |
|---|---|---|
locations | Array | collection of stored locations |
deleteLocation(locationId, success, fail)
Platform: iOS, Android
Delete location with locationId.
deleteAllLocations(success, fail)
Note: You don’t need to delete all locations. The plugin manages the number of stored locations automatically and the total count never exceeds the number as defined by option.maxLocations.
Platform: iOS, Android
Delete all stored locations.
Note: Locations are not actually deleted from database to avoid gaps in locationId numbering. Instead locations are marked as deleted. Locations marked as deleted will not appear in output of BackgroundGeolocation.getValidLocations.
switchMode(modeId, success, fail)
Platform: iOS
Normally the plugin will handle switching between BACKGROUND and FOREGROUND mode itself. Calling switchMode you can override plugin behavior and force it to switch into other mode.
In FOREGROUND mode the plugin uses iOS local manager to receive locations and behavior is affected by option.desiredAccuracy and option.distanceFilter.
In BACKGROUND mode plugin uses significant changes and region monitoring to receive locations and uses option.stationaryRadius only.
// switch to FOREGROUND mode
BackgroundGeolocation.switchMode(BackgroundGeolocation.FOREGROUND_MODE);
// switch to BACKGROUND mode
BackgroundGeolocation.switchMode(BackgroundGeolocation.BACKGROUND_MODE);
forceSync()
Platform: Android, iOS
Force sync of pending locations. Option syncThreshold will be ignored and all pending locations will be immediately posted to syncUrl in single batch.
getLogEntries(limit, fromId, minLevel, success, fail)
Platform: Android, iOS
Return all logged events. Useful for plugin debugging.
| Parameter | Type | Description |
|---|---|---|
limit | Number | limits number of returned entries |
fromId | Number | return entries after fromId. Useful if you plan to implement infinite log scrolling* |
minLevel | String | return log entries above level. Available levels: [“TRACE”, “DEBUG”, “INFO”, “WARN”, “ERROR] |
success | Function | callback function which will be called with log entries |
*Example of infinite log scrolling
Format of log entry:
| Parameter | Type | Description |
|---|---|---|
id | Number | id of log entry as stored in db |
timestamp | Number | timestamp in milliseconds since beginning of UNIX epoch |
level | String | log level |
message | String | log message |
stackTrace | String | recorded stacktrace (Android only, on iOS part of message) |
removeAllListeners(event)
Unregister all event listeners for given event. If parameter event is not provided then all event listeners will be removed.