@capgo/background-geolocation 7.0.10 → 7.0.11

package/README.md

@@ -58,8 +58,6 @@ BackgroundGeolocation.start(
             }
             return console.error(error);
         }
-        // in case of off-track for example, play a sound:
-        BackgroundGeolocation.playSound({soundFile: "assets/myFile.mp3" });
         return console.log(location);
     }
 ).then(() => {
@@ -67,6 +65,10 @@ BackgroundGeolocation.start(
     BackgroundGeolocation.stop();
 });
 
+// Set a planned route to get a notification sound when a new location arrives and it's not on the route:
+        
+BackgroundGeolocation.setPlannedRoute({soundFile: "assets/myFile.mp3", route: [[1,2], [3,4]], distance: 30 });
+
 // If you just want the current location, try something like this. The longer
 // the timeout, the more accurate the guess will be. I wouldn't go below about 100ms.
 function guessLocation(callback, timeout) {
@@ -177,7 +179,7 @@ Configration specific to Android can be made in `strings.xml`:
 * [`start(...)`](#start)
 * [`stop()`](#stop)
 * [`openSettings()`](#opensettings)
-* [`playSound(...)`](#playsound)
+* [`setPlannedRoute(...)`](#setplannedroute)
 * [Interfaces](#interfaces)
 
 </docgen-index>
@@ -235,23 +237,20 @@ Useful for directing users to enable location services or adjust permissions.
 --------------------
 
 
-### playSound(...)
+### setPlannedRoute(...)
 
 ```typescript
-playSound(options: PlaySoundOptions) => Promise<void>
+setPlannedRoute(options: SetPlannedRouteOptions) => Promise<void>
 ```
 
-Plays a sound file.
-This should be used to play a sound, in the background too.
-The idea behind this is to allow the user to hear a sound when a new location is available or when going off track.
-If you simply need to play a sound, you can use `@capgo/native-audio` plugin instead.
-For Android, there's a need to start monitoring location updates first, otherwise the sound will not play.
+Plays a sound file when the user deviates from the planned route.
+This should be used to play a sound (in the background too, only for native).
 
-| Param         | Type                                                          | Description                       |
-| ------------- | ------------------------------------------------------------- | --------------------------------- |
-| **`options`** | <code><a href="#playsoundoptions">PlaySoundOptions</a></code> | The options for playing the sound |
+| Param         | Type                                                                      | Description                                              |
+| ------------- | ------------------------------------------------------------------------- | -------------------------------------------------------- |
+| **`options`** | <code><a href="#setplannedrouteoptions">SetPlannedRouteOptions</a></code> | The options for setting the planned route and sound file |
 
-**Since:** 7.0.10
+**Since:** 7.0.11
 
 --------------------
 
@@ -300,10 +299,12 @@ Extends the standard Error with optional error codes.
 | **`code`** | <code>string</code> | Optional error code for more specific error handling. | 7.0.0 |
 
 
-#### PlaySoundOptions
+#### SetPlannedRouteOptions
 
-| Prop            | Type                | Description                                                                                                                                                                                             | Since  |
-| --------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
-| **`soundFile`** | <code>string</code> | The name of the sound file to play. Must be a valid sound relative path in the app's public folder to work for both web and native platforms. There's no need to include the public folder in the path. | 7.0.10 |
+| Prop            | Type                            | Description                                                                                                                                                                                                                                        | Default         | Since  |
+| --------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------ |
+| **`soundFile`** | <code>string</code>             | The name of the sound file to play. Must be a valid sound relative path in the app's public folder to work for both web and native platforms. There's no need to include the public folder in the path.                                            |                 | 7.0.10 |
+| **`route`**     | <code>[number, number][]</code> | The planned route as an array of longitude and latitude pairs. Each pair represents a point on the route. This is used to define a route that the user can follow. The route is used to play a sound when the user deviates from it.               |                 | 7.0.11 |
+| **`distance`**  | <code>number</code>             | The distance in meters that the user must deviate from the planned route to trigger the sound. This is used to determine how far off the route the user can be before the sound is played. If not specified, a default value of 50 meters is used. | <code>50</code> | 7.0.11 |
 
 </docgen-api>

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

@@ -15,7 +15,9 @@ import android.net.Uri;
 import android.os.Build;
 import android.os.IBinder;
 import android.provider.Settings;
+import androidx.annotation.Nullable;
 import androidx.localbroadcastmanager.content.LocalBroadcastManager;
+import com.getcapacitor.JSArray;
 import com.getcapacitor.JSObject;
 import com.getcapacitor.Logger;
 import com.getcapacitor.PermissionState;
@@ -27,6 +29,8 @@ import com.getcapacitor.annotation.Permission;
 import com.getcapacitor.annotation.PermissionCallback;
 import com.google.android.gms.location.LocationServices;
 import java.util.concurrent.CompletableFuture;
+import org.json.JSONArray;
+import org.json.JSONException;
 import org.json.JSONObject;
 
 @CapacitorPlugin(
@@ -189,7 +193,7 @@ public class BackgroundGeolocation extends Plugin {
   }
 
   @PluginMethod
-  public void playSound(PluginCall call) {
+  public void setPlannedRoute(PluginCall call) {
     String soundFile = call.getString("soundFile");
     if (soundFile == null || soundFile.isEmpty()) {
       call.reject("Sound file is required");
@@ -202,15 +206,48 @@ public class BackgroundGeolocation extends Plugin {
       );
       return;
     }
-    serviceConnectionFuture
-      .thenAccept(service -> {
-        service.playSound(soundFile);
-        call.resolve();
-      })
-      .exceptionally(throwable -> {
-        call.reject("Failed to play sound: " + throwable.getMessage());
-        return null;
-      });
+    try {
+      double[][] javaDoubleArray = getJavaDoubleArray(call.getArray("route"));
+      serviceConnectionFuture
+        .thenAccept(service -> {
+          service.setPlannedRoute(
+            soundFile,
+            javaDoubleArray,
+            call.getFloat("distance", 50f)
+          );
+          call.resolve();
+        })
+        .exceptionally(throwable -> {
+          call.reject("Failed to set route: " + throwable.getMessage());
+          return null;
+        });
+    } catch (Exception ex) {
+      call.reject("Unable to parse route parameters");
+    }
+  }
+
+  private static double[][] getJavaDoubleArray(JSArray jsArray)
+    throws JSONException {
+    int rows = jsArray.length();
+    if (rows == 0) {
+      return new double[0][2];
+    }
+
+    JSONArray firstRow = jsArray.getJSONArray(0);
+    int cols = firstRow.length();
+
+    var javaDoubleArray = new double[rows][cols];
+
+    for (int i = 0; i < rows; i++) {
+      JSONArray rowArray = jsArray.getJSONArray(i);
+      if (rowArray.length() != cols) {
+        throw new JSONException("Input array is not a consistent 2D array.");
+      }
+      for (int j = 0; j < cols; j++) {
+        javaDoubleArray[i][j] = rowArray.getDouble(j);
+      }
+    }
+    return javaDoubleArray;
   }
 
   // Checks if device-wide location services are disabled

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

@@ -26,6 +26,8 @@ public class BackgroundGeolocationService extends Service {
     (BackgroundGeolocationService.class.getPackage().getName() + ".broadcast");
   private final IBinder binder = new LocalBinder();
 
+  private static final double EARTH_RADIUS_M = 6371000;
+
   // Must be unique for this application.
   private static final int NOTIFICATION_ID = 28351;
 
@@ -34,6 +36,9 @@ public class BackgroundGeolocationService extends Service {
   private LocationManager client;
   private LocationListener locationCallback;
   private MediaPlayer mediaPlayer;
+  private double[][] route;
+  private double distanceThreshold;
+  private boolean isOffRoute;
 
   @Override
   public IBinder onBind(Intent intent) {
@@ -83,10 +88,19 @@ public class BackgroundGeolocationService extends Service {
       final String notificationMessage,
       float distanceFilter
     ) {
+      releaseMediaPlayer();
       client = (LocationManager) getSystemService(Context.LOCATION_SERVICE);
       callbackId = id;
 
       locationCallback = location -> {
+        if (mediaPlayer != null) {
+          double[] point = { location.getLongitude(), location.getLatitude() };
+          var offRoute = distancePointToRoute(point) > distanceThreshold;
+          if (offRoute == true && isOffRoute == false) {
+            mediaPlayer.start();
+          }
+          isOffRoute = offRoute;
+        }
         Intent intent = new Intent(ACTION_BROADCAST);
         intent.putExtra("location", location);
         intent.putExtra("id", callbackId);
@@ -131,15 +145,23 @@ public class BackgroundGeolocationService extends Service {
       client.removeUpdates(locationCallback);
       stopForeground(true);
       stopSelf();
+      releaseMediaPlayer();
       return callbackId;
     }
 
-    void playSound(String filePath) {
+    void setPlannedRoute(
+      String filePath,
+      double[][] routeCoordinates,
+      float distance
+    ) {
+      route = routeCoordinates;
+      distanceThreshold = distance;
+      isOffRoute = true;
       try {
-        releaseMediaPlayer();
-
+        if (mediaPlayer != null) {
+          return;
+        }
         mediaPlayer = new MediaPlayer();
-
         AssetManager am = getApplicationContext().getResources().getAssets();
         AssetFileDescriptor assetFileDescriptor = am.openFd(
           "public/" + filePath
@@ -152,15 +174,6 @@ public class BackgroundGeolocationService extends Service {
         );
         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();
@@ -168,15 +181,6 @@ public class BackgroundGeolocationService extends Service {
         });
 
         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();
@@ -272,4 +276,100 @@ public class BackgroundGeolocationService extends Service {
     int id = getAppResourceIdentifier(name, "string", context);
     return id == 0 ? fallback : context.getString(id);
   }
+
+  private static double haversine(double[] point1, double[] point2) {
+    double lon1 = point1[0];
+    double lat1 = point1[1];
+    double lon2 = point2[0];
+    double lat2 = point2[1];
+
+    double dLat = Math.toRadians(lat2 - lat1);
+    double dLon = Math.toRadians(lon2 - lon1);
+
+    double a =
+      Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+      Math.cos(Math.toRadians(lat1)) *
+      Math.cos(Math.toRadians(lat2)) *
+      Math.sin(dLon / 2) *
+      Math.sin(dLon / 2);
+
+    double c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+
+    return EARTH_RADIUS_M * c;
+  }
+
+  private static double distancePointToLineSegment(
+    double[] point,
+    double[] lineStart,
+    double[] lineEnd
+  ) {
+    // Calculate the distances between the three points using Haversine
+    double dist_A_B = haversine(point, lineStart);
+    double dist_A_C = haversine(point, lineEnd);
+    double dist_B_C = haversine(lineStart, lineEnd);
+
+    // Handle the edge case where the line segment is a single point
+    if (dist_B_C == 0) {
+      return dist_A_B;
+    }
+
+    // Check if the angles at the line segment's endpoints are obtuse.
+    // We use the Law of Cosines (c^2 = a^2 + b^2 - 2ab*cos(C))
+    // If cos(C) < 0, the angle is obtuse.
+
+    // Angle at B (lineStart)
+    // Use a small epsilon to handle floating point inaccuracies in division by zero
+    double cos_B =
+      (Math.pow(dist_A_B, 2) + Math.pow(dist_B_C, 2) - Math.pow(dist_A_C, 2)) /
+      (2 * dist_A_B * dist_B_C);
+    if (cos_B < 0) {
+      return dist_A_B;
+    }
+
+    // Angle at C (lineEnd)
+    double cos_C =
+      (Math.pow(dist_A_C, 2) + Math.pow(dist_B_C, 2) - Math.pow(dist_A_B, 2)) /
+      (2 * dist_A_C * dist_B_C);
+    if (cos_C < 0) {
+      return dist_A_C;
+    }
+
+    // If both angles are acute, the closest point is on the line segment itself.
+    // We can calculate the distance (height of the triangle) using its area.
+
+    // 1. Calculate the semi-perimeter of the triangle ABC
+    double s = (dist_A_B + dist_A_C + dist_B_C) / 2;
+
+    // 2. Calculate the area using Heron's formula
+    double area = Math.sqrt(
+      Math.max(0, s * (s - dist_A_B) * (s - dist_A_C) * (s - dist_B_C))
+    );
+
+    // 3. The distance is the height of the triangle from point A to the base BC
+    // Area = 0.5 * base * height  =>  height = 2 * Area / base
+    return (2 * area) / dist_B_C;
+  }
+
+  public double distancePointToRoute(double[] point) {
+    // If the polyline has less than 2 points, we can't form a segment.
+    if (this.route.length < 2) {
+      if (this.route.length == 1) {
+        return haversine(point, this.route[0]);
+      }
+      return Double.POSITIVE_INFINITY; // No line segments to measure against
+    }
+
+    double minDistance = Double.POSITIVE_INFINITY;
+
+    for (int i = 0; i < this.route.length - 1; i++) {
+      double[] lineStart = this.route[i];
+      double[] lineEnd = this.route[i + 1];
+      double distance = distancePointToLineSegment(point, lineStart, lineEnd);
+      if (distance < minDistance) {
+        minDistance = distance;
+      }
+    }
+
+    return minDistance;
+  }
 }

package/dist/docs.json

@@ -103,39 +103,39 @@
         "slug": "opensettings"
       },
       {
-        "name": "playSound",
-        "signature": "(options: PlaySoundOptions) => Promise<void>",
+        "name": "setPlannedRoute",
+        "signature": "(options: SetPlannedRouteOptions) => Promise<void>",
         "parameters": [
           {
             "name": "options",
-            "docs": "The options for playing the sound",
-            "type": "PlaySoundOptions"
+            "docs": "The options for setting the planned route and sound file",
+            "type": "SetPlannedRouteOptions"
           }
         ],
         "returns": "Promise<void>",
         "tags": [
           {
             "name": "param",
-            "text": "options The options for playing the sound"
+            "text": "options The options for setting the planned route and sound file"
           },
           {
             "name": "returns",
-            "text": "A promise that resolves when the sound is successfully played"
+            "text": "A promise that resolves when the route is set successfully"
           },
           {
             "name": "since",
-            "text": "7.0.10"
+            "text": "7.0.11"
           },
           {
             "name": "example",
-            "text": "await BackgroundGeolocation.playSound({\n  soundFile: \"notification.mp3\"\n});"
+            "text": "await BackgroundGeolocation.setPlannedRoute({\n  soundFile: \"notification.mp3\",\n  route: [[-74.0060, 40.7128], [-118.2437, 34.0522]]\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.",
+        "docs": "Plays a sound file when the user deviates from the planned route.\nThis should be used to play a sound (in the background too, only for native).",
         "complexTypes": [
-          "PlaySoundOptions"
+          "SetPlannedRouteOptions"
         ],
-        "slug": "playsound"
+        "slug": "setplannedroute"
       }
     ],
     "properties": []
@@ -440,8 +440,8 @@
       ]
     },
     {
-      "name": "PlaySoundOptions",
-      "slug": "playsoundoptions",
+      "name": "SetPlannedRouteOptions",
+      "slug": "setplannedrouteoptions",
       "docs": "",
       "tags": [],
       "methods": [],
@@ -461,6 +461,42 @@
           "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"
+        },
+        {
+          "name": "route",
+          "tags": [
+            {
+              "text": "7.0.11",
+              "name": "since"
+            },
+            {
+              "text": "[[-74.0060, 40.7128], [-118.2437, 34.0522]]",
+              "name": "example"
+            }
+          ],
+          "docs": "The planned route as an array of longitude and latitude pairs.\nEach pair represents a point on the route.\nThis is used to define a route that the user can follow.\nThe route is used to play a sound when the user deviates from it.",
+          "complexTypes": [],
+          "type": "[number, number][]"
+        },
+        {
+          "name": "distance",
+          "tags": [
+            {
+              "text": "7.0.11",
+              "name": "since"
+            },
+            {
+              "text": "50",
+              "name": "default"
+            },
+            {
+              "text": "50",
+              "name": "example"
+            }
+          ],
+          "docs": "The distance in meters that the user must deviate from the planned route to trigger the sound.\nThis is used to determine how far off the route the user can be before the sound is played.\nIf not specified, a default value of 50 meters is used.",
+          "complexTypes": [],
+          "type": "number"
         }
       ]
     }

package/dist/esm/definitions.d.ts

@@ -162,7 +162,7 @@ export interface CallbackError extends Error {
      */
     code?: string;
 }
-export interface PlaySoundOptions {
+export interface SetPlannedRouteOptions {
     /**
      * The name of the sound file to play.
      * Must be a valid sound relative path in the app's public folder to work for both web and native platforms.
@@ -171,6 +171,24 @@ export interface PlaySoundOptions {
      * @example "notification.mp3"
      * */
     soundFile: string;
+    /**
+     * The planned route as an array of longitude and latitude pairs.
+     * Each pair represents a point on the route.
+     * This is used to define a route that the user can follow.
+     * The route is used to play a sound when the user deviates from it.
+     * @since 7.0.11
+     * @example [[-74.0060, 40.7128], [-118.2437, 34.0522]]
+     */
+    route: [number, number][];
+    /**
+     * The distance in meters that the user must deviate from the planned route to trigger the sound.
+     * This is used to determine how far off the route the user can be before the sound is played.
+     * If not specified, a default value of 50 meters is used.
+     * @since 7.0.11
+     * @default 50
+     * @example 50
+     */
+    distance: number;
 }
 /**
  * Main plugin interface for background geolocation functionality.
@@ -233,20 +251,18 @@ export interface BackgroundGeolocationPlugin {
      */
     openSettings(): Promise<void>;
     /**
-     * Plays a sound file.
-     * This should be used to play a sound, in the background too.
-     * The idea behind this is to allow the user to hear a sound when a new location is available or when going off track.
-     * If you simply need to play a sound, you can use `@capgo/native-audio` plugin instead.
-     * For Android, there's a need to start monitoring location updates first, otherwise the sound will not play.
+     * Plays a sound file when the user deviates from the planned route.
+     * This should be used to play a sound (in the background too, only for native).
      *
-     * @param options The options for playing the sound
-     * @returns A promise that resolves when the sound is successfully played
+     * @param options The options for setting the planned route and sound file
+     * @returns A promise that resolves when the route is set successfully
      *
-     * @since 7.0.10
+     * @since 7.0.11
      * @example
-     * await BackgroundGeolocation.playSound({
-     *   soundFile: "notification.mp3"
+     * await BackgroundGeolocation.setPlannedRoute({
+     *   soundFile: "notification.mp3",
+     *   route: [[-74.0060, 40.7128], [-118.2437, 34.0522]]
      * });
      */
-    playSound(options: PlaySoundOptions): Promise<void>;
+    setPlannedRoute(options: SetPlannedRouteOptions): Promise<void>;
 }

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The options for configuring for location updates.\n *\n * @since 7.0.9\n */\nexport interface StartOptions {\n  /**\n   * If the \"backgroundMessage\" option is defined, the plugin will\n   * provide location updates whether the app is in the background or the\n   * foreground. If it is not defined, location updates are only\n   * guaranteed in the foreground. This is true on both platforms.\n   *\n   * On Android, a notification must be shown to continue receiving\n   * location updates in the background. This option specifies the text of\n   * that notification.\n   *\n   * @since 7.0.9\n   * @example \"Getting your location to provide better service\"\n   */\n  backgroundMessage?: string;\n  /**\n   * The title of the notification mentioned above.\n   *\n   * @since 7.0.9\n   * @default \"Using your location\"\n   * @example \"Location Service\"\n   */\n  backgroundTitle?: string;\n  /**\n   * Whether permissions should be requested from the user automatically,\n   * if they are not already granted.\n   *\n   * @since 7.0.9\n   * @default true\n   * @example\n   * // Auto-request permissions\n   * requestPermissions: true\n   *\n   * // Don't auto-request, handle manually\n   * requestPermissions: false\n   */\n  requestPermissions?: boolean;\n  /**\n   * If \"true\", stale locations may be delivered while the device\n   * obtains a GPS fix. You are responsible for checking the \"time\"\n   * property. If \"false\", locations are guaranteed to be up to date.\n   *\n   * @since 7.0.9\n   * @default false\n   * @example\n   * // Allow stale locations for faster initial response\n   * stale: true\n   *\n   * // Only fresh locations\n   * stale: false\n   */\n  stale?: boolean;\n  /**\n   * The distance in meters that the device must move before a new location update is triggered.\n   * This is used to filter out small movements and reduce the number of updates.\n   *\n   * @since 7.0.9\n   * @default 0\n   * @example\n   * // Update every 10 meters\n   * distanceFilter: 10\n   *\n   * // Update on any movement\n   * distanceFilter: 0\n   */\n  distanceFilter?: number;\n}\n\n/**\n * Represents a geographical location with various attributes.\n * Contains all the standard location properties returned by GPS/network providers.\n *\n * @since 7.0.0\n */\nexport interface Location {\n  /**\n   * Latitude in degrees.\n   * Range: -90.0 to +90.0\n   *\n   * @since 7.0.0\n   * @example 40.7128\n   */\n  latitude: number;\n  /**\n   * Longitude in degrees.\n   * Range: -180.0 to +180.0\n   *\n   * @since 7.0.0\n   * @example -74.0060\n   */\n  longitude: number;\n  /**\n   * Radius of horizontal uncertainty in metres, with 68% confidence.\n   * Lower values indicate more accurate location.\n   *\n   * @since 7.0.0\n   * @example 5.0\n   */\n  accuracy: number;\n  /**\n   * Metres above sea level (or null if not available).\n   *\n   * @since 7.0.0\n   * @example 10.5\n   */\n  altitude: number | null;\n  /**\n   * Vertical uncertainty in metres, with 68% confidence (or null if not available).\n   *\n   * @since 7.0.0\n   * @example 3.0\n   */\n  altitudeAccuracy: number | null;\n  /**\n   * `true` if the location was simulated by software, rather than GPS.\n   * Useful for detecting mock locations in development or testing.\n   *\n   * @since 7.0.0\n   * @example false\n   */\n  simulated: boolean;\n  /**\n   * Deviation from true north in degrees (or null if not available).\n   * Range: 0.0 to 360.0\n   *\n   * @since 7.0.0\n   * @example 45.5\n   */\n  bearing: number | null;\n  /**\n   * Speed in metres per second (or null if not available).\n   *\n   * @since 7.0.0\n   * @example 2.5\n   */\n  speed: number | null;\n  /**\n   * Time the location was produced, in milliseconds since the unix epoch.\n   * Use this to check if a location is stale when using stale: true.\n   *\n   * @since 7.0.0\n   * @example 1640995200000\n   */\n  time: number | null;\n}\n\n/**\n * Error object that may be passed to the location start callback.\n * Extends the standard Error with optional error codes.\n *\n * @since 7.0.0\n */\nexport interface CallbackError extends Error {\n  /**\n   * Optional error code for more specific error handling.\n   *\n   * @since 7.0.0\n   * @example \"PERMISSION_DENIED\"\n   */\n  code?: string;\n}\n\nexport interface PlaySoundOptions {\n  /**\n   * The name of the sound file to play.\n   * Must be a valid sound relative path in the app's public folder to work for both web and native platforms.\n   * There's no need to include the public folder in the path.\n   * @since 7.0.10\n   * @example \"notification.mp3\"\n   * */\n  soundFile: string;\n}\n\n/**\n * Main plugin interface for background geolocation functionality.\n * Provides methods to manage location updates and access device settings.\n *\n * @since 7.0.0\n */\nexport interface BackgroundGeolocationPlugin {\n  /**\n   * To start listening for changes in the device's location, call this method.\n   * A Promise is returned to indicate that it finished the call. The callback will be called every time a new location\n   * is available, or if there was an error when calling this method. Don't rely on promise rejection for this.\n   *\n   * @param options The configuration options\n   * @param callback The callback function invoked when a new location is available or an error occurs\n   * @returns A promise that resolves when the method is successfully called\n   *\n   * @since 7.0.9\n   * @example\n   * 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   * );\n   */\n  start(\n    options: StartOptions,\n    callback: (position?: Location, error?: CallbackError) => void,\n  ): Promise<void>;\n\n  /**\n   * Stops location updates.\n   *\n   * @returns A promise that resolves when the plugin stops successfully removed\n   *\n   * @since 7.0.9\n   * @example\n   * await BackgroundGeolocation.stop();\n   */\n  stop(): Promise<void>;\n\n  /**\n   * Opens the device's location settings page.\n   * Useful for directing users to enable location services or adjust permissions.\n   *\n   * @returns A promise that resolves when the settings page is opened\n   *\n   * @since 7.0.0\n   * @example\n   * // Direct user to location settings\n   * await BackgroundGeolocation.openSettings();\n   */\n  openSettings(): Promise<void>;\n\n  /**\n   * Plays a sound file.\n   * This should be used to play a sound, in the background too.\n   * The idea behind this is to allow the user to hear a sound when a new location is available or when going off track.\n   * If you simply need to play a sound, you can use `@capgo/native-audio` plugin instead.\n   * For Android, there's a need to start monitoring location updates first, otherwise the sound will not play.\n   *\n   * @param options The options for playing the sound\n   * @returns A promise that resolves when the sound is successfully played\n   *\n   * @since 7.0.10\n   * @example\n   * await BackgroundGeolocation.playSound({\n   *   soundFile: \"notification.mp3\"\n   * });\n   */\n  playSound(options: PlaySoundOptions): Promise<void>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The options for configuring for location updates.\n *\n * @since 7.0.9\n */\nexport interface StartOptions {\n  /**\n   * If the \"backgroundMessage\" option is defined, the plugin will\n   * provide location updates whether the app is in the background or the\n   * foreground. If it is not defined, location updates are only\n   * guaranteed in the foreground. This is true on both platforms.\n   *\n   * On Android, a notification must be shown to continue receiving\n   * location updates in the background. This option specifies the text of\n   * that notification.\n   *\n   * @since 7.0.9\n   * @example \"Getting your location to provide better service\"\n   */\n  backgroundMessage?: string;\n  /**\n   * The title of the notification mentioned above.\n   *\n   * @since 7.0.9\n   * @default \"Using your location\"\n   * @example \"Location Service\"\n   */\n  backgroundTitle?: string;\n  /**\n   * Whether permissions should be requested from the user automatically,\n   * if they are not already granted.\n   *\n   * @since 7.0.9\n   * @default true\n   * @example\n   * // Auto-request permissions\n   * requestPermissions: true\n   *\n   * // Don't auto-request, handle manually\n   * requestPermissions: false\n   */\n  requestPermissions?: boolean;\n  /**\n   * If \"true\", stale locations may be delivered while the device\n   * obtains a GPS fix. You are responsible for checking the \"time\"\n   * property. If \"false\", locations are guaranteed to be up to date.\n   *\n   * @since 7.0.9\n   * @default false\n   * @example\n   * // Allow stale locations for faster initial response\n   * stale: true\n   *\n   * // Only fresh locations\n   * stale: false\n   */\n  stale?: boolean;\n  /**\n   * The distance in meters that the device must move before a new location update is triggered.\n   * This is used to filter out small movements and reduce the number of updates.\n   *\n   * @since 7.0.9\n   * @default 0\n   * @example\n   * // Update every 10 meters\n   * distanceFilter: 10\n   *\n   * // Update on any movement\n   * distanceFilter: 0\n   */\n  distanceFilter?: number;\n}\n\n/**\n * Represents a geographical location with various attributes.\n * Contains all the standard location properties returned by GPS/network providers.\n *\n * @since 7.0.0\n */\nexport interface Location {\n  /**\n   * Latitude in degrees.\n   * Range: -90.0 to +90.0\n   *\n   * @since 7.0.0\n   * @example 40.7128\n   */\n  latitude: number;\n  /**\n   * Longitude in degrees.\n   * Range: -180.0 to +180.0\n   *\n   * @since 7.0.0\n   * @example -74.0060\n   */\n  longitude: number;\n  /**\n   * Radius of horizontal uncertainty in metres, with 68% confidence.\n   * Lower values indicate more accurate location.\n   *\n   * @since 7.0.0\n   * @example 5.0\n   */\n  accuracy: number;\n  /**\n   * Metres above sea level (or null if not available).\n   *\n   * @since 7.0.0\n   * @example 10.5\n   */\n  altitude: number | null;\n  /**\n   * Vertical uncertainty in metres, with 68% confidence (or null if not available).\n   *\n   * @since 7.0.0\n   * @example 3.0\n   */\n  altitudeAccuracy: number | null;\n  /**\n   * `true` if the location was simulated by software, rather than GPS.\n   * Useful for detecting mock locations in development or testing.\n   *\n   * @since 7.0.0\n   * @example false\n   */\n  simulated: boolean;\n  /**\n   * Deviation from true north in degrees (or null if not available).\n   * Range: 0.0 to 360.0\n   *\n   * @since 7.0.0\n   * @example 45.5\n   */\n  bearing: number | null;\n  /**\n   * Speed in metres per second (or null if not available).\n   *\n   * @since 7.0.0\n   * @example 2.5\n   */\n  speed: number | null;\n  /**\n   * Time the location was produced, in milliseconds since the unix epoch.\n   * Use this to check if a location is stale when using stale: true.\n   *\n   * @since 7.0.0\n   * @example 1640995200000\n   */\n  time: number | null;\n}\n\n/**\n * Error object that may be passed to the location start callback.\n * Extends the standard Error with optional error codes.\n *\n * @since 7.0.0\n */\nexport interface CallbackError extends Error {\n  /**\n   * Optional error code for more specific error handling.\n   *\n   * @since 7.0.0\n   * @example \"PERMISSION_DENIED\"\n   */\n  code?: string;\n}\n\nexport interface SetPlannedRouteOptions {\n  /**\n   * The name of the sound file to play.\n   * Must be a valid sound relative path in the app's public folder to work for both web and native platforms.\n   * There's no need to include the public folder in the path.\n   * @since 7.0.10\n   * @example \"notification.mp3\"\n   * */\n  soundFile: string;\n  /**\n   * The planned route as an array of longitude and latitude pairs.\n   * Each pair represents a point on the route.\n   * This is used to define a route that the user can follow.\n   * The route is used to play a sound when the user deviates from it.\n   * @since 7.0.11\n   * @example [[-74.0060, 40.7128], [-118.2437, 34.0522]]\n   */\n  route: [number, number][];\n\n  /**\n   * The distance in meters that the user must deviate from the planned route to trigger the sound.\n   * This is used to determine how far off the route the user can be before the sound is played.\n   * If not specified, a default value of 50 meters is used.\n   * @since 7.0.11\n   * @default 50\n   * @example 50\n   */\n  distance: number;\n}\n\n/**\n * Main plugin interface for background geolocation functionality.\n * Provides methods to manage location updates and access device settings.\n *\n * @since 7.0.0\n */\nexport interface BackgroundGeolocationPlugin {\n  /**\n   * To start listening for changes in the device's location, call this method.\n   * A Promise is returned to indicate that it finished the call. The callback will be called every time a new location\n   * is available, or if there was an error when calling this method. Don't rely on promise rejection for this.\n   *\n   * @param options The configuration options\n   * @param callback The callback function invoked when a new location is available or an error occurs\n   * @returns A promise that resolves when the method is successfully called\n   *\n   * @since 7.0.9\n   * @example\n   * 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   * );\n   */\n  start(\n    options: StartOptions,\n    callback: (position?: Location, error?: CallbackError) => void,\n  ): Promise<void>;\n\n  /**\n   * Stops location updates.\n   *\n   * @returns A promise that resolves when the plugin stops successfully removed\n   *\n   * @since 7.0.9\n   * @example\n   * await BackgroundGeolocation.stop();\n   */\n  stop(): Promise<void>;\n\n  /**\n   * Opens the device's location settings page.\n   * Useful for directing users to enable location services or adjust permissions.\n   *\n   * @returns A promise that resolves when the settings page is opened\n   *\n   * @since 7.0.0\n   * @example\n   * // Direct user to location settings\n   * await BackgroundGeolocation.openSettings();\n   */\n  openSettings(): Promise<void>;\n\n  /**\n   * Plays a sound file when the user deviates from the planned route.\n   * This should be used to play a sound (in the background too, only for native).\n   *\n   * @param options The options for setting the planned route and sound file\n   * @returns A promise that resolves when the route is set successfully\n   *\n   * @since 7.0.11\n   * @example\n   * await BackgroundGeolocation.setPlannedRoute({\n   *   soundFile: \"notification.mp3\",\n   *   route: [[-74.0060, 40.7128], [-118.2437, 34.0522]]\n   * });\n   */\n  setPlannedRoute(options: SetPlannedRouteOptions): Promise<void>;\n}\n"]}

package/dist/esm/web.d.ts

@@ -1,9 +1,18 @@
 import { WebPlugin } from "@capacitor/core";
-import type { BackgroundGeolocationPlugin, StartOptions, Location, CallbackError, PlaySoundOptions } from "./definitions";
+import type { BackgroundGeolocationPlugin, StartOptions, Location, CallbackError, SetPlannedRouteOptions } from "./definitions";
 export declare class BackgroundGeolocationWeb extends WebPlugin implements BackgroundGeolocationPlugin {
+    private static readonly EARTH_RADIUS_M;
     private watchId;
+    private plannedRoute;
+    private audio;
+    private isOffRoute;
+    private distanceThreshold;
     start(options: StartOptions, callback: (position?: Location, error?: CallbackError) => void): Promise<void>;
     stop(): Promise<void>;
     openSettings(): Promise<void>;
-    playSound(options: PlaySoundOptions): Promise<void>;
+    setPlannedRoute(options: SetPlannedRouteOptions): Promise<void>;
+    private toRadians;
+    private haversine;
+    private distancePointToLineSegment;
+    private distancePointToRoute;
 }