@capgo/background-geolocation 7.0.6 → 7.0.7

package/README.md

@@ -6,7 +6,8 @@
   <h2><a href="https://capgo.app/consulting/?ref=plugin"> Missing a feature? We’ll build the plugin for you 💪</a></h2>
 </div>
 
-A Capacitor plugin that lets you receive geolocation updates even while the app is backgrounded. Only iOS and Android platforms are supported.
+A Capacitor plugin that lets you receive geolocation updates even while the app is backgrounded.
+It has a web API to facilitate for a similar usage, but background geolocation is not supported in a regular browser, only in an app environment.
 
 ## Usage
 
@@ -121,12 +122,6 @@ function guess_location(callback, timeout) {
 }
 ```
 
-### Typescript support
-
-```typescript
-import { BackgroundGeolocation } from "@capgo/background-geolocation";
-```
-
 ## Installation
 
 This plugin supports Capacitor v7:
@@ -162,7 +157,7 @@ Add the following keys to `Info.plist.`:
 
 Set the the `android.useLegacyBridge` option to `true` in your Capacitor configuration. This prevents location updates halting after 5 minutes in the background. See https://capacitorjs.com/docs/config and https://github.com/capacitor-community/background-geolocation/issues/89.
 
-On Android 13+, the app needs the `POST_NOTIFICATIONS` runtime permission to show the persistent notification informing the user that their location is being used in the background. You may need to [request this permission](https://developer.android.com/develop/ui/views/notifications/notification-permission) from the user, this can be accomplished [using the `@capacitor/local-notifications` plugin](https://capacitorjs.com/docs/apis/local-notifications#checkpermissions).
+On Android 13+, the app needs the `POST_NOTIFICATIONS` runtime permission to show the persistent notification informing the user that their location is being used in the background. This runtime permission is requested after the location permission is granted.
 
 If your app forwards location updates to a server in real time, be aware that after 5 minutes in the background Android will throttle HTTP requests initiated from the WebView. The solution is to use a native HTTP plugin such as [CapacitorHttp](https://capacitorjs.com/docs/apis/http). See https://github.com/capacitor-community/background-geolocation/issues/14.
 

package/android/src/main/java/com/capgo/capacitor_background_geolocation/BackgroundGeolocation.java

@@ -11,7 +11,6 @@ import android.content.Context;
 import android.content.Intent;
 import android.content.IntentFilter;
 import android.content.ServiceConnection;
-import android.content.pm.PackageManager;
 import android.graphics.Color;
 import android.location.Location;
 import android.location.LocationManager;
@@ -30,7 +29,7 @@ import com.getcapacitor.annotation.CapacitorPlugin;
 import com.getcapacitor.annotation.Permission;
 import com.getcapacitor.annotation.PermissionCallback;
 import com.google.android.gms.location.LocationServices;
-import com.google.android.gms.tasks.OnSuccessListener;
+import java.util.concurrent.CompletableFuture;
 import org.json.JSONObject;
 
 @CapacitorPlugin(
@@ -43,140 +42,178 @@ import org.json.JSONObject;
       },
       alias = "location"
     ),
+    @Permission(
+      strings = { Manifest.permission.POST_NOTIFICATIONS },
+      alias = "notification"
+    ),
   }
 )
 public class BackgroundGeolocation extends Plugin {
 
-  private BackgroundGeolocationService.LocalBinder service = null;
-  private Boolean stoppedWithoutPermissions = false;
+  private CompletableFuture<
+    BackgroundGeolocationService.LocalBinder
+  > serviceConnectionFuture;
+  private CompletableFuture<Void> locationPermissionFuture;
 
   private void fetchLastLocation(PluginCall call) {
     try {
       LocationServices.getFusedLocationProviderClient(getContext())
         .getLastLocation()
-        .addOnSuccessListener(
-          getActivity(),
-          new OnSuccessListener<Location>() {
-            @Override
-            public void onSuccess(Location location) {
-              if (location != null) {
-                call.resolve(formatLocation(location));
-              }
-            }
+        .addOnSuccessListener(getActivity(), location -> {
+          if (location != null) {
+            call.resolve(formatLocation(location));
           }
-        );
+        });
     } catch (SecurityException ignore) {}
   }
 
   @PluginMethod(returnType = PluginMethod.RETURN_CALLBACK)
   public void addWatcher(final PluginCall call) {
-    if (service == null) {
-      call.reject("Service not running.");
+    if (
+      getPermissionState("location") != PermissionState.GRANTED &&
+      !call.getBoolean("requestPermissions", true)
+    ) {
+      call.reject("User denied location permission", "NOT_AUTHORIZED");
       return;
     }
-    call.setKeepAlive(true);
 
-    if (getPermissionState("location") != PermissionState.GRANTED) {
-      if (call.getBoolean("requestPermissions", true)) {
-        requestPermissionForAlias(
-          "location",
-          call,
-          "locationPermissionsCallback"
-        );
-      } else {
-        call.reject("Permission denied.", "NOT_AUTHORIZED");
-      }
-    } else if (!isLocationEnabled(getContext())) {
+    if (
+      getPermissionState("location") != PermissionState.GRANTED &&
+      call.getBoolean("requestPermissions", true)
+    ) {
+      call.setKeepAlive(true);
+      requestLocationPermissions(call)
+        .thenRun(() -> {
+          proceedWithWatcher(call);
+        })
+        .exceptionally(throwable -> {
+          call.reject("User denied location permission", "NOT_AUTHORIZED");
+          return null;
+        });
+      return;
+    }
+
+    // location permission granted.
+    if (!isLocationEnabled(getContext())) {
       call.reject("Location services disabled.", "NOT_AUTHORIZED");
+      return;
     }
+
+    // Everything is OK, continuing to adding a watcher
+    call.setKeepAlive(true);
+    proceedWithWatcher(call);
+  }
+
+  private void proceedWithWatcher(PluginCall call) {
     if (call.getBoolean("stale", false)) {
       fetchLastLocation(call);
     }
-    Notification backgroundNotification = null;
-    String backgroundMessage = call.getString("backgroundMessage");
-
-    if (backgroundMessage != null) {
-      Notification.Builder builder = new Notification.Builder(getContext())
-        .setContentTitle(
-          call.getString("backgroundTitle", "Using your location")
-        )
-        .setContentText(backgroundMessage)
-        .setOngoing(true)
-        .setPriority(Notification.PRIORITY_HIGH)
-        .setWhen(System.currentTimeMillis());
-
-      try {
-        String name = getAppString(
-          "capacitor_background_geolocation_notification_icon",
-          "mipmap/ic_launcher"
+    getServiceConnection().thenAccept(serviceBinder -> {
+        serviceBinder.addWatcher(
+          call.getCallbackId(),
+          createBackgroundNotification(call),
+          call.getFloat("distanceFilter", 0f)
         );
-        String[] parts = name.split("/");
-        // It is actually necessary to set a valid icon for the notification to behave
-        // correctly when tapped. If there is no icon specified, tapping it will open the
-        // app's settings, rather than bringing the application to the foreground.
-        builder.setSmallIcon(getAppResourceIdentifier(parts[1], parts[0]));
-      } catch (Exception e) {
-        Logger.error("Could not set notification icon", e);
-      }
+      });
+  }
 
-      try {
-        String color = getAppString(
-          "capacitor_background_geolocation_notification_color",
-          null
-        );
-        if (color != null) {
-          builder.setColor(Color.parseColor(color));
-        }
-      } catch (Exception e) {
-        Logger.error("Could not set notification color", e);
-      }
+  private CompletableFuture<Void> requestLocationPermissions(PluginCall call) {
+    if (locationPermissionFuture != null) {
+      return locationPermissionFuture;
+    }
+    locationPermissionFuture = new CompletableFuture<>();
+    requestPermissionForAlias("location", call, "locationPermissionsCallback");
+    return locationPermissionFuture;
+  }
 
-      Intent launchIntent = getContext()
-        .getPackageManager()
-        .getLaunchIntentForPackage(getContext().getPackageName());
-      if (launchIntent != null) {
-        launchIntent.addFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT);
-        builder.setContentIntent(
-          PendingIntent.getActivity(
-            getContext(),
-            0,
-            launchIntent,
-            PendingIntent.FLAG_CANCEL_CURRENT | PendingIntent.FLAG_IMMUTABLE
-          )
-        );
-      }
+  private Notification createBackgroundNotification(PluginCall call) {
+    String backgroundMessage = call.getString("backgroundMessage", "");
 
-      // Set the Channel ID for Android O.
-      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-        builder.setChannelId(
-          BackgroundGeolocationService.class.getPackage().getName()
-        );
+    Notification.Builder builder = new Notification.Builder(getContext())
+      .setContentTitle(call.getString("backgroundTitle", "Using your location"))
+      .setContentText(backgroundMessage)
+      .setOngoing(true)
+      .setPriority(Notification.PRIORITY_HIGH)
+      .setWhen(System.currentTimeMillis());
+
+    try {
+      String name = getAppString(
+        "capacitor_background_geolocation_notification_icon",
+        "mipmap/ic_launcher"
+      );
+      String[] parts = name.split("/");
+      // It is actually necessary to set a valid icon for the notification to behave
+      // correctly when tapped. If there is no icon specified, tapping it will open the
+      // app's settings, rather than bringing the application to the foreground.
+      builder.setSmallIcon(getAppResourceIdentifier(parts[1], parts[0]));
+    } catch (Exception e) {
+      Logger.error("Could not set notification icon", e);
+    }
+
+    try {
+      String color = getAppString(
+        "capacitor_background_geolocation_notification_color",
+        null
+      );
+      if (color != null) {
+        builder.setColor(Color.parseColor(color));
       }
+    } catch (Exception e) {
+      Logger.error("Could not set notification color", e);
+    }
 
-      backgroundNotification = builder.build();
+    Intent launchIntent = getContext()
+      .getPackageManager()
+      .getLaunchIntentForPackage(getContext().getPackageName());
+    if (launchIntent != null) {
+      launchIntent.addFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT);
+      builder.setContentIntent(
+        PendingIntent.getActivity(
+          getContext(),
+          0,
+          launchIntent,
+          PendingIntent.FLAG_CANCEL_CURRENT | PendingIntent.FLAG_IMMUTABLE
+        )
+      );
     }
-    service.addWatcher(
-      call.getCallbackId(),
-      backgroundNotification,
-      call.getFloat("distanceFilter", 0f)
-    );
+
+    // Set the Channel ID for Android O.
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      builder.setChannelId(
+        BackgroundGeolocationService.class.getPackage().getName()
+      );
+    }
+
+    return builder.build();
   }
 
   @PermissionCallback
   private void locationPermissionsCallback(PluginCall call) {
-    if (getPermissionState("location") != PermissionState.GRANTED) {
-      call.reject("User denied location permission", "NOT_AUTHORIZED");
+    if (locationPermissionFuture == null) {
       return;
     }
-    if (call.getBoolean("stale", false)) {
-      fetchLastLocation(call);
-    }
-    if (service != null) {
-      service.onPermissionsGranted();
-      // The handleOnResume method will now be called, and we don't need it to call
-      // service.onPermissionsGranted again so we reset this flag.
-      stoppedWithoutPermissions = false;
+
+    requestPermissionForAlias(
+      "notification",
+      call,
+      "notificationPermissionsCallback"
+    );
+
+    if (getPermissionState("location") != PermissionState.GRANTED) {
+      locationPermissionFuture.completeExceptionally(
+        new SecurityException("User denied location permission")
+      );
+      locationPermissionFuture = null;
+      return;
     }
+
+    locationPermissionFuture.complete(null);
+    locationPermissionFuture = null;
+  }
+
+  @PermissionCallback
+  private void notificationPermissionsCallback(PluginCall call) {
+    Logger.debug("notification permission callback");
   }
 
   @PluginMethod
@@ -186,12 +223,20 @@ public class BackgroundGeolocation extends Plugin {
       call.reject("Missing id.");
       return;
     }
-    service.removeWatcher(callbackId);
-    PluginCall savedCall = getBridge().getSavedCall(callbackId);
-    if (savedCall != null) {
-      savedCall.release(getBridge());
-    }
-    call.resolve();
+
+    getServiceConnection()
+      .thenAccept(service -> {
+        service.removeWatcher(callbackId);
+        PluginCall savedCall = getBridge().getSavedCall(callbackId);
+        if (savedCall != null) {
+          savedCall.release(getBridge());
+        }
+        call.resolve();
+      })
+      .exceptionally(throwable -> {
+        call.reject("Service connection failed: " + throwable.getMessage());
+        return null;
+      });
   }
 
   @PluginMethod
@@ -313,51 +358,77 @@ public class BackgroundGeolocation extends Plugin {
       manager.createNotificationChannel(channel);
     }
 
+    LocalBroadcastManager.getInstance(this.getContext()).registerReceiver(
+      new ServiceReceiver(),
+      new IntentFilter(BackgroundGeolocationService.ACTION_BROADCAST)
+    );
+  }
+
+  private CompletableFuture<
+    BackgroundGeolocationService.LocalBinder
+  > getServiceConnection() {
+    if (
+      serviceConnectionFuture != null &&
+      !serviceConnectionFuture.isCompletedExceptionally()
+    ) {
+      return serviceConnectionFuture;
+    }
+
+    serviceConnectionFuture = new CompletableFuture<>();
+
+    Intent serviceIntent = new Intent(
+      this.getContext(),
+      BackgroundGeolocationService.class
+    );
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      this.getContext().startForegroundService(serviceIntent);
+    } else {
+      this.getContext().startService(serviceIntent);
+    }
+
     this.getContext().bindService(
-        new Intent(this.getContext(), BackgroundGeolocationService.class),
+        serviceIntent,
         new ServiceConnection() {
           @Override
           public void onServiceConnected(ComponentName name, IBinder binder) {
-            BackgroundGeolocation.this.service =
-              (BackgroundGeolocationService.LocalBinder) binder;
+            serviceConnectionFuture.complete(
+              (BackgroundGeolocationService.LocalBinder) binder
+            );
           }
 
           @Override
-          public void onServiceDisconnected(ComponentName name) {}
+          public void onServiceDisconnected(ComponentName name) {
+            serviceConnectionFuture = null;
+          }
         },
         Context.BIND_AUTO_CREATE
       );
 
-    LocalBroadcastManager.getInstance(this.getContext()).registerReceiver(
-      new ServiceReceiver(),
-      new IntentFilter(BackgroundGeolocationService.ACTION_BROADCAST)
-    );
+    return serviceConnectionFuture;
   }
 
   @Override
   protected void handleOnResume() {
-    if (service != null) {
-      if (
-        stoppedWithoutPermissions &&
-        getPermissionState("location") == PermissionState.GRANTED
-      ) {
-        service.onPermissionsGranted();
-      }
-    }
     super.handleOnResume();
   }
 
   @Override
   protected void handleOnPause() {
-    stoppedWithoutPermissions =
-      getPermissionState("location") != PermissionState.GRANTED;
     super.handleOnPause();
   }
 
   @Override
   protected void handleOnDestroy() {
-    if (service != null) {
-      service.stopService();
+    if (serviceConnectionFuture != null) {
+      serviceConnectionFuture.thenAccept(
+        BackgroundGeolocationService.LocalBinder::stopService
+      );
+    }
+
+    if (
+      locationPermissionFuture != null && !locationPermissionFuture.isDone()
+    ) {
+      locationPermissionFuture.cancel(true);
     }
     super.handleOnDestroy();
   }

package/android/src/main/java/com/capgo/capacitor_background_geolocation/BackgroundGeolocationService.java

@@ -2,20 +2,14 @@ package com.capgo.capacitor_background_geolocation;
 
 import android.app.Notification;
 import android.app.Service;
+import android.content.Context;
 import android.content.Intent;
-import android.content.pm.ServiceInfo;
-import android.location.Location;
+import android.location.LocationListener;
+import android.location.LocationManager;
 import android.os.Binder;
-import android.os.Build;
 import android.os.IBinder;
 import androidx.localbroadcastmanager.content.LocalBroadcastManager;
 import com.getcapacitor.Logger;
-import com.google.android.gms.location.FusedLocationProviderClient;
-import com.google.android.gms.location.LocationAvailability;
-import com.google.android.gms.location.LocationCallback;
-import com.google.android.gms.location.LocationRequest;
-import com.google.android.gms.location.LocationResult;
-import com.google.android.gms.location.LocationServices;
 import java.util.HashSet;
 
 // A bound and started service that is promoted to a foreground service
@@ -30,16 +24,16 @@ public class BackgroundGeolocationService extends Service {
   // Must be unique for this application.
   private static final int NOTIFICATION_ID = 28351;
 
-  private class Watcher {
+  private static class Watcher {
 
     public String id;
-    public FusedLocationProviderClient client;
-    public LocationRequest locationRequest;
-    public LocationCallback locationCallback;
+    public LocationManager client;
+    public float distanceFilter;
+    public LocationListener locationCallback;
     public Notification backgroundNotification;
   }
 
-  private HashSet<Watcher> watchers = new HashSet<Watcher>();
+  private HashSet<Watcher> watchers = new HashSet<>();
 
   @Override
   public IBinder onBind(Intent intent) {
@@ -53,20 +47,26 @@ public class BackgroundGeolocationService extends Service {
   @Override
   public boolean onUnbind(Intent intent) {
     for (Watcher watcher : watchers) {
-      watcher.client.removeLocationUpdates(watcher.locationCallback);
+      watcher.client.removeUpdates(watcher.locationCallback);
     }
-    watchers = new HashSet<Watcher>();
+    watchers = new HashSet<>();
     stopSelf();
     return false;
   }
 
-  Notification getNotification() {
-    for (Watcher watcher : watchers) {
-      if (watcher.backgroundNotification != null) {
-        return watcher.backgroundNotification;
-      }
+  private void requestLocationUpdates(Watcher watcher) {
+    try {
+      watcher.client.requestLocationUpdates(
+        LocationManager.GPS_PROVIDER,
+        1000,
+        watcher.distanceFilter,
+        watcher.locationCallback
+      );
+    } catch (SecurityException ignore) {
+      // According to Android Studio, this method can throw a Security Exception if
+      // permissions are not yet granted. Rather than check the permissions, which is fiddly,
+      // we simply ignore the exception.
     }
-    return null;
   }
 
   // Handles requests from the activity.
@@ -77,54 +77,28 @@ public class BackgroundGeolocationService extends Service {
       Notification backgroundNotification,
       float distanceFilter
     ) {
-      FusedLocationProviderClient client =
-        LocationServices.getFusedLocationProviderClient(
-          BackgroundGeolocationService.this
-        );
-      LocationRequest locationRequest = new LocationRequest();
-      locationRequest.setMaxWaitTime(1000);
-      locationRequest.setInterval(1000);
-      locationRequest.setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY);
-      locationRequest.setSmallestDisplacement(distanceFilter);
-
-      LocationCallback callback = new LocationCallback() {
-        @Override
-        public void onLocationResult(LocationResult locationResult) {
-          Location location = locationResult.getLastLocation();
-          Intent intent = new Intent(ACTION_BROADCAST);
-          intent.putExtra("location", location);
-          intent.putExtra("id", id);
-          LocalBroadcastManager.getInstance(
-            getApplicationContext()
-          ).sendBroadcast(intent);
-        }
-
-        @Override
-        public void onLocationAvailability(LocationAvailability availability) {
-          if (!availability.isLocationAvailable()) {
-            Logger.debug("Location not available");
-          }
-        }
+      LocationManager locationManager = (LocationManager) getSystemService(
+        Context.LOCATION_SERVICE
+      );
+
+      LocationListener listener = location -> {
+        Intent intent = new Intent(ACTION_BROADCAST);
+        intent.putExtra("location", location);
+        intent.putExtra("id", id);
+        LocalBroadcastManager.getInstance(
+          getApplicationContext()
+        ).sendBroadcast(intent);
       };
 
       Watcher watcher = new Watcher();
       watcher.id = id;
-      watcher.client = client;
-      watcher.locationRequest = locationRequest;
-      watcher.locationCallback = callback;
+      watcher.client = locationManager;
+      watcher.distanceFilter = distanceFilter;
+      watcher.locationCallback = listener;
       watcher.backgroundNotification = backgroundNotification;
       watchers.add(watcher);
 
-      // According to Android Studio, this method can throw a Security Exception if
-      // permissions are not yet granted. Rather than check the permissions, which is fiddly,
-      // we simply ignore the exception.
-      try {
-        watcher.client.requestLocationUpdates(
-          watcher.locationRequest,
-          watcher.locationCallback,
-          null
-        );
-      } catch (SecurityException ignore) {}
+      requestLocationUpdates(watcher);
 
       // Promote the service to the foreground if necessary.
       // Ideally we would only call 'startForeground' if the service is not already
@@ -132,46 +106,32 @@ public class BackgroundGeolocationService extends Service {
       // in API level 29 and seems to behave weirdly, as reported in #120. However,
       // it appears that 'startForeground' is idempotent, so we just call it repeatedly
       // each time a background watcher is added.
-      if (backgroundNotification != null) {
-        try {
-          // This method has been known to fail due to weird
-          // permission bugs, so we prevent any exceptions from
-          // crashing the app. See issue #86.
-          startForeground(NOTIFICATION_ID, backgroundNotification);
-        } catch (Exception exception) {
-          Logger.error("Failed to foreground service", exception);
-        }
+      try {
+        // This method has been known to fail due to weird
+        // permission bugs, so we prevent any exceptions from
+        // crashing the app. See issue #86.
+        startForeground(NOTIFICATION_ID, backgroundNotification);
+      } catch (Exception exception) {
+        Logger.error("Failed to foreground service", exception);
       }
     }
 
     void removeWatcher(String id) {
       for (Watcher watcher : watchers) {
         if (watcher.id.equals(id)) {
-          watcher.client.removeLocationUpdates(watcher.locationCallback);
+          watcher.client.removeUpdates(watcher.locationCallback);
           watchers.remove(watcher);
-          if (getNotification() == null) {
-            stopForeground(true);
-          }
-          return;
+          break;
         }
       }
-    }
-
-    void onPermissionsGranted() {
-      // If permissions were granted while the app was in the background, for example in
-      // the Settings app, the watchers need restarting.
-      for (Watcher watcher : watchers) {
-        watcher.client.removeLocationUpdates(watcher.locationCallback);
-        watcher.client.requestLocationUpdates(
-          watcher.locationRequest,
-          watcher.locationCallback,
-          null
-        );
+      if (watchers.isEmpty()) {
+        stopService();
       }
     }
 
     void stopService() {
-      BackgroundGeolocationService.this.stopSelf();
+      stopForeground(true);
+      stopSelf();
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@capgo/background-geolocation",
-    "version": "7.0.6",
+    "version": "7.0.7",
     "description": "Receive geolocation updates even while the app is in the background.",
     "main": "dist/plugin.cjs.js",
     "module": "dist/esm/index.js",