Class BackgroundGeolocation

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);
});

ℹ️ 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

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);

ℹ️ 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

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.

example

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

example

await BackgroundGeolocation.destroyLocation(location.uuid);

example

let success = await BackgroundGeolocation.destroyLocations();

deprecated

Use Logger.destroyLog.

example

await BackgroundGeolocation.destroyTransistorAuthorizationToken();

ℹ️ See also:

• findOrCreateTransistorAuthorizationToken

deprecated

Use Logger.emailLog.

To learn how to upload locations to the Transistor Demo Server, see TransistorAuthorizationToken.

This token is typically provided to Config.transistorAuthorizationToken when first configuring the SDK with ready.

Params

@param {String} orgname

Represents a "company" or "organization"; a container for posting locations from multiple devices to the same account. orgname is used for accessing your device results in web app, eg: http://tracker.transistorsoft.com/my-organization-name.

@param {String} username

Appended to the DeviceInfo.model as a means of creating a consistent and unique device identifier. For example:

• Pixel 3a-my-username
• A310-my-username
• iPhone 11,3-my-username

@param {String} url [http://tracker.transistorsoft.com]

The server to register with and receive authentication tokens from. Defaults to http://tracker.transistorsoft.com. If you have a local instance of background-geolocation-console running on your localhost, you would provide the ip address of your server, eg: http://192.168.0.100:9000.

---

When the SDK receives the TransistorAuthorizationToken from url, it will be cached in persistant-storage within the native code. If the SDK doesn"t find a cached token on the client, it will automatically register for one from url, using the provided orgname and username. Otherwise, the cached token will be immediately returned.

example

let orgname      = "my-company-name";
let username     = "my-username";

let token = await BackgroundGeolocation.findOrCreateTransistorAuthorizationToken(orgname, username);

BackgroundGeolocation.ready({
  transistorAuthorizationToken: token
});

ℹ️ See also:

• destroyTransistorAuthorizationToken
• Config.transistorAuthorizationToken

alias

stopBackgroundTask

deprecated

example

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

ℹ️ See also:

• 📘 Geofencing Guide

example

let count = await BackgroundGeolocation.getCount();

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.

break

Options

See CurrentPositionRequest.

Error Codes

See LocationError.

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
  }
});

⚠️ 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.

example

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

ℹ️ See also:

• 📘 Geofencing Guide

example

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

ℹ️ See also:

• 📘 Geofencing Guide

example

let locations = await BackgroundGeolocation.getLocations();

deprecated

Use Logger.getLog.

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:

example

let odometer = await BackgroundGeolocation.getOdometer();

ℹ️ See also:

• desiredOdometerAccuracy.
• 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.

ℹ️ See also:

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

example

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

break

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.

For devices which are missing any of these sensors, you can increase the motion-detection sensitivity by decreasing minimumActivityRecognitionConfidence.

example

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

example

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

break

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

example

let isPowerSaveMode = await BackgroundGeolocation.isPowerSaveMode;

Fired when Authorization.refreshUrl responds, either successfully or not. If successful, AuthorizationEvent.success will be true and AuthorizationEvent.response will contain the decoded JSON response returned from the server.

If authorization failed, AuthorizationEvent.error will contain the error message.

example

const subscription = BackgroundGeolocation.onAuthorization((event) => {
  if (event.success) {
    console.log("[authorization] ERROR: ", event.error);
  } else {
    console.log("[authorization] SUCCESS: ", event.response);
  }
});

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.

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);
});

⚠️ Warning: You must call .ready(confg) once and only once, each time your app is launched.

• Do not hide the call to #ready 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 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
});

⚠️ 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).

example

const BackgroundGeolocationHeadlessTask = async (event) => {
  let params = event.params;
   console.log("[BackgroundGeolocation HeadlessTask] -", event.name, params);

   switch (event.name) {
     case "heartbeat":
       // Use await for async tasks
       let location = await BackgroundGeolocation.getCurrentPosition({
         samples: 1,
         persist: false
       });
       console.log("[BackgroundGeolocation HeadlessTask] - getCurrentPosition:", location);
       break;
   }
}

BackgroundGeolocation.registerHeadlessTask(BackgroundGeolocationHeadlessTask);

ℹ️ See also:

• 📘 Android Headless Mode.

example

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

ℹ️ See also:

• 📘 Geofencing Guide

example

BackgroundGeolocation.removeGeofences();

ℹ️ See also:

• 📘 Geofencing Guide

deprecated.

Use Subscription returned from BackgroundGeolocation.onXXX to remove listeners.

example

const subscription = BackgroundGeolocation.onLocation((location) => {
  console.log('[onLocation]', location);
});
.
.
.
// Remove listener
subscription.remove();

---

⚠️ [Deprecated]

Removes an event listener. You must supply the type of event to remove in addition to a reference to the exact function you used to subscribe to the event.

Event
location
motionchange
activitychange
providerchange
geofence
geofenceschange
heartbeat
http
powersavechange
schedule
connectivitychange
enabledchange

example

const locationHandler = (location) => {
  console.log("[location] - ", location)
}
BackgroundGeolocation.onLocation(locationHandler)
.
.
// Remove the listener providing a reference to the original callback.
BackgroundGeolocation.removeListener("location", locationHandler)

Calls Subscription.remove on all subscriptions.

example

BackgroundGeolocation.removeListeners();

The method will resolve successful if either WhenInUse or Always is authorized, regardless of Config.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 Config.locationAuthorizationRequest, the SDK will present an error dialog offering to direct the user to your app's Settings screen.

• To disable this behaviour, see Config.disableLocationAuthorizationAlert.
• To customize the text on this dialog, see Config.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.

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);
  }
}

ℹ️ See also:

• Config.locationAuthorizationRequest
• Config.disableLocationAuthorizationAlert
• Config.locationAuthorizationAlert
• Config.backgroundPermissionRationale (Android 11+)
• requestTemporaryFullAccuracy (iOS 14+)

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.

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);
    });
  }
});

See also:

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

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

example

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

⚠️ 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.

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

example

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

example

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

⚠️ Note:

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

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 schedule, this method will override that schedule and engage tracking immediately.

example

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

ℹ️ See also:

• stop
• startGeofences
• 📘 Philosophy of Operation

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.

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();
    });
  });
}

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
)

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

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.

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();
});

ℹ️ See also:

• stop
• 📘 Geofencing Guide

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

To halt scheduled tracking, use stopSchedule.

example

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

ℹ️ See also:

• schedule
• startSchedule

example

BackgroundGeolocation.stop();

⚠️ Note:

If you've configured a 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();

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.

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);
  });
});

example

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

⚠️ 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();
  }
})

ℹ️ See also:

• startSchedule

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();
}

ℹ️ See also:

• stopWatchPosition

If the plugin is configured for HTTP with an Config.url and autoSync false, the sync method will initiate POSTing the locations currently stored in the native SQLite database to your configured Config.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 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 Config.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.

example

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

ℹ️ For more information, see the HTTP Guide

deprecated

Use Config.transistorAuthorizationToken

⚠️ 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.

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();
}