React-Native Background Location Module For Android

This post will cover a topic that has been key in many applications and will focus on a solution working fully on the background and the most interesting part of all: working from Android 4.4 (SDK 19) to the most recent version at the time of writing which is Android Oreo (SDK 27). The purpose of the solution is not for real-time tracking, it’s to track a user location in small intervals (e.g. 5 or 10 minutes), but it could be taken to an extreme where you could try to get location updates on a much smaller interval (e.g. 1 minute). Android 8 and its particularities With Oreo, Google wanted to bring a few changes to the table, mainly regarding background services and background location. The changes can be read with more detail in these two pages: Background Execution Limits Background Location Limits But I will give you a summary of what they are. What motivated Google to do these changes was and by third party apps, or in other words, they want to better control their operating system environment by giving developers a more controlled freedom to develop. Which means we are not able to run background tasks as freely as we were running them in previous versions of Android. power resource consumption This change makes sense in order to deliver a better user experience to their target market. After all, we don’t want to have an app stealing all our smartphone resources because it’s running too many background tasks or simply isn’t handling code well which in turn may destroy not only processing resources but memory as well 🙂. With new background service limitations, what Google suggests in their “ ” page is: Background Execution Limits In most cases, apps can work around these limitations by using JobScheduler jobs. This approach lets an app arrange to perform work when the app isn't actively running, but still gives the system the leeway to schedule these jobs in a way that doesn't affect the user experience. This seems a very good suggestion, but there are a few . gotchas Gotcha #1 JobScheduler was added in SDK 21 aka Android 5, so it’s not really an option if we’re targeting Android 4.4. Gotcha #2 Even if we were targeting Android 5 and above, there would be a slight problem. Jobs that are scheduled to run by JobScheduler can only run at a minimum interval of 15 minutes, which brings us to our article title “ ” and we want to design a solution to get location updates on our users. 15 minutes is a big interval if we are talking about location, so we need to figure out a different way to get the results we want. React-Native Background Location Purpose of the solution So what we are going to build is just a small part of a big project that is designed for truck drivers to use while they are performing their shipment deliveries. The purpose is for the company that employs the truck driver and for the client to be able to know where the driver and consequently their shipment is. This feature has a few : requirements Tracking can have an interval of 5–10 minutesTracking must be active with the app in the backgroundPower consumption should be kept to the minimumMemory leaks and memory usage should be non existent / low respectively Given these guidelines we definitely need to look for background services APIs in Android. The first logical choice to look at is WorkManager API. WorkManager API At first sight this API seems to be perfect for our case since it even supports devices with Android 4.0 and can create background tasks even when the phone restarts. It’s pretty flexible since it does a ton of work for you but it has a huge gotcha which is: . it’s a dependency in AndroidX So for those of you who don’t know, AndroidX is a new support library supplied by the Android ecosystem in order to unify and provide newer APIs and packages for developers to use in their apps. The trick here is: . You can’t mix them both up since there will be naming collision when you are importing dependencies that are present in both support library providers. Many API’s fall under this problem. you either use dependencies under AndroidX or prior to AndroidX Another thing that I would like to point out is that the original project from which this solution derived is an enterprise level application done in react-native with 2 years of development on top of it and with many dependencies already installed. So migrating all the dependencies to AndroidX is pretty much impossible, since you would have to change every direct dependency under the app and every react-native project dependency in the project also. In summary, this API needs to be excluded, since in our particular case it couldn’t do the work it’s designed to do. What about the AlarmManager API? With API we are able to schedule background services to run on a specific interval defined by us with a minimal interval time of 1 minute, which is great! AlarmManager The main gotcha with this API is that it is not able to launch background services if the app itself is in the background, at least in Android 8 and above. This is a blocker if we want to make sure that our app is still tracking our user if the messaging or any other app is open and in the foreground. Although it doesn’t solve our problem entirely, it’s still a very useful API since it launches a new thread to run our services for us and we are able to cancel the alarms we schedule and closing the allocated threads that way. Enter Foreground Services With Foreground Services we are able to maintain a service running continuously on the background even when our app is not on the foreground. We are able to do this because our app will have an undismissable notification informing the user that it is still running although he might not be seeing it at the moment. Because our app is informing the user that it’s still running, Google allows it to do virtually any background task you want to do, which in our case is perfect! So the solution we are going to analyse involves a Foreground service, an API instance, an and a in order to get regular location updates and store them locally. AlarmManager IntentService BroadcastReceiver The Solution The final reproducible demo is available , and it’s a very small reproducible example of what we want to achieve. here First of all, our solution is based on a lot of native Java code, so from this point onward you can only implement this solution in case you have an ejected react-native app, which is something similar to when you create a react-native project with react-native init my-project . In order to use the smartphone’s location you naturally have to request permissions for this. This part is handled in the JS side, but it’s nothing major, just skim through the files in order to checkout what’s happening. First, let’s create our native module, in order to be able to initiate our native code from the JavaScript side. com.rnbglocation.location; android.content.BroadcastReceiver; android.content.Context; android.content.Intent; android.content.IntentFilter; androidx.core.content.ContextCompat; com.facebook.react.bridge.Arguments; com.facebook.react.bridge.ReactApplicationContext; com.facebook.react.bridge.ReactContext; com.facebook.react.bridge.ReactContextBaseJavaModule; com.facebook.react.bridge.ReactMethod; com.facebook.react.bridge.WritableMap; com.facebook.react.modules.core.DeviceEventManagerModule; com.google.gson.Gson; java.util.HashMap; java.util.Map; javax.annotation.Nonnull; javax.annotation.Nullable; com.rnbglocation.location.LocationForegroundService.LOCATION_EVENT_DATA_NAME; { String MODULE_NAME = ; String CONST_JS_LOCATION_EVENT_NAME = ; String CONST_JS_LOCATION_LAT = ; String CONST_JS_LOCATION_LON = ; String CONST_JS_LOCATION_TIME = ; Context mContext; Intent mForegroundServiceIntent; BroadcastReceiver mEventReceiver; Gson mGson; LocationModule( ReactApplicationContext reactContext) { (reactContext); mContext = reactContext; mForegroundServiceIntent = Intent(mContext, LocationForegroundService.class); mGson = Gson(); createEventReceiver(); registerEventReceiver(); } { ContextCompat.startForegroundService(mContext, mForegroundServiceIntent); } { mContext.stopService(mForegroundServiceIntent); } { Map constants = HashMap<>(); constants.put(CONST_JS_LOCATION_EVENT_NAME, LocationForegroundService.JS_LOCATION_EVENT_NAME); constants.put(CONST_JS_LOCATION_LAT, LocationForegroundService.JS_LOCATION_LAT_KEY); constants.put(CONST_JS_LOCATION_LON, LocationForegroundService.JS_LOCATION_LON_KEY); constants.put(CONST_JS_LOCATION_TIME, LocationForegroundService.JS_LOCATION_TIME_KEY); constants; } { MODULE_NAME; } { mEventReceiver = BroadcastReceiver() { { LocationCoordinates locationCoordinates = mGson.fromJson( intent.getStringExtra(LOCATION_EVENT_DATA_NAME), LocationCoordinates.class); WritableMap eventData = Arguments.createMap(); eventData.putDouble( LocationForegroundService.JS_LOCATION_LAT_KEY, locationCoordinates.getLatitude()); eventData.putDouble( LocationForegroundService.JS_LOCATION_LON_KEY, locationCoordinates.getLongitude()); eventData.putDouble( LocationForegroundService.JS_LOCATION_TIME_KEY, locationCoordinates.getTimestamp()); sendEventToJS(getReactApplicationContext(), LocationForegroundService.JS_LOCATION_EVENT_NAME, eventData); } }; } { IntentFilter eventFilter = IntentFilter(); eventFilter.addAction(LocationForegroundService.LOCATION_EVENT_NAME); mContext.registerReceiver(mEventReceiver, eventFilter); } { reactContext .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class) .emit(eventName, params); } } package import import import import import import import import import import import import import import import import import import static public , class LocationModule extends ReactContextBaseJavaModule implements LocationEventReceiver JSEventSender private static final "LocationManager" private static final "JS_LOCATION_EVENT_NAME" private static final "JS_LOCATION_LAT_KEY" private static final "JS_LOCATION_LON_KEY" private static final "JS_LOCATION_TIME_KEY" private private private private @Nonnull super new new @ReactMethod public void startBackgroundLocation () @ReactMethod public void stopBackgroundLocation () @Nullable @Override Map public getConstants () final new return @Nonnull @Override String public getName () return @Override public void createEventReceiver () new @Override public void onReceive (Context context, Intent intent) // if you actually want to send events to JS side, it needs to be in the "Module" @Override public void registerEventReceiver () new @Override public void sendEventToJS (ReactContext reactContext, String eventName, @Nullable WritableMap params) This is the first step to our Location feature. This is a common procedure for every native module you want to build for react native, you can follow more documentation . here The two most important parts in this file are the and interfaces. These were created to show two responsibilities of whatever class implements them respectively: LocationEventReceiver JSEventSender To receive the location updates through a .To send events to the JS side (with the location updates). BroadcastReceiver It’s important to note that if we want to send events to the JS side, we need to do the actual sending of the events in the React modules created by us, since the is needed to do this. If not for this, the interface could be implemented directly by our Foreground Service. ReactApplicationContext JSEventSender This Module will expose 2 methods accessible on the JS side: startBackgroundLocation stopBackgroundLocation They will be responsible for either launching our Foreground Service or stopping it. Next we’re going to analyse a bit our Foreground Service, which is kind of our mastermind behind everything. com.rnbglocation.location; android.app.AlarmManager; android.app.Notification; android.app.NotificationChannel; android.app.NotificationManager; android.app.PendingIntent; android.app.Service; android.content.BroadcastReceiver; android.content.Context; android.content.Intent; android.content.IntentFilter; android.os.Build; android.os.IBinder; androidx.annotation.Nullable; androidx.core.app.NotificationCompat; com.google.gson.Gson; com.rnbglocation.MainActivity; { String CHANNEL_ID = ; NOTIFICATION_ID = ; String LOCATION_EVENT_NAME = ; String LOCATION_EVENT_DATA_NAME = ; LOCATION_UPDATE_INTERVAL = ; String JS_LOCATION_LAT_KEY = ; String JS_LOCATION_LON_KEY = ; String JS_LOCATION_TIME_KEY = ; String JS_LOCATION_EVENT_NAME = ; AlarmManager mAlarmManager; BroadcastReceiver mEventReceiver; PendingIntent mLocationBackgroundServicePendingIntent; Gson mGson; { .onCreate(); mAlarmManager = (AlarmManager) getApplicationContext().getSystemService(Context.ALARM_SERVICE); mGson = Gson(); createEventReceiver(); registerEventReceiver(); } { createNotificationChannel(); startForeground(NOTIFICATION_ID, createNotification()); createLocationPendingIntent(); mAlarmManager.setRepeating( AlarmManager.RTC, System.currentTimeMillis(), LOCATION_UPDATE_INTERVAL, mLocationBackgroundServicePendingIntent ); START_NOT_STICKY; } { mEventReceiver = BroadcastReceiver() { { LocationCoordinates locationCoordinates = mGson.fromJson( intent.getStringExtra(LOCATION_EVENT_DATA_NAME), LocationCoordinates.class); } }; } { IntentFilter eventFilter = IntentFilter(); eventFilter.addAction(LOCATION_EVENT_NAME); registerReceiver(mEventReceiver, eventFilter); } { ; } { unregisterReceiver(mEventReceiver); mAlarmManager.cancel(mLocationBackgroundServicePendingIntent); stopSelf(); .onDestroy(); } { (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) { NotificationChannel serviceChannel = NotificationChannel( CHANNEL_ID, , NotificationManager.IMPORTANCE_DEFAULT ); NotificationManager manager = getSystemService(NotificationManager.class); manager.createNotificationChannel(serviceChannel); } } { Intent notificationIntent = Intent( , MainActivity.class); PendingIntent pendingIntent = PendingIntent.getActivity( , , notificationIntent, ); NotificationCompat.Builder( , CHANNEL_ID) .setContentIntent(pendingIntent) .build(); } { Intent i = Intent(getApplicationContext(), LocationBackgroundService.class); mLocationBackgroundServicePendingIntent = PendingIntent.getService(getApplicationContext(), , i, PendingIntent.FLAG_UPDATE_CURRENT); } } package import import import import import import import import import import import import import import import import public class LocationForegroundService extends Service implements LocationEventReceiver public static final "ForegroundServiceChannel" public static final int 1 public static final "com.rnbglocation.LOCATION_INFO" public static final "LocationData" public static final int 60000 public static final "latitude" public static final "longitude" public static final "timestamp" public static final "location_received" private private private private @Override public void onCreate () super new @Override public int onStartCommand (Intent intent, flags, startId) int int return @Override public void createEventReceiver () new @Override public void onReceive (Context context, Intent intent) /* do any kind of logic in here with the LocationCoordinates class e.g. like a request to an API, etc --> all on the native side */ TODO: @Override public void registerEventReceiver () new @Nullable @Override IBinder public onBind (Intent intent) return null @Override public void onDestroy () super private void createNotificationChannel () if new "Foreground Service Channel" Notification private createNotification () new this this 0 0 return new this private void createLocationPendingIntent () new 1 In this service we are implementing like we were on the module. This may be a bit redundant in such a simple demo, but the purpose of having this service knowing the location updates is because you may want your foreground service to launch different background tasks with different work depending on the location of the user, or you may want to do specific native work like persisting these coordinates locally. LocationEventReceiver The method is the base of the service and it’s responsible for: onStartCommand Creating our notification channel (a necessary step from Oreo up) Creating the notification that is displayed to our users Call method which is crucial to start this service as a foreground service startForeground Use to schedule a background task to fetch our user location with 1 minute intervals (the interval is fully customisable of course) AlarmManager Don’t forget that for your app to be able to use foreground services, it must declare the permissions for it in the manifest file with: The actual location fetching and handling is done in a background task on a different thread than the main one. Let’s check out this background service. com.rnbglocation.location; android.annotation.SuppressLint; android.app.IntentService; android.content.Intent; android.location.Location; android.os.Handler; androidx.annotation.Nullable; com.google.android.gms.location.FusedLocationProviderClient; com.google.android.gms.location.LocationCallback; com.google.android.gms.location.LocationRequest; com.google.android.gms.location.LocationResult; com.google.android.gms.location.LocationServices; com.google.gson.Gson; java.util.Date; { FusedLocationProviderClient mFusedLocationClient; LocationCallback mLocationCallback; Gson mGson; { (LocationForegroundService.class.getName()); mGson = Gson(); } ( ) { mFusedLocationClient = LocationServices.getFusedLocationProviderClient(getApplicationContext()); mLocationCallback = createLocationRequestCallback(); LocationRequest locationRequest = LocationRequest.create() .setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY) .setInterval( ) .setFastestInterval( ); Handler(getMainLooper()).post(() -> mFusedLocationClient.requestLocationUpdates(locationRequest, mLocationCallback, )); } { LocationCallback() { { (locationResult == ) { ; } (Location location : locationResult.getLocations()) { LocationCoordinates locationCoordinates = createCoordinates(location.getLatitude(), location.getLongitude()); broadcastLocationReceived(locationCoordinates); mFusedLocationClient.removeLocationUpdates(mLocationCallback); } } }; } { LocationCoordinates() .setLatitude(latitude) .setLongitude(longitude) .setTimestamp( Date().getTime()); } { Intent eventIntent = Intent(LocationForegroundService.LOCATION_EVENT_NAME); eventIntent.putExtra(LocationForegroundService.LOCATION_EVENT_DATA_NAME, mGson.toJson(locationCoordinates)); getApplicationContext().sendBroadcast(eventIntent); } } package import import import import import import import import import import import import import public class LocationBackgroundService extends IntentService private private private public LocationBackgroundService () super new @SuppressLint "MissingPermission" @Override protected void onHandleIntent (@Nullable Intent intent) 0 0 new null LocationCallback private createLocationRequestCallback () return new @Override public void onLocationResult (LocationResult locationResult) if null return for LocationCoordinates private createCoordinates ( latitude, longitude) double double return new new private void broadcastLocationReceived (LocationCoordinates locationCoordinates) new This service is pretty simple, it’s using to fetch the user location with the details specified in our . FusedLocationProviderClient LocationRequest When the location provider finishes fetching the user location, we then send that location transformed into our class through our broadcast mechanism for anyone who wants to listen for those coordinates. LocationCoordinates These files are the heart of this solution, and with this you can perfectly control user location on almost all Android smartphones out there with a react native solution which is incredibly resource and battery friendly. Additional Notes For Android 4.4 support there are a few extra steps needed, and they are included on the demo provided but I think they are worth mentioning nonetheless. In our file we need to include a new dependency regarding the build process of the APK, and that dependency is: app.gradle implementation “com.android.support:multidex:1.0.3” Besides that, in that very same file we need to declare that we want our app to enable multi-dexing with the following statement: under the piece of configuration multiDexEnabled true defaultConfig This will let our app know that we want to include this, but in order for everything to work well we need to do one more thing under the MainApplication.java file: … … MainApplication extends MultiDexApplication With these configurations we make sure that our app is now fully compatible until Android 4.4 which is great! Conclusion React-Native is a great platform for developers to use and definitely speeds things up for devs coming from a mostly web background. Still, there are many things that require native knowledge on either Android or iOS and this demo is an example of that. One thing that I would like to say about the technology itself is: Be careful when choosing the technology for your app when you’re in an enterprise environment. React Native is far from stable, and the breaking changes are several from version to version. Just to have a small idea: v0.60 — breaking changes involved for some users v0.59 — breaking changes on Android v0.58 — breaking changes for some components v0.57.2 — breaking changes due to elements removed Taking this into account, you can see that all the breaking changes from version to version may have problems on app maintenance in the future when you try to upgrade your app for some new features, optimisations or simply bug fixes. Consider the trade-offs well when considering this technology against the more traditional ones, especially if you’re aiming for something that is going to be maintained long term or you won’t have a particular big or specialised team involved on building and maintaining the product. I hope you liked this simple demo and most of all, I hope it helps you in your project! 🎉 I would also love your feedback 🙂 If you find this article interesting, please share it, because you know — Sharing is caring! Also, if you enjoy working at a large scale in projects with global impact and if you enjoy a challenge, please reach out to us at xgeeks ! We’re always looking for talented people to join our team 🙌