Background Geolocation v3

Transistor Software
4 min readMay 16, 2019


Version 3 of the Background Geolocation SDK for Cordova, React Native and Flutter (v1) is a significant refactor of the SDK’s Android Service architecture.

The Foreground Service

In the past, when BackgroundGeolocation.start() was executed, the Android SDK would launch a foreground-service (along with its required persistent notification). The foreground-service would remain running with its persistent notification until BackgroundGeolocation.stop() was executed.

One of the most common complaints, of course, was “How do I hide that notification?”

“Well, you can’t”, we would answer.

However, a way has been discovered to at least run the foreground-service only when the SDK is in the moving state, when the user is walking or driving, for example. But when the device is completely stationary, there is no longer a foreground-service running. This is exactly how popular tracking apps, such as Life360, operate.

Also driving this change was a report from a customer who found the long-running foreground-service was being terminated after five days on a Pixel running Android 9. It wasn’t an easy case to quickly reproduce, but it was in fact reproduced here in the lab. It seems that Android clearly does not want long-running foreground-services.

Android Significant Location Changes

In the past, only the iOS SDK implemented the option useSignificantChangesOnly. iOS has a built-in option for its Location API called Significant Location Changes” (SLC). Engaging the SLC option with useSignificantChangesOnly: true, your app will be provided only periodic location updates, typically every 500–1000 meters but significantly less power will be consumed.

Using SLC allows an iOS app to be submitted to the app store without the Background Mode: “location”, which Apple is very strict about granting only to those apps which clearly demonstrate a use-case for it.

The useSignificantChangesOnly option is now available for Android and no foreground-service will be launched at all.

useSignificantChangesOnly: true
useSignificantChangesOnly: false (default)

Android Custom Notification Layouts

In December, 2018, we received a feature-request to be able to add custom buttons to the Android SDK’s foreground-service notification.

Custom Notification Layouts have now been implemented! For setup instructions, see the Wiki for Cordova, React Native or Flutter to create any layout you wish. A new event-listener onNotificationAction allows you to respond to clicks upon custom buttons, even in the headless-state.

Android background-tasks

Before v3 (v1 for Flutter), only the iOS SDK had an implementation for startBackgroundTask. An iOS “background-task” is a signal to the OS that the app wants to perform a long-running task while the app is in the background, an HTTP request for example. Typically, when an iOS app moves to the background, the OS immediately suspends the app (unless a Background Mode, such as location-updates, is engaged). An iOS background-task provides an app exactly 180 seconds of running-time before the app will be forcibly suspended.

With the latest version of the Background Geolocation SDK, Android now has an implementation for startBackgroundTask.

The Android implementation will launch a foreground-service to ensure the work in your callback function gets completed before your app is suspended in the background. Signalling BackgroundGeolocation.finish(taskId) will terminate the service.

For nearly six years, the Background Geolocation SDK for Cordova, React Native and Flutter has continued to evolve and respond to the latest changes in iOS and Android.



Transistor Software

Creator of Background Geolocation SDK. Professional plugin developers — geolocation specialists.