[New Feature] Android Headless Mode

Transistor Software
2 min readOct 19, 2018

On Android, when you terminate your app with the BackgroundGeolocation plugin configured with stopOnTerminate: false, your Javascript code is completely terminated — only the plugin’s native Android background service continues running. If you’ve configured the plugin with an url, its Android background Service will continue posting locations to your server.

But what if you need to implement some custom business logic in the “headless” state, such as posting a local notification or executing getCurrentPositionin a heartbeat event?

The BackgroundGeolocation plugin for React Native and Cordova now provides a mechanism for you to implement your own custom code to handle all the plugin’s events while in the “Headless” state (heartbeat, location, motionchange, geofence, etc).

React Native

For React Native users, you get the best implementation because the plugin implements the React Native Headless JS mechanism. This allows you to implement your “Headless Task” in the Javascript environment. No native Android code required for you!

Try it out

With your React Native debugger connected, terminate your app and observe log messages arriving from your HeadlessTask.

For more information, see the React Native Background Geolocation Wiki Android Headless Mode.

Cordova / Ionic

For Cordova users, unfortunately the Cordova platform provides no such mechanism to execute Javascript code in the Headless state, so you’ll have to implement your Headless code in the native Android environment with Java code. Don’t be daunted — it’s really not that difficult.

Step 1

First, create a Java file named BackgroundGeolocationHeadlessTask.java in your src folder (eg: src/android/BackgroundGeolocationHeadlessTask.java). This file must extend HeadlessTask and implement HeadlessTask.Receiver exactly as shown below:

Step 2

Next, you need to instruct Cordova to copy your custom source-file file into the background-geolocation plugin’s src-tree. In your Cordova config.xml, add the following element to copy your custom source-file:

Step 3

Finally, configure the plugin with enableHeadless: true:

Try it out

While observing $ adb logcat, terminate your app and observe log messages arriving from your custom BackgroundGeolocationHeadlessTask. With just a small handful of Java code, you’re now receiving all events emitted by the plugin while in the Headless state with your app terminated.

The entire BackgroundGeolocation API is available to you in the native environment — anything you can do in Javascript, you can do in the native environment. In fact, the entire Android API universe is available to you. If you have any experience with native Android development, this won’t be a difficult task for you. If you have no experience with Java, we can assist in writing your own custom tasks in a couple of hours.

For more information, see the Cordova Background Geolocation Wiki Android Headless Mode.



Transistor Software

Creator of Background Geolocation SDK. Professional plugin developers — geolocation specialists. https://www.transistorsoft.com