@capgo/background-geolocation 7.0.8 → 7.0.10

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

@@ -1,16 +1,21 @@
 package com.capgo.capacitor_background_geolocation;
 
 import android.app.Notification;
+import android.app.PendingIntent;
 import android.app.Service;
 import android.content.Context;
 import android.content.Intent;
+import android.content.res.AssetFileDescriptor;
+import android.content.res.AssetManager;
+import android.graphics.Color;
 import android.location.LocationListener;
 import android.location.LocationManager;
+import android.media.MediaPlayer;
 import android.os.Binder;
+import android.os.Build;
 import android.os.IBinder;
 import androidx.localbroadcastmanager.content.LocalBroadcastManager;
 import com.getcapacitor.Logger;
-import java.util.HashSet;
 
 // A bound and started service that is promoted to a foreground service
 // (showing a persistent notification) when the first background watcher is
@@ -24,16 +29,11 @@ public class BackgroundGeolocationService extends Service {
   // Must be unique for this application.
   private static final int NOTIFICATION_ID = 28351;
 
-  private static class Watcher {
+  private String callbackId;
 
-    public String id;
-    public LocationManager client;
-    public float distanceFilter;
-    public LocationListener locationCallback;
-    public Notification backgroundNotification;
-  }
-
-  private HashSet<Watcher> watchers = new HashSet<>();
+  private LocationManager client;
+  private LocationListener locationCallback;
+  private MediaPlayer mediaPlayer;
 
   @Override
   public IBinder onBind(Intent intent) {
@@ -46,59 +46,67 @@ public class BackgroundGeolocationService extends Service {
   // service is terminated immediately.
   @Override
   public boolean onUnbind(Intent intent) {
-    for (Watcher watcher : watchers) {
-      watcher.client.removeUpdates(watcher.locationCallback);
-    }
-    watchers = new HashSet<>();
+    client.removeUpdates(locationCallback);
+    releaseMediaPlayer();
     stopSelf();
     return false;
   }
 
-  private void requestLocationUpdates(Watcher watcher) {
+  @Override
+  public void onDestroy() {
+    client.removeUpdates(locationCallback);
+    super.onDestroy();
+    releaseMediaPlayer();
+  }
+
+  private void releaseMediaPlayer() {
+    if (mediaPlayer == null) {
+      return;
+    }
     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.
+      if (mediaPlayer.isPlaying()) {
+        mediaPlayer.stop();
+      }
+      mediaPlayer.release();
+    } catch (Exception e) {
+      Logger.error("Error releasing MediaPlayer", e);
     }
+    mediaPlayer = null;
   }
 
   // Handles requests from the activity.
   public class LocalBinder extends Binder {
 
-    void addWatcher(
+    void start(
       final String id,
-      Notification backgroundNotification,
+      final String notificationTitle,
+      final String notificationMessage,
       float distanceFilter
     ) {
-      LocationManager locationManager = (LocationManager) getSystemService(
-        Context.LOCATION_SERVICE
-      );
+      client = (LocationManager) getSystemService(Context.LOCATION_SERVICE);
+      callbackId = id;
 
-      LocationListener listener = location -> {
+      locationCallback = location -> {
         Intent intent = new Intent(ACTION_BROADCAST);
         intent.putExtra("location", location);
-        intent.putExtra("id", id);
+        intent.putExtra("id", callbackId);
         LocalBroadcastManager.getInstance(
           getApplicationContext()
         ).sendBroadcast(intent);
       };
 
-      Watcher watcher = new Watcher();
-      watcher.id = id;
-      watcher.client = locationManager;
-      watcher.distanceFilter = distanceFilter;
-      watcher.locationCallback = listener;
-      watcher.backgroundNotification = backgroundNotification;
-      watchers.add(watcher);
-
-      requestLocationUpdates(watcher);
+      try {
+        client.requestLocationUpdates(
+          LocationManager.GPS_PROVIDER,
+          1000,
+          distanceFilter,
+          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.
+      }
 
       // Promote the service to the foreground if necessary.
       // Ideally we would only call 'startForeground' if the service is not already
@@ -110,28 +118,158 @@ public class BackgroundGeolocationService extends Service {
         // 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);
+        startForeground(
+          NOTIFICATION_ID,
+          createBackgroundNotification(notificationTitle, notificationMessage)
+        );
       } 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.removeUpdates(watcher.locationCallback);
-          watchers.remove(watcher);
-          break;
-        }
+    String stop() {
+      client.removeUpdates(locationCallback);
+      stopForeground(true);
+      stopSelf();
+      return callbackId;
+    }
+
+    void playSound(String filePath) {
+      try {
+        releaseMediaPlayer();
+
+        mediaPlayer = new MediaPlayer();
+
+        AssetManager am = getApplicationContext().getResources().getAssets();
+        AssetFileDescriptor assetFileDescriptor = am.openFd(
+          "public/" + filePath
+        );
+
+        mediaPlayer.setDataSource(
+          assetFileDescriptor.getFileDescriptor(),
+          assetFileDescriptor.getStartOffset(),
+          assetFileDescriptor.getLength()
+        );
+        mediaPlayer.setLooping(false);
+
+        mediaPlayer.setOnCompletionListener(mp -> {
+          try {
+            mp.release();
+          } catch (Exception e) {
+            Logger.error("Error releasing MediaPlayer on completion", e);
+          }
+          mediaPlayer = null;
+        });
+
+        mediaPlayer.setOnErrorListener((mp, what, extra) -> {
+          Logger.error("MediaPlayer error: what=" + what + ", extra=" + extra);
+          releaseMediaPlayer();
+          return true; // Indicate we handled the error
+        });
+
+        mediaPlayer.prepareAsync();
+        mediaPlayer.setOnPreparedListener(mp -> {
+          try {
+            mp.start();
+            Logger.debug("PlaySound: Successfully started playing sound");
+          } catch (Exception e) {
+            Logger.error("Error starting MediaPlayer", e);
+            releaseMediaPlayer();
+          }
+        });
+      } catch (Exception e) {
+        Logger.error("PlaySound: Unexpected error", e);
+        releaseMediaPlayer();
       }
-      if (watchers.isEmpty()) {
-        stopService();
+    }
+  }
+
+  private Notification createBackgroundNotification(
+    String backgroundTitle,
+    String backgroundMessage
+  ) {
+    Notification.Builder builder = new Notification.Builder(
+      getApplicationContext()
+    )
+      .setContentTitle(backgroundTitle)
+      .setContentText(backgroundMessage)
+      .setOngoing(true)
+      .setPriority(Notification.PRIORITY_HIGH)
+      .setWhen(System.currentTimeMillis());
+
+    try {
+      String name = getAppString(
+        "capacitor_background_geolocation_notification_icon",
+        "mipmap/ic_launcher",
+        getApplicationContext()
+      );
+      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], getApplicationContext())
+      );
+    } catch (Exception e) {
+      Logger.error("Could not set notification icon", e);
+    }
+
+    try {
+      String color = getAppString(
+        "capacitor_background_geolocation_notification_color",
+        null,
+        getApplicationContext()
+      );
+      if (color != null) {
+        builder.setColor(Color.parseColor(color));
       }
+    } catch (Exception e) {
+      Logger.error("Could not set notification color", e);
     }
 
-    void stopService() {
-      stopForeground(true);
-      stopSelf();
+    Intent launchIntent = getApplicationContext()
+      .getPackageManager()
+      .getLaunchIntentForPackage(getApplicationContext().getPackageName());
+    if (launchIntent != null) {
+      launchIntent.addFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT);
+      builder.setContentIntent(
+        PendingIntent.getActivity(
+          getApplicationContext(),
+          0,
+          launchIntent,
+          PendingIntent.FLAG_CANCEL_CURRENT | PendingIntent.FLAG_IMMUTABLE
+        )
+      );
+    }
+
+    // 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();
+  }
+
+  // Gets the identifier of the app's resource by name, returning 0 if not found.
+  private static int getAppResourceIdentifier(
+    String name,
+    String defType,
+    Context context
+  ) {
+    return context
+      .getResources()
+      .getIdentifier(name, defType, context.getPackageName());
+  }
+
+  // Gets a string from the app's strings.xml file, resorting to a fallback if it is not defined.
+  public static String getAppString(
+    String name,
+    String fallback,
+    Context context
+  ) {
+    int id = getAppResourceIdentifier(name, "string", context);
+    return id == 0 ? fallback : context.getString(id);
   }
 }

package/dist/docs.json

@@ -2,22 +2,22 @@
   "api": {
     "name": "BackgroundGeolocationPlugin",
     "slug": "backgroundgeolocationplugin",
-    "docs": "Main plugin interface for background geolocation functionality.\nProvides methods to manage location watchers and access device settings.",
+    "docs": "Main plugin interface for background geolocation functionality.\nProvides methods to manage location updates and access device settings.",
     "tags": [
       {
-        "text": "1.0.0",
+        "text": "7.0.0",
         "name": "since"
       }
     ],
     "methods": [
       {
-        "name": "addWatcher",
-        "signature": "(options: WatcherOptions, callback: (position?: Location | undefined, error?: CallbackError | undefined) => void) => Promise<string>",
+        "name": "start",
+        "signature": "(options: StartOptions, callback: (position?: Location | undefined, error?: CallbackError | undefined) => void) => Promise<void>",
         "parameters": [
           {
             "name": "options",
-            "docs": "The watcher configuration options",
-            "type": "WatcherOptions"
+            "docs": "The configuration options",
+            "type": "StartOptions"
           },
           {
             "name": "callback",
@@ -25,11 +25,11 @@
             "type": "(position?: Location | undefined, error?: CallbackError | undefined) => void"
           }
         ],
-        "returns": "Promise<string>",
+        "returns": "Promise<void>",
         "tags": [
           {
             "name": "param",
-            "text": "options The watcher configuration options"
+            "text": "options The configuration options"
           },
           {
             "name": "param",
@@ -37,57 +37,47 @@
           },
           {
             "name": "returns",
-            "text": "A promise that resolves to a unique identifier for the watcher ID"
+            "text": "A promise that resolves when the method is successfully called"
           },
           {
             "name": "since",
-            "text": "1.0.0"
+            "text": "7.0.9"
           },
           {
             "name": "example",
-            "text": "const watcherId = await BackgroundGeolocation.addWatcher(\n  {\n    backgroundMessage: \"App is using your location in the background\",\n    backgroundTitle: \"Location Service\",\n    requestPermissions: true,\n    stale: false,\n    distanceFilter: 10\n  },\n  (location, error) => {\n    if (error) {\n      console.error('Location error:', error);\n      return;\n    }\n    if (location) {\n      console.log('New location:', location.latitude, location.longitude);\n    }\n  }\n);"
+            "text": "await BackgroundGeolocation.start(\n  {\n    backgroundMessage: \"App is using your location in the background\",\n    backgroundTitle: \"Location Service\",\n    requestPermissions: true,\n    stale: false,\n    distanceFilter: 10\n  },\n  (location, error) => {\n    if (error) {\n      console.error('Location error:', error);\n      return;\n    }\n    if (location) {\n      console.log('New location:', location.latitude, location.longitude);\n    }\n  }\n);"
           }
         ],
-        "docs": "Adds a watcher for location updates.\nThe watcher will be invoked with the latest location whenever it is available.\nIf an error occurs, the callback will be invoked with the error.",
+        "docs": "To start listening for changes in the device's location, call this method.\nA Promise is returned to indicate that it finished the call. The callback will be called every time a new location\nis available, or if there was an error when calling this method. Don't rely on promise rejection for this.",
         "complexTypes": [
-          "WatcherOptions",
+          "StartOptions",
           "Location",
           "CallbackError"
         ],
-        "slug": "addwatcher"
+        "slug": "start"
       },
       {
-        "name": "removeWatcher",
-        "signature": "(options: { id: string; }) => Promise<void>",
-        "parameters": [
-          {
-            "name": "options",
-            "docs": "Object containing the watcher ID to remove",
-            "type": "{ id: string; }"
-          }
-        ],
+        "name": "stop",
+        "signature": "() => Promise<void>",
+        "parameters": [],
         "returns": "Promise<void>",
         "tags": [
-          {
-            "name": "param",
-            "text": "options Object containing the watcher ID to remove"
-          },
           {
             "name": "returns",
-            "text": "A promise that resolves when the watcher is successfully removed"
+            "text": "A promise that resolves when the plugin stops successfully removed"
           },
           {
             "name": "since",
-            "text": "1.0.0"
+            "text": "7.0.9"
           },
           {
             "name": "example",
-            "text": "await BackgroundGeolocation.removeWatcher({ id: watcherId });"
+            "text": "await BackgroundGeolocation.stop();"
           }
         ],
-        "docs": "Removes a watcher by its unique identifier.\nStops location updates for the specified watcher.",
+        "docs": "Stops location updates.",
         "complexTypes": [],
-        "slug": "removewatcher"
+        "slug": "stop"
       },
       {
         "name": "openSettings",
@@ -101,7 +91,7 @@
           },
           {
             "name": "since",
-            "text": "1.0.0"
+            "text": "7.0.0"
           },
           {
             "name": "example",
@@ -111,18 +101,53 @@
         "docs": "Opens the device's location settings page.\nUseful for directing users to enable location services or adjust permissions.",
         "complexTypes": [],
         "slug": "opensettings"
+      },
+      {
+        "name": "playSound",
+        "signature": "(options: PlaySoundOptions) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "The options for playing the sound",
+            "type": "PlaySoundOptions"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options The options for playing the sound"
+          },
+          {
+            "name": "returns",
+            "text": "A promise that resolves when the sound is successfully played"
+          },
+          {
+            "name": "since",
+            "text": "7.0.10"
+          },
+          {
+            "name": "example",
+            "text": "await BackgroundGeolocation.playSound({\n  soundFile: \"notification.mp3\"\n});"
+          }
+        ],
+        "docs": "Plays a sound file.\nThis should be used to play a sound, in the background too.\nThe idea behind this is to allow the user to hear a sound when a new location is available or when going off track.\nIf you simply need to play a sound, you can use `@capgo/native-audio` plugin instead.\nFor Android, there's a need to start monitoring location updates first, otherwise the sound will not play.",
+        "complexTypes": [
+          "PlaySoundOptions"
+        ],
+        "slug": "playsound"
       }
     ],
     "properties": []
   },
   "interfaces": [
     {
-      "name": "WatcherOptions",
-      "slug": "watcheroptions",
-      "docs": "The options for configuring a watcher that listens for location updates.",
+      "name": "StartOptions",
+      "slug": "startoptions",
+      "docs": "The options for configuring for location updates.",
       "tags": [
         {
-          "text": "1.0.0",
+          "text": "7.0.9",
           "name": "since"
         }
       ],
@@ -132,7 +157,7 @@
           "name": "backgroundMessage",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.9",
               "name": "since"
             },
             {
@@ -140,7 +165,7 @@
               "name": "example"
             }
           ],
-          "docs": "If the \"backgroundMessage\" option is defined, the watcher will\nprovide location updates whether the app is in the background or the\nforeground. If it is not defined, location updates are only\nguaranteed in the foreground. This is true on both platforms.\n\nOn Android, a notification must be shown to continue receiving\nlocation updates in the background. This option specifies the text of\nthat notification.",
+          "docs": "If the \"backgroundMessage\" option is defined, the plugin will\nprovide location updates whether the app is in the background or the\nforeground. If it is not defined, location updates are only\nguaranteed in the foreground. This is true on both platforms.\n\nOn Android, a notification must be shown to continue receiving\nlocation updates in the background. This option specifies the text of\nthat notification.",
           "complexTypes": [],
           "type": "string | undefined"
         },
@@ -148,7 +173,7 @@
           "name": "backgroundTitle",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.9",
               "name": "since"
             },
             {
@@ -168,7 +193,7 @@
           "name": "requestPermissions",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.9",
               "name": "since"
             },
             {
@@ -188,7 +213,7 @@
           "name": "stale",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.9",
               "name": "since"
             },
             {
@@ -208,7 +233,7 @@
           "name": "distanceFilter",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.9",
               "name": "since"
             },
             {
@@ -232,7 +257,7 @@
       "docs": "Represents a geographical location with various attributes.\nContains all the standard location properties returned by GPS/network providers.",
       "tags": [
         {
-          "text": "1.0.0",
+          "text": "7.0.0",
           "name": "since"
         }
       ],
@@ -242,7 +267,7 @@
           "name": "latitude",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.0",
               "name": "since"
             },
             {
@@ -258,7 +283,7 @@
           "name": "longitude",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.0",
               "name": "since"
             },
             {
@@ -274,7 +299,7 @@
           "name": "accuracy",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.0",
               "name": "since"
             },
             {
@@ -290,7 +315,7 @@
           "name": "altitude",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.0",
               "name": "since"
             },
             {
@@ -306,7 +331,7 @@
           "name": "altitudeAccuracy",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.0",
               "name": "since"
             },
             {
@@ -322,7 +347,7 @@
           "name": "simulated",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.0",
               "name": "since"
             },
             {
@@ -338,7 +363,7 @@
           "name": "bearing",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.0",
               "name": "since"
             },
             {
@@ -354,7 +379,7 @@
           "name": "speed",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.0",
               "name": "since"
             },
             {
@@ -370,7 +395,7 @@
           "name": "time",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.0",
               "name": "since"
             },
             {
@@ -387,10 +412,10 @@
     {
       "name": "CallbackError",
       "slug": "callbackerror",
-      "docs": "Error object that may be passed to the location watcher callback.\nExtends the standard Error with optional error codes.",
+      "docs": "Error object that may be passed to the location start callback.\nExtends the standard Error with optional error codes.",
       "tags": [
         {
-          "text": "1.0.0",
+          "text": "7.0.0",
           "name": "since"
         }
       ],
@@ -400,7 +425,7 @@
           "name": "code",
           "tags": [
             {
-              "text": "1.0.0",
+              "text": "7.0.0",
               "name": "since"
             },
             {
@@ -413,6 +438,31 @@
           "type": "string | undefined"
         }
       ]
+    },
+    {
+      "name": "PlaySoundOptions",
+      "slug": "playsoundoptions",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "soundFile",
+          "tags": [
+            {
+              "text": "7.0.10",
+              "name": "since"
+            },
+            {
+              "text": "\"notification.mp3\"",
+              "name": "example"
+            }
+          ],
+          "docs": "The name of the sound file to play.\nMust be a valid sound relative path in the app's public folder to work for both web and native platforms.\nThere's no need to include the public folder in the path.",
+          "complexTypes": [],
+          "type": "string"
+        }
+      ]
     }
   ],
   "enums": [],