Interface BackgroundGeolocation

ReadonlydeviceSettings

Readonlylogger

onNotificationAction

• onNotificationAction(cb: (buttonId: string) => void): Subscription

  [Android-only] Subscribe to button-clicks of a custom NotificationConfig.layout on the Android foreground-service notification.

  Parameters

  • cb: (buttonId: string) => void

  Returns Subscription

removeListeners

• removeListeners(): Promise<void>

  Removes all event-listeners.

  Calls [[Subscription.remove]] on all subscriptions.

  Returns Promise<void>

  Example

  BackgroundGeolocation.removeListeners();
  Copy

registerHeadlessTask

• registerHeadlessTask(callback: (event: HeadlessEvent) => Promise<void>): void

  Registers a Javascript callback to execute in the Android "Headless" state, where the app has been terminated configured with AppConfig.stopOnTerminate:false. The received eventobject contains aname(the event name) andparams` (the event data-object).

  ⚠️ Note Cordova & Capacitor

  • Javascript headless callbacks are not supported by Cordova or Capacitor. See Android Headless Mode

  ⚠️ Warning:

  • You must registerHeadlessTask in your application root file (eg: index.js).

  ⚠️ Warning:

  • Your function must be declared as async. You must await all work within your task. Your headless-task will automatically be terminated after executing the last line of your function.

  Parameters

  • callback: (event: HeadlessEvent) => Promise<void>

  Returns void

  Example

  const BackgroundGeolocationHeadlessTask = async (event) => {
    const params = event.params;
    console.log("[BackgroundGeolocation HeadlessTask] -", event.name, params);
  
    switch (event.name) {
      case "terminate":
        // Use await for async tasks
        const location = await BackgroundGeolocation.getCurrentPosition({
          samples: 1,
          persist: false
        });
        console.log("[BackgroundGeolocation HeadlessTask] - getCurrentPosition:", location);
        break;
    }
    // You must await all work you do in your task.  
    // Headless-tasks are automatically terminated after executing the last line of your function.
    await doWork();
  }
  
  BackgroundGeolocation.registerHeadlessTask(BackgroundGeolocationHeadlessTask);
  Copy

  Debugging

  While implementing your headless-task It's crucial to observe your Android logs in a terminal via

  $ adb logcat *:S TSLocationManager:V ReactNativeJS:V
  
  TSLocationManager: [c.t.r.HeadlessTask onHeadlessEvent] 💀  event: connectivitychange
  TSLocationManager: [c.t.r.HeadlessTask createReactContextAndScheduleTask] initialize ReactContext
  TSLocationManager: [c.t.r.HeadlessTask onHeadlessEvent] 💀  event: providerchange
  TSLocationManager: [c.t.r.HeadlessTask onHeadlessEvent] 💀  event: terminate
  ReactNativeJS: '[BGGeoHeadlessTask] ', 'connectivitychange', taskId: 1
  TSLocationManager: [c.t.r.HeadlessTask invokeStartTask] taskId: 1
  TSLocationManager: [c.t.r.HeadlessTask invokeStartTask] taskId: 2
  TSLocationManager: [c.t.r.HeadlessTask invokeStartTask] taskId: 3
  ReactNativeJS: '[BGGeoHeadlessTask] ', 'providerchange', taskId: 2
  ReactNativeJS: '[BGGeoHeadlessTask] ', 'terminate', taskId: 3
  TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task start] ⏳ startBackgroundTask: 1
  TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task start] ⏳ startBackgroundTask: 2
  ReactNativeJS: *** [doWork] START
  ReactNativeJS: *** [doWork] START
  TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task start] ⏳ startBackgroundTask: 3
  ReactNativeJS: *** [doWork] START
  .
  .
  .
  ReactNativeJS: *** [doWork] FINISH
  ReactNativeJS: *** [doWork] FINISH
  ReactNativeJS: *** [doWork] FINISH
  TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task stop] ⏳ stopBackgroundTask: 1
  TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task stop] ⏳ stopBackgroundTask: 2
  TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task stop] ⏳ stopBackgroundTask: 3
  TSLocationManager: [c.t.r.HeadlessTask$1 onHeadlessJsTaskFinish] taskId: 1
  TSLocationManager: [c.t.r.HeadlessTask$1 onHeadlessJsTaskFinish] taskId: 2
  TSLocationManager: [c.t.r.HeadlessTask$1 onHeadlessJsTaskFinish] taskId: 3
  Copy

  ℹ️ See also:

  • 📘 Android Headless Mode.
  • AppConfig.enableHeadless

ready

• ready(config: Config): Promise<State>

  Signal to the plugin that your app is launched and ready, proving the default Config.

  The supplied Config will be applied only at first install of your app — for every launch thereafter, the plugin will automatically load its last-known configuration from persistent storage. The plugin always remembers the configuration you apply to it.

  Parameters

  • config: Config

  Returns Promise<State>

  Example

  BackgroundGeolocation.ready({
    desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
    distanceFilter: 10,
    stopOnTerminate: false,
    startOnBoot: true,
    url: "http://your.server.com",
    headers: {
     "my-auth-token": "secret-token"
    }
  }).then((state) => {
   console.log("[ready] success", state);
  });
  Copy

  ⚠️ Warning:

  • You must call .ready(confg) once and only once, each time your app is launched.
  • Do not hide the call to .ready(config) within a view which is loaded only by clicking a UI action. This is particularly important for iOS in the case where the OS relaunches your app in the background when the device is detected to be moving. If you don't ensure that .ready(config) is called in this case, tracking will not resume.

  The reset method.

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

  Config.reset: false

  Configuring the plugin with reset: false should generally be avoided unless you know exactly what it does. People often find this from the Demo app. If you do configure reset: false, you'll find that your Config provided to .ready is consumed only at first launch after install. Thereafter, the plugin will ignore any changes you've provided there. The only way to change the config then is to use setConfig.

  You will especially not want to use reset: false during development, while you're fine-tuning your Config options.

  The reason the Demo app uses reset: false is because it hosts an advanced "Settings" screen to tune the Config at runtime and we don't want those runtime changes to be overwritten by .ready(config) each time the app launches.

  ⚠️ If you don't undestand what reset: false does, NO NOT USE IT. If you blindly copy/pasted it from the Demo app, REMOVE IT from your Config.

  Example

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

reset

• reset(config: Config): Promise<State>

  Resets the SDK configuration to documented default-values.

  If an optional Config is provided, it will be applied after the configuration reset.

  Parameters

  • config: Config

  Returns Promise<State>

start

• start(): Promise<State>

  Enable location + geofence tracking.

  This is the SDK'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 AppConfig.schedule, this method will override that schedule and engage tracking immediately.

  Returns Promise<State>

  Example

  BackgroundGeolocation.start().then((state) => {
    console.log("[start] success - ", state);
  });
  Copy

  ℹ️ See also:

  • stop
  • startGeofences
  • 📘 Philosophy of Operation

stop

• stop(): Promise<State>

  Disable location and geofence monitoring. This is the SDK's power OFF button.

  Returns Promise<State>

  Example

  BackgroundGeolocation.stop();
  Copy

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

  Example

  // Later when you want to stop the Scheduler (eg: user logout)
  BackgroundGeolocation.stopSchedule();
  Copy

changePace

• changePace(isMoving: boolean): Promise<State>

  Manually toggles the SDK's motion state between stationary and moving.

  When provided a value of 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.

  Parameters

  • isMoving: boolean

  Returns Promise<State>

  Example

  BackgroundGeolocation.changePace(true);  // <-- Location-services ON ("moving" state)
  BackgroundGeolocation.changePace(false); // <-- Location-services OFF ("stationary" state)
  Copy

startGeofences

• startGeofences(): Promise<State>

  Engages the geofences-only State.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.

  Returns Promise<State>

  Example

  // Add a geofence.
  BackgroundGeolocation.addGeofence({
    notifyOnExit: true,
    radius: 200,
    identifier: "ZONE_OF_INTEREST",
    latitude: 37.234232,
    longitude: 42.234234
  });
  
  // Listen to geofence events.
  BackgroundGeolocation.onGeofence((event) => {
    console.log("[onGeofence] -  ", event);
  });
  
  // Configure the plugin
  BackgroundGeolocation.ready({
    url: "http://my.server.com",
    autoSync: true
  }).then(((state) => {
    // Start monitoring geofences.
    BackgroundGeolocation.startGeofences();
  });
  Copy

  ℹ️ See also:

  • stop
  • 📘 Geofencing Guide

getState

• getState(): Promise<State>

  Return the current State of the plugin, including all Config parameters.

  Returns Promise<State>

  Example

  let state = await BackgroundGeolocation.getState();
  console.log("[state] ", state.enabled, state.trackingMode);
  Copy

setConfig

• setConfig(config: Partial<Config>): Promise<State>

  Re-configure the SDK's Config parameters. This is the method to use when you wish to change the plugin Config after ready has been executed.

  The supplied Config will be appended to the current configuration and applied in realtime.

  Parameters

  • config: Partial<Config>

  Returns Promise<State>

  Example

  BackgroundGeolocation.setConfig({
    desiredAccuracy: Config.DESIRED_ACCURACY_HIGH,
    distanceFilter: 100.0,
    stopOnTerminate: false,
    startOnBoot: true
  }).then((state) => {
    console.log("[setConfig] success: ", state);
  })
  Copy

getCurrentPosition

• getCurrentPosition(options?: CurrentPositionRequest): Promise<Location>

  Retrieves the current Location.

  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 [[Config.url]]. If an error occurs while fetching the location, catch will be provided with an [[LocationError]].

  Options

  See CurrentPositionRequest.

  Error Codes

  See LocationError.

  Parameters

  • Optionaloptions: CurrentPositionRequest

  Returns Promise<Location>

  Example

  let location = await BackgroundGeolocation.getCurrentPosition({
    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: {             // Custom meta-data.
      "route_id": 123
    }
  });
  Copy

  ⚠️ Note:

  • While getCurrentPosition will receive only one Location, the plugin does request multiple location samples which will all be provided to the onLocation event-listener. You can detect these samples via Location.sample == true.

watchPosition

• watchPosition(
      cb: (location: Location) => void,
      options?: CurrentPositionRequest,
  ): Subscription

  Start a stream of continuous location-updates. The native code will persist the fetched location to its SQLite database just as any other location (If the SDK is currently [[State.enabled]]) in addition to POSTing to your configured [[Config.url]] (if you've enabled the HTTP features).

  ⚠️ Warning: watchPosition is not recommended 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. The SDK's primary Philosophy of Operation does not require watchPosition.

  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 in the background, consuming battery.

  Parameters

  • cb: (location: Location) => void
  • Optionaloptions: CurrentPositionRequest

  Returns Subscription

  Example

  onResume() {
    // Start watching position while app in foreground.
    BackgroundGeolocation.watchPosition((location) => {
      console.log("[watchPosition] -", location);
    }, (errorCode) => {
      console.log("[watchPosition] ERROR -", errorCode);
    }, {
      interval: 1000
    })
  }
  
  onSuspend() {
    // Halt watching position when app goes to background.
    BackgroundGeolocation.stopWatchPosition();
  }
  Copy

OptionalstopWatchPosition

• stopWatchPosition?(sub?: Subscription): void

  Stop watch-position updates initiated from watchPosition.

  Parameters

  • Optionalsub: Subscription

  Returns void

  Example

  onResume() {
    // Start watching position while app in foreground.
    BackgroundGeolocation.watchPosition((location) => {
      console.log("[watchPosition] -", location);
    }, (errorCode) => {
      console.log("[watchPosition] ERROR -", errorCode);
    }, {
     interval: 1000
    })
  }
  
  onSuspend() {
    // Halt watching position when app goes to background.
    BackgroundGeolocation.stopWatchPosition();
  }
  Copy

  ℹ️ See also:

  • watchPosition

resetOdometer

• resetOdometer(): Promise<number>

  Initialize the odometer to 0.

  Returns Promise<number>

  Example

  BackgroundGeolocation.resetOdometer().then((location) => {
    // This is the location where odometer was set at.
    console.log("[setOdometer] success: ", location);
  });
  Copy

  ⚠️ Note:

  • resetOdometer will internally perform a getCurrentPosition in order the record to exact location where odometer was set.
  • resetOdometer is the same as .setOdometer(0)

setOdometer

• setOdometer(value: number): Promise<number>

  Initialize the odometer to any arbitrary value.

  Parameters

  • value: number

  Returns Promise<number>

  Example

  BackgroundGeolocation.setOdometer(1234.56).then((location) => {
    // This is the location where odometer was set at.
    console.log("[setOdometer] success: ", location);
  });
  Copy

  ⚠️ Note:

  • setOdometer will internally perform a getCurrentPosition in order to record the exact location where odometer was set.

getOdometer

• getOdometer(): Promise<number>

  Retrieve the current distance-traveled ("odometer").

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

  Returns Promise<number>

  Example

  let odometer = await BackgroundGeolocation.getOdometer();
  Copy

  ℹ️ See also:

  • LocationFilter.odometerAccuracyThreshold.
  • resetOdometer / setOdometer.

  ⚠️ Warning:

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

getProviderState

• getProviderState(): Promise<ProviderChangeEvent>

  Retrieves the current state of location-provider authorization.

  ℹ️ See also:

  • You can also listen for changes in location-authorization using the event onProviderChange.

  Returns Promise<ProviderChangeEvent>

  Example

  let providerState = await BackgroundGeolocation.getProviderState();
  console.log("- Provider state: ", providerState);
  Copy

requestPermission

• requestPermission(): Promise<AuthorizationStatus>

  Manually request location permission from the user with the configured GeoConfig.locationAuthorizationRequest.

  The method will resolve successful if either WhenInUse or Always is authorized, regardless of GeoConfig.locationAuthorizationRequest. Otherwise an error will be returned (eg: user denies location permission).

  If the user has already provided authorization for location-services, the method will resolve successfully immediately.

  If iOS has already presented the location authorization dialog and the user has not currently authorized your desired GeoConfig.locationAuthorizationRequest, the SDK will present an error dialog offering to direct the user to your app's Settings screen.

  • To disable this behaviour, see GeoConfig.disableLocationAuthorizationAlert.
  • To customize the text on this dialog, see GeoConfig.locationAuthorizationAlert.

  ⚠️ Note:

  • The SDK will already request permission from the user when you execute start, startGeofences, getCurrentPosition, etc. You do not need to explicitly execute this method with typical use-cases.

  Returns Promise<AuthorizationStatus>

  Example

  async componentDidMount() {
    // Listen to onProviderChange to be notified when location authorization changes occur.
    BackgroundGeolocation.onProviderChange((event) => {
      console.log('[providerchange]', event);
    });
  
    // First ready the plugin with your configuration.
    let state = await BackgroundGeolocation.ready({
      locationAuthorizationRequest: 'Always'
    });
  
    // Manually request permission with configured locationAuthorizationRequest.
    try {
      int status = await BackgroundGeolocation.requestPermission();
      console.log('[requestPermission] success: ', status);
    } catch(status) {
      console.warn('[requestPermission] FAILURE: ', status);
    }
  }
  Copy

  ℹ️ See also:

  • GeoConfig.locationAuthorizationRequest
  • GeoConfig.disableLocationAuthorizationAlert
  • GeoConfig.locationAuthorizationAlert
  • AppConfig.backgroundPermissionRationale (**Android+*)
  • requestTemporaryFullAccuracy (iOS 14+)

requestTemporaryFullAccuracy

• requestTemporaryFullAccuracy(purposeKey: string): Promise<AccuracyAuthorization>

  [iOS 14+] iOS 14 has introduced a new [Precise: On] switch on the location authorization dialog allowing users to disable high-accuracy location.

  The method requestTemporaryFullAccuracy (Apple docs) will allow you to present a dialog to the user requesting temporary full accuracy for the lifetime of this application run (until terminate).

  

  Configuration — Info.plist

  In order to use this method, you must configure your Info.plist with the Dictionary key: Privacy - Location Temporary Usage Description Dictionary

  

  The keys of this Dictionary (eg: Delivery) are supplied as the first argument to the method. The value will be printed on the dialog shown to the user, explaing the purpose of your request for full accuracy.

  If the dialog fails to be presented, an error will be thrown:

  • The Info.plist file doesn’t have an entry for the given purposeKey value.
  • The app is already authorized for full accuracy.
  • The app is in the background.

  

  Note: Android and older versions of iOS < 14 will return [[BackgroundGeolocation.ACCURACY_AUTHORIZATION_FULL]].

  Parameters

  • purposeKey: string

  Returns Promise<AccuracyAuthorization>

  Example

  BackgroundGeolocation.onProviderChange((event) => {
    if (event.accuracyAuthorization == BackgroundGeolocation.ACCURACY_AUTHORIZATION_REDUCED) {
      // Supply "Purpose" key from Info.plist as 1st argument.
      BackgroundGeolocation.requestTemporaryFullAccuracy("Delivery").then((accuracyAuthorization) => {
        if (accuracyAuthorization == BackgroundGeolocation.ACCURACY_AUTHORIZATION_FULL) {
          console.log('[requestTemporaryFullAccuracy] GRANTED: ', accuracyAuthorization);
        } else {
          console.log('[requestTemporaryFullAccuracy] DENIED: ', accuracyAuthorization);
        }
      }).catch((error) => {
        console.warn("[requestTemporaryFullAccuracy] FAILED TO SHOW DIALOG: ", error);
      });
    }
  });
  Copy

  See also:

  • ProviderChangeEvent.accuracyAuthorization.
  • What's new in iOS 14 CoreLocation

addGeofence

• addGeofence(geofence: Geofence): Promise<boolean>

  Adds a Geofence to be monitored by the native Geofencing API.

  Parameters

  • geofence: Geofence

  Returns Promise<boolean>

  Example

  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
    }
  }).then((success) => {
    console.log("[addGeofence] success");
  }).catch((error) => {
    console.log("[addGeofence] FAILURE: ", error);
  });
  Copy

  ℹ️ Note:

  • If a geofence(s) already exists with the configured Geofence.identifier, the previous one(s) will be deleted before the new one is inserted.
  • When adding multiple, it's about 10 times faster to use addGeofences instead.
  • 📘 Geofencing Guide

addGeofences

• addGeofences(geofences: Geofence[]): Promise<boolean>

  Adds a list of Geofence to be monitored by the native Geofencing API.

  Parameters

  • geofences: Geofence[]

  Returns Promise<boolean>

  Example

  let geofences = [{
    identifier: "foo",
    radius: 200,
    latitude: 45.51921926,
    longitude: -73.61678581,
    notifyOnEntry: true
  },
    identifier: "bar",
    radius: 200,
    latitude: 45.51921926,
    longitude: -73.61678581,
    notifyOnEntry: true
  }];
  
  BackgroundGeolocation.addGeofences(geofences);
  Copy

  ℹ️ Note:

  • If a geofence(s) already exists with the configured Geofence.identifier, the previous one(s) will be deleted before the new one is inserted.
  • 📘 Geofencing Guide
  • addGeofence

removeGeofence

• removeGeofence(identifier: string): Promise<boolean>

  Removes a Geofence having the given Geofence.identifier.

  Parameters

  • identifier: string

  Returns Promise<boolean>

  Example

  BackgroundGeolocation.removeGeofence("Home").then((success) => {
    console.log("[removeGeofence] success");
  }).catch((error) => {
    console.log("[removeGeofence] FAILURE: ", error);
  });
  Copy

  ℹ️ See also:

  • 📘 Geofencing Guide

removeGeofences

• removeGeofences(identifiers?: string[]): Promise<boolean>

  Destroy all Geofence

  Parameters

  • Optionalidentifiers: string[]

  Returns Promise<boolean>

  Example

  BackgroundGeolocation.removeGeofences();
  Copy

  ℹ️ See also:

  • 📘 Geofencing Guide

getGeofences

• getGeofences(): Promise<Geofence[]>

  Fetch a list of all Geofence in the SDK's database. If there are no geofences being monitored, you'll receive an empty Array.

  Returns Promise<Geofence[]>

  Example

  let geofences = await BackgroundGeolocation.getGeofences();
  console.log("[getGeofences: ", geofences);
  Copy

  ℹ️ See also:

  • 📘 Geofencing Guide

getGeofence

• getGeofence(identifier: string): Promise<Geofence>

  Fetch a single Geofence by identifier from the SDK's database.

  Parameters

  • identifier: string

  Returns Promise<Geofence>

  Example

  let geofence = await BackgroundGeolocation.getGeofence("HOME");
  console.log("[getGeofence] ", geofence);
  Copy

  ℹ️ See also:

  • 📘 Geofencing Guide

geofenceExists

• geofenceExists(identifier: string): Promise<boolean>

  Determine if a particular geofence exists in the SDK's database.

  Parameters

  • identifier: string

  Returns Promise<boolean>

  Example

  let exists = await BackgroundGeolocation.geofenceExists("HOME");
  console.log("[geofenceExists] ", exists);
  Copy

  ℹ️ See also:

  • 📘 Geofencing Guide

startSchedule

• startSchedule(): Promise<void>

  Initiate the configured AppConfig.schedule.

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

  To halt scheduled tracking, use stopSchedule.

  Returns Promise<void>

  Example

  BackgroundGeolocation.startSchedule.then((state) => {
    console.log("[startSchedule] success: ", state);
  })
  Copy

  ℹ️ See also:

  • AppConfig.schedule
  • startSchedule

stopSchedule

• stopSchedule(): Promise<void>

  Halt scheduled tracking.

  Returns Promise<void>

  Example

  BackgroundGeolocation.stopSchedule.then((state) => {
    console.log("[stopSchedule] success: ", state);
  })
  Copy

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

  Example

  // Later when you want to stop the Scheduler (eg: user logout)
  await BackgroundGeolocation.stopSchedule().then((state) => {
    if (state.enabled) {
      BackgroundGeolocation.stop();
    }
  })
  Copy

  ℹ️ See also:

  • startSchedule

setLogLevel

• setLogLevel(level: LogLevel): Promise<void>

  Sets the LoggerConfig.logLevel.

  Parameters

  • level: LogLevel

  Returns Promise<void>

setLogPersist

• setLogPersist(mode: PersistMode): Promise<void>

  Parameters

  • mode: PersistMode

  Returns Promise<void>

getDeviceInfo

• getDeviceInfo(): Promise<DeviceInfo>

  Returns the device information.

  Returns Promise<DeviceInfo>

  Example

  const deviceInfo = await BackgroundGeolocation.getDeviceInfo();
  console.log(deviceInfo);
  Copy

getSensors

• getSensors(): Promise<Sensors>

  Returns the presence of device sensors accelerometer, gyroscope, magnetometer

  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 severely degraded and highly inaccurate.

  Returns Promise<Sensors>

  Example

  let sensors = await BackgroundGeolocation.sensors;
  console.log(sensors);
  Copy

isPowerSaveMode

• isPowerSaveMode(): Promise<boolean>

  Fetches the state of the operating-system's "Power Saving" mode.

  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 from the event onPowerSaveChange.

  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%).

  

  Returns Promise<boolean>

  Example

  let isPowerSaveMode = await BackgroundGeolocation.isPowerSaveMode;
  Copy

destroyLocations

• destroyLocations(): Promise<void>

  Remove all records in SDK's SQLite database.

  Returns Promise<void>

  Example

  let success = await BackgroundGeolocation.destroyLocations();
  Copy

destroyLocation

• destroyLocation(uuid: string): Promise<void>

  Destroy a single location by Location.uuid

  Parameters

  • uuid: string

  Returns Promise<void>

  Example

  await BackgroundGeolocation.destroyLocation(location.uuid);
  Copy

getLocations

• getLocations(): Promise<Object[]>

  Retrieve a List of Location currently stored in the SDK's SQLite database.

  Returns Promise<Object[]>

  Example

  let locations = await BackgroundGeolocation.getLocations();
  Copy

getCount

• getCount(): Promise<number>

  Retrieve the count of all locations current stored in the SDK's SQLite database.

  Returns Promise<number>

  Example

  let count = await BackgroundGeolocation.getCount();
  Copy

sync

• sync(): Promise<Object[]>

  Manually execute upload to configured HttpConfig.url of all Location records currently stored in the SDK's SQLite database.

  If the plugin is configured for HTTP with an HttpConfig.url and HttpConfig.autoSync false, the sync method will initiate POSTing the locations currently stored in the native SQLite database to your configured HttpConfig.url. When your HTTP server returns a response of 200 OK, that record(s) in the database will be DELETED.

  If you configured HttpConfig.batchSync true, all the locations will be sent to your server in a single HTTP POST request, otherwise the plugin will execute an HTTP post for each Location in the database (REST-style). Your callback will be executed and provided with a List of all the locations from the SQLite database. If you configured the plugin for HTTP (by configuring a HttpConfig.url), your callback will be executed after all the HTTP request(s) have completed. If the plugin failed to sync to your server (possibly because of no network connection), the failure callback will be called with an error message. If you are not using the HTTP features, sync will delete all records from its SQLite database.

  Returns Promise<Object[]>

  Example

  BackgroundGeolocation.sync((records) => {
    console.log("[sync] success: ", records);
  }).catch((error) => {
    console.log("[sync] FAILURE: ", error);
  });
  
  Copy

  ℹ️ For more information, see the [[HttpEvent | HTTP Guide]]

startBackgroundTask

• startBackgroundTask(): Promise<number>

  Sends a signal to OS that you wish to perform a long-running task.

  The OS will keep your running in the background and not suspend it until you signal completion with the stopBackgroundTask method. Your callback will be provided with a single parameter taskId which you will send to the stopBackgroundTask method.

  Returns Promise<number>

  Example

  onLocation(location) {
    console.log("[location] ", location);
  
    // Perform some long-running task (eg: HTTP request)
    BackgroundGeolocation.startBackgroundTask().then((taskId) => {
      performLongRunningTask.then(() => {
        // When your long-running task is complete, signal completion of taskId.
        BackgroundGeolocation.stopBackgroundTask(taskId);
      }).catch(error) => {
        // Be sure to catch errors:  never leave you background-task hanging.
        console.error(error);
        BackgroundGeolocation.stopBackgroundTask();
      });
    });
  }
  Copy

  iOS: The iOS implementation uses beginBackgroundTaskWithExpirationHandler

  ⚠️ 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 stopBackgroundTask your taskId to prevent the OS from force-killing your application.

  Logging of iOS background tasks looks like this:

  ✅-[BackgroundTaskManager createBackgroundTask] 1
  .
  .
  .
  
  ✅-[BackgroundTaskManager stopBackgroundTask:]_block_invoke 1 OF (
      1
  )
  Copy

  Android:

  The Android implementation launches a WorkManager task.

  ⚠️ The Android plugin imposes a limit of 3 minutes for your background-task before it automatically FORCE KILLs it.

  Logging for Android background-tasks looks like this (when you see an hourglass ⏳ icon, a foreground-service is active)

   I TSLocationManager: [c.t.l.u.BackgroundTaskManager onStartJob] ⏳ startBackgroundTask: 6
   .
   .
   .
   I TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task stop] ⏳ stopBackgroundTask: 6
  Copy

stopBackgroundTask

• stopBackgroundTask(taskId: number): Promise<void>

  Signal completion of startBackgroundTask

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

  Parameters

  • taskId: number

  Returns Promise<void>

  Example

  BackgroundGeolocation.startBackgroundTask().then((taskId) => {
    // Perform some long-running task (eg: HTTP request)
    performLongRunningTask.then(() => {
      // When your long-running task is complete, signal completion of taskId.
      BackgroundGeolocation.stopBackgroundTask(taskId);
    });
  });
  Copy

findOrCreateTransistorAuthorizationToken

• findOrCreateTransistorAuthorizationToken(
      orgname: string,
      username: string,
      url?: string,
  ): Promise<TransistorAuthorizationToken>

  Find or create a Transistor authorization token.

  See TransistorAuthorizationService for more information.

  Parameters

  • orgname: string
  • username: string
  • Optionalurl: string

  Returns Promise<TransistorAuthorizationToken>

destroyTransistorAuthorizationToken

• destroyTransistorAuthorizationToken(url: string): Promise<void>

  Destroy a Transistor authorization token.

  See TransistorAuthorizationService for more information.

  Parameters

  • url: string

  Returns Promise<void>

onLocation

• onLocation(
      cb: (location: Location) => void,
      onError?: (err: LocationError) => void,
  ): Subscription

  Subscribe to location events.

  Every location recorded by the SDK is provided to your callback, including those from [[onMotionChange]], [[getCurrentPosition]] and [[watchPosition]].

  Parameters

  • cb: (location: Location) => void
  • OptionalonError: (err: LocationError) => void

  Returns Subscription

  Example

  const subscription = BackgroundGeolocation.onLocation((location) => {
    console.log("[onLocation] success: ", location);
  }, (error) => {
    console.log("[onLocation] ERROR: ", error);
  });
  Copy

  Error Codes

  If the native location API fails to return a location, the failure callback will be provided a [[LocationError]].

  ⚠️ Note Location.sample:

  When performing a onMotionChange 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 callback, 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 callback via location.sample == true. If you're manually POSTing location to your server, you should ignore these locations.

  location

onMotionChange

• onMotionChange(cb: (event: MotionChangeEvent) => void): Subscription

  Subscribe to motionchange events.

  Your callback will be executed each time the device has changed-state between MOVING or STATIONARY.

  Parameters

  • cb: (event: MotionChangeEvent) => void

  Returns Subscription

  Example

  const subscription = BackgroundGeolocation.onMotionChange((event:MotionChangeEvent) => {
    if (event.isMoving) {
       console.log("[onMotionChange] Device has just started MOVING ", event.location);
    } else {
       console.log("[onMotionChange] Device has just STOPPED:  ", event.location);
    }
  });
  Copy

  ---

  ⚠️ Warning: autoSyncThreshold

  If you've configured [[Config.autoSyncThreshold]], it will be ignored during a onMotionChange event — all queued locations will be uploaded, since:

  • If an onMotionChange event fires into the moving state, the device may have been sitting dormant for a long period of time. The plugin is eager to upload this state-change to the server as soon as possible.
  • If an onMotionChange event fires into the stationary state, the device may be about to lie dormant for a long period of time. The plugin is eager to upload all queued locations to the server before going dormant.

  ---

  ℹ️ See also:

  • GeoConfig.stopTimeout
  • 📘 Philosophy of Operation

  motionchange

onGeofence

• onGeofence(cb: (event: GeofenceEvent) => void): Subscription

  Subscribe to Geofence transition events.

  Your supplied callback will be called when any monitored geofence crossing occurs.

  Parameters

  • cb: (event: GeofenceEvent) => void

  Returns Subscription

  Example

  const subscription = BackgroundGeolocation.onGeofence((event) => {
    console.log("[onGeofence] ", event);
  });
  Copy

  __ℹ️ See also:

  • 📘 Geofencing Guide

  geofence

onGeofencesChange

• onGeofencesChange(cb: (event: GeofencesChangeEvent) => void): Subscription

  Subscribe to changes in actively monitored geofences.

  Fired when the list of monitored-geofences changed. The BackgroundGeolocation SDK 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 GeoConfig.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, that the plugin will fire the onGeofencesChange event.

  Parameters

  • cb: (event: GeofencesChangeEvent) => void

  Returns Subscription

  Example

  const subscription = BackgroundGeolocation.onGeofencesChange((event) => {
    let on = event.on;     //<-- new geofences activated.
    let off = event.off; //<-- geofences that were just de-activated.
  
    // Create map circles
    on.forEach((geofence) => {
      createGeofenceMarker(geofence)
    });
  
    // Remove map circles
    off.forEach((identifier) => {
      removeGeofenceMarker(identifier);
    }
  });
  Copy

  ℹ️ See also:

  • 📘 Geofencing Guide geofenceschange

onActivityChange

• onActivityChange(cb: (event: MotionActivityEvent) => void): Subscription

  Subscribe to changes in motion activity.

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

  Android: Android MotionActivityEvent.confidence always reports 100%.

  Parameters

  • cb: (event: MotionActivityEvent) => void

  Returns Subscription

  Example

  const subscription = BackgroundGeolocation.onActivityChange((event) => {
    console.log("[onActivityChange] ", event);
  });
  Copy

  activitychange

onProviderChange

• onProviderChange(cb: (event: ProviderChangeEvent) => void): Subscription

  Subscribe to changes in device's location-services configuration / authorization.

  Your callback fill be executed whenever a change in the state of the device's Location Services has been detected. eg: "GPS ON", "WiFi only".

  Parameters

  • cb: (event: ProviderChangeEvent) => void

  Returns Subscription

  Example

  const subscription = BackgroundGeolocation.onProviderChange((event) => {
    console.log("[onProviderChange: ", event);
  
    switch(event.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;
    }
  });
  Copy

  ℹ️ See also:

  • You can explicitly request the current state of location-services using [[getProviderState]].

  ⚠️ Note:

  • The plugin always force-fires an onProviderChange event whenever the app is launched (right after the ready method is executed), regardless of current state, so you can learn the the current state of location-services with each boot of your application.

  providerchange