[iOS only]
Presumably, this affects iOS stop-detect algorithm. Apple is vague about what exactly this option does.
Available values are defined as constants upon the BackgroundGeolocation class.
[Android only]
Allow recording locations which are duplicates of the previous.
Configures the SDK for Authorization with your server (eg: JSON Web Token).
The SDK will automatically apply the supplied token to HTTP request's Authorization header, eg:
"Authorization": "Bearer abcd1234..."
If provided with Authorization.refreshUrl and Authorization.expires, the SDK can automatically re-register for a new token after expiration.
Immediately upload each recorded location to your configured url.
The minimum number of persisted records the plugin must accumulate before triggering an autoSync action.
(Android 11+) Configure the dialog presented to the user when Always location permission is requested.
Just as in iOS 13/14, Android 11 has changed location authorization and no longer offers the [Allow all the time]
button on the location authorization dialog. Instead, Android now offers a hook to present a custom dialog to the user where you will explain exactly why you require "Allow all the time" location permission.
This dialog can forward the user directly to your application's Location Permissions screen, where the user must explicity authorize [Allow all the time]
. The Background Geolocation SDK will present this dialog, which can be customized with backgroundPermissionRationale.
positiveAction
on the dialog, it will not be shown again (pressing [Cancel]
button does not count).[Ask every time]
, the backgroundPermissionRationale can be shown once again.
POST multiple locations to your url in a single HTTP request.
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 database to your server in a single HTTP POST request. With batchSync false
, an HTTP POST
request will be initiated for each location in database.
batchSync: true
— All accumulated locations POSTed in 1 HTTP request.Configure the plugin to emit sound effects and local-notifications during development.
[Android only]
Sets the maximum wait time in milliseconds for location updates.
Defaults to 0
(no defer). 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.
Specify the desired-accuracy of the geolocation system.
The following constants are defined upon the BackgroundGeolocation class:
Name | Location Providers | Description |
---|---|---|
BackgroundGeolocation.DESIRED_ACCURACY_NAVIGATION | (iOS only) GPS + Wifi + Cellular | Highest power; highest accuracy |
BackgroundGeolocation.DESIRED_ACCURACY_HIGH | GPS + Wifi + Cellular | Highest power; highest accuracy |
BackgroundGeolocation.DESIRED_ACCURACY_MEDIUM | Wifi + Cellular | Medium power; Medium accuracy; |
BackgroundGeolocation.DESIRED_ACCURACY_LOW | Wifi (low power) + Cellular | Lower power; No GPS |
BackgroundGeolocation.DESIRED_ACCURACY_VERY_LOW | Cellular only | Lowest power; lowest accuracy |
BackgroundGeolocation.DESIRED_ACCURACY_LOWEST | (iOS only) | Lowest power; lowest accuracy |
DESIRED_ACCURACY_HIGH
uses GPS. speed
, heading
and altitude
are available only from GPS.The maximum location accuracy allowed for a location to be used for Location.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.
Disable autoSync HTTP requests when device is connected to a Cellular connection.
Defaults to false
. Set true
to allow autoSync only when device is connected to Wifi.
WARNING This option is ignored when manually invoking BackgroundGeolocation.sync.
Defaults to false
. Set true
to disable automatic, speed-based distanceFilter auto-scaling. By default, the SDK automatically
increases distanceFilter as speed increases (and decreases it as speed decreases) in order to record fewer locations and conserve energy.
Disables automatic authorization alert when plugin detects the user has disabled location authorization.
Disable the plugin requesting "Motion & Fitness" (ios) or "Physical Activity" (android >= 10) authorization from the User.
[Android-only]
Disables the automatic insert of a location record into the SDK's SQLite database and subsequent HTTP upload if configured with Config.url.
When a onProviderChange event fires, the Android SDK has traditionally recorded a location to show exactly when and where the state of location-services was changed (eg: Location-services disabled).
Android has done this automatically due to the difficulty with some platforms' implementation of Headless Tasks (enableHeadless), where Cordova and Capacitor require implementations using Java code, which is often difficult for most developers.
Some developers' servers have strict HTTP JSON payloads and possibly using locationTemplate, where it's impossible to template the automatically appended provider
key in the payload.
Set true
to disable this default behaviour.
Disable motion-activity related stop-detection.
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
.
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
.
[Android only]
Enables "Headless" operation allowing you to respond to events after you app has been terminated with stopOnTerminate false
.
Enable extra timestamp meta data to be appended to each recorded location, including system-time.
Optional arbitrary key/values {}
applied to each recorded location.
π See HTTP Guide
[Android only]
Explicitly set the fastest interval for location updates, in milliseconds.
[Android only]
Configure the plugin service to run as a more robust "Foreground Service".
When a device is already within a just-created geofence, fire the enter transition immediately.
Defaults to true
. Set false
to disable triggering a geofence immediately if device is already inside it.
[Android only]
Enable high-accuracy for geofence-only mode (See BackgroundGeolocation.startGeofences).
Defaults to false
. Runs Android's BackgroundGeolocation.startGeofences with a foreground service (along with its corresponding persistent Notification.
Configuring geofenceModeHighAccuracy: true
will make Android geofence triggering far more responsive. In this mode, the usual config options to control location-services will be applied:
With the default geofenceModeHighAccuracy: false
, a device will have to move farther into a geofence before the ENTER event fires and farther out of a geofence before
the EXIT event fires.
The more aggressive you configure the location-update params above (at the cost of power consumption), the more responsive will be your geofence-triggering.
The radius around current location to query for geofences to activate monitoring upon.
The default and minimum is 1000
meters. See related event BackgroundGeolocation.onGeofencesChange. When using Geofences, the
plugin activates only those in proximity (the maximum 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.
Optional custom template for rendering GeofenceEvent JSON request data in HTTP requests.
Optional HTTP headers applied to each HTTP request.
Controls the rate (in seconds) the BackgroundGeolocation.onHeartbeat event will fire.
The root property of the JSON schema where location-data will be attached.
HTTP request timeout in milliseconds.
HTTP request timeouts will fire the BackgroundGeolocation.onHttp. Defaults to 60000 ms
.
Configure the initial tracking-state after BackgroundGeolocation.start is called.
The plugin will immediately enter the tracking-state, by-passing the stationary state. If the device is not currently moving, the stop-detection system will still engage. After stopTimeout minutes without movement, the plugin will enter the stationary state, as usual.
[iOS only]
Controls the text-elements of the plugin's location-authorization dialog.
Defines the desired location-authorization request you wish for the user to authorize:
Always
WhenInUse
Any
Optional custom template for rendering Location JSON request data in HTTP requests.
The default timeout in seconds when requesting a location before the SDK gives up and fires a LocationError.
Defaults to 60
seconds.
[Android only]
Set the desired interval for active location updates, in milliseconds.
Controls the order that locations are selected from the database (and uploaded to your server).
Defaults to ascending (ASC
), where oldest locations are synced first. Descending (DESC
) uploads latest locations first.
Controls the volume of recorded events in the plugin's logging database.
BackgroundGeolocation contains powerful logging features. By default, the plugin boots with a value of BackgroundGeolocation.LOG_LEVEL_OFF,
storing logMaxDays (default 3
) days worth of logs in its SQLite database.
The following log-levels are defined as constants on this BackgroundGeolocation class:
Maximum number of days to persist a log-entry in database.
Controls the number of records attached to each batch HTTP request.
Maximum number of days to store a geolocation in plugin's SQLite database.
Maximum number of records to persist in plugin's SQLite database.
Default -1
means no limit.
The HTTP method to use when creating an HTTP request to your configured url.
Defaults to POST
. Valid values are POST
, PUT
and OPTIONS
.
[Android only]
Optionally add a delay in milliseconds to trigger Android into the moving state when Motion API reports the device is moving (eg: on_foot
, in_vehicle
)
This can help prevent false-positive motion-triggering when one moves about their home, for example. Only if the Motion API stays in the moving state for motionTriggerDelay
milliseconds will the plugin trigger into the moving state and begin tracking the location.
If the Motion API returns to the still
state before motionTriggerDelay
times-out, the trigger to the moving state will be cancelled.
[Android only] Configures the persistent foreground-service Notification required by Android.
See Notification for detailed usage.
β οΈ DEPRECATED: Notification.channelName
β οΈ DEPRECATED: Use Notification.color
β οΈ DEPRECATED: Notification.largeIcon
β οΈ DEPRECATED Notification.priority
β οΈ DEPRECATED: Use Notification.smallIcon
β οΈ DEPRECATED: Use Notification.text
β οΈ DEPRECATED: Use Notification.title
Optional HTTP params
appended to the JSON body of each HTTP request.
[iOS only]
Configure iOS location API to never automatically turn off.
Allows you to specify which events to persist to the SDK's internal database: locations | geofences | all (default).
Note that all recorded location and geofence events will always be provided to your [BackgroundGeolocation.onLocation] and [BackgroundGeolocation.onGeofence] events, just that the persistence of those events in the SDK's internal SQLite database can be limited. Any event which has not been persisted to the SDK's internal database will also not therefore be uploaded to your [url] (if configured).
Name | Description |
---|---|
BackgroundGeolocation.PERSIST_MODE_ALL | (DEFAULT) Persist both geofence and location events |
BackgroundGeolocation.PERSIST_MODE_LOCATION | Persist only location events (ignore geofence events) |
BackgroundGeolocation.PERSIST_MODE_GEOFENCE | Persist only geofence events (ignore location events) |
BackgroundGeolocation.PERSIST_MODE_NONE | Persist nothing (neither geofence nor location events) |
This option is designed for specializd use-cases and should generally not be used. For example, some might wish to
run the plugin in regular tracking mode with BackgroundGeolocation.start but only record geofence events. In this case,
one would configure persistMode: BackgroundGeolocation.PERSIST_MODE_GEOFENCE
.
[iOS only]
Prevent iOS from suspending your application in the background after location-services have been switched off.
Controls whether the plugin should first reset the configuration when #ready
is executed before applying the supplied config {}
.
Defaults to true
. The SDK can optionally re-apply its persisted configuration with each boot of your application, ignoring the config {}
supplied to the #ready
method.
Android only Force the Android scheduler to use AlarmManager
(more precise) instead of JobScheduler
. Defaults to false
.
BackgroundGeolocation.ready({
schedule: ["1-7 09:00-17:00"],
scheduleUseAlarmManager: true
});
[iOS Only] A Boolean indicating whether the status bar changes its appearance when an app uses location services in the background with Always
authorization.
The default value of this property is true
. The background location usage indicator is a blue bar or a blue pill in the status bar on iOS; on watchOS the indicator is a small icon. Users can tap the indicator to return to your app.
This property affects only apps that received Always
authorization. When such an app moves to the background, the system uses this property to determine whether to change the status bar appearance to indicate that location services are in use. Set this value to true to maintain transparency with the user.
For apps with When In Use authorization, the system changes the appearance of the status bar when the app uses location services in the background.
Android-only
Experimental filter to ignore anomalous locations that suddenly jump an unusual distance from last.
The SDK will calculate an apparent speed and distance relative to last known location. If the location suddenly
teleports from last location, it will be ignored.
The measurement is in meters/second. The default is to throw away any location which apparently moved at 300 meters/second from last known location.
Controls whether to resume location-tracking after device is rebooted.
Defaults to false
. Set true
to engage background-tracking after the device reboots.
[iOS only]
The minimum distance the device must move beyond the stationary location for aggressive background-tracking to engage.
take ~200 meters of movement before the plugin begins tracking.
[iOS only]
Allows the iOS stop-detection system to be delayed from activating.
Automatically BackgroundGeolocation.stop when the stopTimeout elapses.
Controls whether to continue location-tracking after application is terminated.
Minutes to wait in moving state with no movement before considering the device stationary.
Convenience option to automatically configures the SDK to upload locations to the Transistor Software demo server at http://tracker.transistorsoft.com (or your own local instance of background-geolocation-console)
See TransistorAuthorizationToken. This option will automatically configures the url to point at the Demo server as well as well as the required Authorization configuration.
[Android-only]
Configures a comma-separated list of motion-activities which are allow to trigger location-tracking.
Your server url
where you wish the SDK to automatically upload location data.
Set true
in order to disable constant background-tracking. Locations will be recorded only periodically.
Defaults to false
. A location will be recorded only every 500
to 1000
meters (can be higher in non urban environments; depends upon the spacing of Cellular towers). Many of the plugin's configuration parameters will have no effect, such as distanceFilter, stationaryRadius, activityType, etc.
Using significantChangesOnly: true
will provide significant power-saving at the expense of fewer recorded locations.
Engages the iOS Significant Location Changes API API for only periodic location updates every 500-1000 meters.
Generated using TypeDoc
π§ Configuration API.
The following configuration options are used to configure the SDK via the methods BackgroundGeolocation.ready and BackgroundGeolocation.setConfig.
Geolocation Options
[Geolocation] Common Options
Integer
10
. The minimum distance (measured in meters) a device must move horizontally before an update event is generated.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.Float
1
. Controls the scale of automatic speed-baseddistanceFilter
elasticity. IncreasingelasticityMultiplier
will result in few location samples as speed increases.Integer
0
. The plugin can optionally automatically stop tracking after some number of minutes elapses after the BackgroundGeolocation.start method was called.Boolean
false
. The plugin can optionally automatically stop tracking when thestopTimeout
timer elapses.Integer
100
. Location accuracy threshold in meters for odometer calculations.Boolean
false
. Defaults tofalse
. Settrue
in order to disable constant background-tracking. A location will be recorded only several times / hour.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 theproviderchange
event.Always
. The desired location-authorization request, eitherAlways
,WhenInUse
orAny
.[Geolocation] iOS Options
Integer
25
. When stopped, the minimum distance the device must move beyond the stationary location for aggressive background-tracking to engage.Object
Always
orWhenInUse
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.Boolean
boolean
indicating whether the status bar changes its appearance when an app uses location services in the background withAlways
authorization.[Geolocation] Android Options
Integer
1000
. With distanceFilter: 0, Sets the desired interval for location updates, in milliseconds. β οΈ This setting will be ignored whendistanceFilter > 0
Integer
10000
. Explicitly set the fastest interval for location updates, in milliseconds.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.Boolean
false
. The Android plugin will ignore a received location when it is identical to the last location. Settrue
to override this behaviour and record every location, regardless if it is identical to the last location.Activity Recognition Options
[Activity Recognition] Common Options
Integer
5
. The number of minutes to wait before turning off location-services after the ActivityRecognition System (ARS) detects the device isSTILL
Integer
0
. Number of minutes to delay the stop-detection system from being activated.Boolean
false
. Disable accelerometer-based Stop-detection System. β οΈ Not recommendedBoolean
false
. Disable motion-activity updates (eg: "walking", "in_vehicle"). Requires permission from the user. β οΈ The plugin is HIGHLY optimized to use the Motion API for improved battery performance. You are STRONLY recommended to NOT disable this.[Activity Recognition] iOS Options
HTTP & Persistence Options
String
undefined
. Your server url where you wish to HTTP POST locations toInteger
60000
. HTTP request timeout in milliseconds.Object
undefined
. Optional HTTP params sent along in HTTP request to above urlObject
undefined
. Optional meta-data to attach to each recorded locationObject
undefined
. Optional HTTP headers sent along in HTTP request to above urlString
POST
. The HTTP method. Defaults toPOST
. Some servers requirePUT
.String
location
. The root property of the JSON data where location-data will be appended.String
undefined
. Optional custom location data schema (eg:{ "lat:<%= latitude %>, "lng":<%= longitude %> }
String
undefined
. Optional custom geofence data schema (eg:{ "lat:<%= latitude %>, "lng":<%= longitude %>, "geofence":"<%= geofence.identifier %>:<%= geofence.action %>" }
Boolean
true
. If you've enabled HTTP feature by configuring an url, the plugin will attempt to upload each location to your server as it is recorded.Integer
0
. The minimum number of persisted records to trigger an autoSync action.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.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.Integer
1
. Maximum number of days to store a geolocation in plugin's SQLite database.Integer
-1
. Maximum number of records to persist in plugin's SQLite database. Defaults to-1
(no limit). To disable persisting locations, set this to0
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
Boolean
true
. Setfalse
to continue tracking after user terminates the app.Boolean
false
. Set totrue
to enable background-tracking after the device reboots.Integer
60
. Rate in seconds to fire BackgroundGeolocation.onHeartbeat events.Array
undefined
. Defines a schedule to automatically start/stop tracking at configured times[Application] iOS Options
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
Boolean
false
. Settrue
to make the plugin mostly immune to OS termination due to memory pressure from other apps.Boolean
false
. Set totrue
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 ModeGeofencing Options
Integer
1000
. Radius in meters to query for geofences within proximity.Boolean
true
. Setfalse
to disable triggering a geofence immediately if device is already inside it.[Geofencing] Android Options
Boolean
false
. Runs startGeofences with a foreground service (along with its corresponding persitent Notification). This will make geofence triggering far more consistent at the expense of higher power usage.Logging & Debug Options
Boolean
false
. When enabled, the plugin will emit sounds & notifications for life-cycle events of background-geolocationInteger
LOG_LEVEL_VERBOSE
. Sets the verbosity of the plugin's logs fromLOG_LEVEL_OFF
toLOG_LEVEL_VERBOSE
Integer
3
. Maximum days to persist a log-entry in database.