@capgo/background-geolocation 8.0.33 → 8.0.35

package/README.md

@@ -1,5 +1,5 @@
 # Background Geolocation
- <a href="https://capgo.app/"><img src='https://raw.githubusercontent.com/Cap-go/capgo/main/assets/capgo_banner.png' alt='Capgo - Instant updates for capacitor'/></a>
+<a href="https://capgo.app/"><img src="https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-background-geolocation" alt="Capgo - Instant updates for Capacitor" /></a>
 
 <div align="center">
   <h2><a href="https://capgo.app/?ref=plugin_background_geolocation"> ➡️ Get Instant updates for your App with Capgo</a></h2>
@@ -97,15 +97,13 @@ BackgroundGeolocation.setPlannedRoute({soundFile: "assets/myFile.mp3", route: [[
 
 ## Native geofencing
 
-Use native geofencing when you need lightweight location boundaries such as stores, job sites, delivery zones, campuses, or check-in areas. The plugin monitors geofences natively, emits JavaScript events while the app is active, and can send transition payloads directly to your backend while the WebView is suspended.
+Use native geofencing when you need lightweight location boundaries such as stores, job sites, delivery zones, campuses, or check-in areas. The plugin monitors geofences natively and emits JavaScript events while the app is active. Android background delivery is optional and only requested when you opt in.
 
 ```javascript
 import { BackgroundGeolocation } from "@capgo/background-geolocation";
 
-// Geofencing can notify JavaScript while the app is alive and can also POST
-// transitions natively while the WebView is suspended.
+// Geofencing can notify JavaScript while the app is alive.
 await BackgroundGeolocation.setupGeofencing({
-    url: "https://api.example.com/geofences",
     notifyOnEntry: true,
     notifyOnExit: true,
     payload: { userId: "123" }
@@ -129,13 +127,20 @@ handle.remove();
 
 ### Android background geofence permission
 
-The plugin does not add `ACCESS_BACKGROUND_LOCATION` by default. Add it to your app manifest only when you need background geofencing or background location updates:
+The plugin does not add `ACCESS_BACKGROUND_LOCATION` by default and does not request it unless you explicitly opt in. Apps that only use foreground location can omit this permission.
+
+Opt in only when you need Android geofence transitions while the app is in the background:
 
 ```xml
 <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
 ```
 
-Apps that only use foreground location can omit this permission.
+```javascript
+await BackgroundGeolocation.setupGeofencing({
+    url: "https://api.example.com/geofences",
+    backgroundLocation: true
+});
+```
 
 ```javascript
 // If you just want the current location, try something like this. The longer
@@ -211,7 +216,7 @@ Set the the `android.useLegacyBridge` option to `true` in your Capacitor configu
 
 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.
 
-For geofencing on Android 10+, the app also needs `ACCESS_BACKGROUND_LOCATION`. Android may require the user to grant this from system settings after foreground location is granted; use `openSettings()` if the permission remains denied.
+For background geofencing on Android 10+, the app also needs `ACCESS_BACKGROUND_LOCATION` and `backgroundLocation: true` in `setupGeofencing()`. Android may require the user to grant this from system settings after foreground location is granted; use `openSettings()` if the permission remains denied. Leave `backgroundLocation` unset or `false` if your app does not have Google Play approval for Android background location.
 
 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.
 
@@ -359,8 +364,9 @@ setupGeofencing(options: GeofenceSetupOptions) => Promise<void>
 
 Configures native geofence transition handling.
 
-Call this before adding geofences when you need native background POSTs
-or default entry/exit settings.
+Call this before adding geofences when you need default entry/exit settings
+or native background POSTs. Android background POSTs require
+`backgroundLocation: true`.
 
 | Param         | Type                                                                  | Description                        |
 | ------------- | --------------------------------------------------------------------- | ---------------------------------- |
@@ -546,17 +552,18 @@ Extends the standard Error with optional error codes.
 
 Options for configuring native geofence transition handling.
 
-When `url` is provided, native iOS and Android code sends a JSON `POST`
-whenever a monitored region is entered or exited. This keeps geofence
-handling useful when the WebView is suspended.
-
-| Prop                     | Type                                                             | Description                                                                                                                                                                                                                                              | Default           | Since  |
-| ------------------------ | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------ |
-| **`url`**                | <code>string</code>                                              | Endpoint that receives geofence transition payloads.                                                                                                                                                                                                     |                   | 8.0.30 |
-| **`notifyOnEntry`**      | <code>boolean</code>                                             | Whether entry transitions should be monitored.                                                                                                                                                                                                           | <code>true</code> | 8.0.30 |
-| **`notifyOnExit`**       | <code>boolean</code>                                             | Whether exit transitions should be monitored.                                                                                                                                                                                                            | <code>true</code> | 8.0.30 |
-| **`payload`**            | <code><a href="#record">Record</a>&lt;string, unknown&gt;</code> | Base JSON payload merged into every native transition POST and listener event.                                                                                                                                                                           |                   | 8.0.30 |
-| **`requestPermissions`** | <code>boolean</code>                                             | Whether the plugin should request the native location permission needed for geofencing. iOS geofencing needs Always location authorization. Android background geofencing needs foreground location and, on Android 10+, background location permission. | <code>true</code> | 8.0.30 |
+When `url` is provided, native code can send a JSON `POST` whenever a
+monitored region is entered or exited. Android background POST delivery
+requires `backgroundLocation: true`.
+
+| Prop                     | Type                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Default            | Since  |
+| ------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ------ |
+| **`url`**                | <code>string</code>                                              | Endpoint that receives geofence transition payloads. On Android, native background POST delivery requires `backgroundLocation: true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |                    | 8.0.30 |
+| **`notifyOnEntry`**      | <code>boolean</code>                                             | Whether entry transitions should be monitored.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | <code>true</code>  | 8.0.30 |
+| **`notifyOnExit`**       | <code>boolean</code>                                             | Whether exit transitions should be monitored.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | <code>true</code>  | 8.0.30 |
+| **`payload`**            | <code><a href="#record">Record</a>&lt;string, unknown&gt;</code> | Base JSON payload merged into every native transition POST and listener event.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                    | 8.0.30 |
+| **`requestPermissions`** | <code>boolean</code>                                             | Whether the plugin should request the native location permission needed for geofencing. iOS geofencing needs Always location authorization. Android geofencing requests foreground location by default. Android background location is only requested when `backgroundLocation` is enabled.                                                                                                                                                                                                                                                                                                                                    | <code>true</code>  | 8.0.30 |
+| **`backgroundLocation`** | <code>boolean</code>                                             | Whether Android geofencing should opt into background location permission. The plugin does not add `ACCESS_BACKGROUND_LOCATION` to your app manifest. Leave this disabled if your app does not have Google Play approval for Android background location. Enable it only after adding `ACCESS_BACKGROUND_LOCATION` to your app manifest and when you need Android geofence transitions while the app is in the background. This option only affects Android. Android versions below 10 do not request an extra background-location runtime permission, but the option still gates native Android background geofence delivery. | <code>false</code> | 8.0.34 |
 
 
 #### AddGeofenceOptions

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

@@ -228,25 +228,34 @@ public class BackgroundGeolocation extends Plugin {
         }
 
         JSObject payload = call.getObject("payload", new JSObject());
-        GeofenceStore.saveSetup(getContext(), url, call.getBoolean("notifyOnEntry", true), call.getBoolean("notifyOnExit", true), payload);
+        boolean backgroundLocation = call.getBoolean("backgroundLocation", false);
+        GeofenceStore.saveSetup(
+            getContext(),
+            url,
+            call.getBoolean("notifyOnEntry", true),
+            call.getBoolean("notifyOnExit", true),
+            payload,
+            backgroundLocation
+        );
 
         if (!call.getBoolean("requestPermissions", true)) {
             call.resolve();
             return;
         }
 
-        requestGeofencePermissions(call)
+        requestGeofencePermissions(call, backgroundLocation)
             .thenRun(call::resolve)
             .exceptionally((throwable) -> {
-                call.reject("Background location permission is required for geofencing", "NOT_AUTHORIZED");
+                call.reject(geofencePermissionMessage(backgroundLocation), "NOT_AUTHORIZED");
                 return null;
             });
     }
 
     @PluginMethod
     public void addGeofence(PluginCall call) {
-        if (!hasGeofencePermissions()) {
-            call.reject("Background location permission is required for geofencing", "NOT_AUTHORIZED");
+        boolean backgroundLocation = GeofenceStore.getBackgroundLocation(getContext());
+        if (!hasGeofencePermissions(backgroundLocation)) {
+            call.reject(geofencePermissionMessage(backgroundLocation), "NOT_AUTHORIZED");
             return;
         }
         if (!isLocationEnabled(getContext())) {
@@ -322,7 +331,7 @@ public class BackgroundGeolocation extends Plugin {
                 })
                 .addOnFailureListener((exception) -> call.reject("Could not start monitoring the geofence", exception));
         } catch (SecurityException exception) {
-            call.reject("Background location permission is required for geofencing", "NOT_AUTHORIZED", exception);
+            call.reject(geofencePermissionMessage(backgroundLocation), "NOT_AUTHORIZED", exception);
         }
     }
 
@@ -365,8 +374,8 @@ public class BackgroundGeolocation extends Plugin {
         call.resolve(result);
     }
 
-    private CompletableFuture<Void> requestGeofencePermissions(PluginCall call) {
-        if (hasGeofencePermissions()) {
+    private CompletableFuture<Void> requestGeofencePermissions(PluginCall call, boolean backgroundLocation) {
+        if (hasGeofencePermissions(backgroundLocation)) {
             return CompletableFuture.completedFuture(null);
         }
         if (geofencePermissionFuture != null) {
@@ -378,7 +387,7 @@ public class BackgroundGeolocation extends Plugin {
             requestPermissionForAlias("location", call, "geofenceLocationPermissionsCallback");
             return future;
         }
-        requestBackgroundLocationPermissionIfNeeded(call);
+        requestBackgroundLocationPermissionIfNeeded(call, backgroundLocation);
         return future;
     }
 
@@ -392,7 +401,7 @@ public class BackgroundGeolocation extends Plugin {
             geofencePermissionFuture = null;
             return;
         }
-        requestBackgroundLocationPermissionIfNeeded(call);
+        requestBackgroundLocationPermissionIfNeeded(call, GeofenceStore.getBackgroundLocation(getContext()));
     }
 
     @PermissionCallback
@@ -409,8 +418,8 @@ public class BackgroundGeolocation extends Plugin {
         geofencePermissionFuture = null;
     }
 
-    private void requestBackgroundLocationPermissionIfNeeded(PluginCall call) {
-        if (hasBackgroundLocationPermission()) {
+    private void requestBackgroundLocationPermissionIfNeeded(PluginCall call, boolean backgroundLocation) {
+        if (!backgroundLocation || hasBackgroundLocationPermission()) {
             geofencePermissionFuture.complete(null);
             geofencePermissionFuture = null;
             return;
@@ -418,8 +427,8 @@ public class BackgroundGeolocation extends Plugin {
         requestPermissionForAlias("backgroundLocation", call, "geofenceBackgroundPermissionsCallback");
     }
 
-    private boolean hasGeofencePermissions() {
-        return getPermissionState("location") == PermissionState.GRANTED && hasBackgroundLocationPermission();
+    private boolean hasGeofencePermissions(boolean backgroundLocation) {
+        return getPermissionState("location") == PermissionState.GRANTED && (!backgroundLocation || hasBackgroundLocationPermission());
     }
 
     private boolean hasBackgroundLocationPermission() {
@@ -432,6 +441,13 @@ public class BackgroundGeolocation extends Plugin {
         );
     }
 
+    private String geofencePermissionMessage(boolean backgroundLocation) {
+        if (backgroundLocation) {
+            return "Background location permission is required for geofencing";
+        }
+        return "Location permission is required for geofencing";
+    }
+
     private GeofencingClient getGeofencingClient() {
         return LocationServices.getGeofencingClient(getContext());
     }

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

@@ -34,6 +34,9 @@ public class GeofenceBootReceiver extends BroadcastReceiver {
 
     private static List<Task<Void>> restorePersistedGeofences(Context context) {
         List<Task<Void>> tasks = new ArrayList<>();
+        if (!GeofenceStore.getBackgroundLocation(context)) {
+            return tasks;
+        }
         var client = LocationServices.getGeofencingClient(context);
         for (String identifier : GeofenceStore.getRegionIds(context)) {
             JSONObject region = GeofenceStore.getRegion(context, identifier);

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

@@ -33,13 +33,21 @@ final class GeofenceStore {
     private static final String KEY_URL = "url";
     private static final String KEY_NOTIFY_ON_ENTRY = "notifyOnEntry";
     private static final String KEY_NOTIFY_ON_EXIT = "notifyOnExit";
+    private static final String KEY_BACKGROUND_LOCATION = "backgroundLocation";
     private static final String KEY_PAYLOAD = "payload";
     private static final String KEY_REGION_IDS = "regionIds";
     private static final String KEY_REGION_PREFIX = "region.";
 
     private GeofenceStore() {}
 
-    static void saveSetup(Context context, String url, boolean notifyOnEntry, boolean notifyOnExit, JSONObject payload) {
+    static void saveSetup(
+        Context context,
+        String url,
+        boolean notifyOnEntry,
+        boolean notifyOnExit,
+        JSONObject payload,
+        boolean backgroundLocation
+    ) {
         SharedPreferences.Editor editor = prefs(context).edit();
         if (url == null || url.isEmpty()) {
             editor.remove(KEY_URL);
@@ -48,6 +56,7 @@ final class GeofenceStore {
         }
         editor.putBoolean(KEY_NOTIFY_ON_ENTRY, notifyOnEntry);
         editor.putBoolean(KEY_NOTIFY_ON_EXIT, notifyOnExit);
+        editor.putBoolean(KEY_BACKGROUND_LOCATION, backgroundLocation);
         editor.putString(KEY_PAYLOAD, payload == null ? new JSONObject().toString() : payload.toString());
         editor.apply();
     }
@@ -64,6 +73,10 @@ final class GeofenceStore {
         return prefs(context).getBoolean(KEY_NOTIFY_ON_EXIT, true);
     }
 
+    static boolean getBackgroundLocation(Context context) {
+        return prefs(context).getBoolean(KEY_BACKGROUND_LOCATION, false);
+    }
+
     static void saveRegion(
         Context context,
         String identifier,
@@ -170,6 +183,9 @@ final class GeofenceStore {
     }
 
     static void enqueueTransition(Context context, JSONObject data) {
+        if (!getBackgroundLocation(context)) {
+            return;
+        }
         if (getUrl(context) == null || getUrl(context).isEmpty()) {
             return;
         }

package/dist/docs.json

@@ -163,10 +163,10 @@
           },
           {
             "name": "example",
-            "text": "await BackgroundGeolocation.setupGeofencing({\n  url: \"https://api.example.com/geofences\",\n  notifyOnEntry: true,\n  notifyOnExit: true,\n  payload: { userId: \"123\" }\n});"
+            "text": "await BackgroundGeolocation.setupGeofencing({\n  notifyOnEntry: true,\n  notifyOnExit: true,\n  payload: { userId: \"123\" }\n});"
           }
         ],
-        "docs": "Configures native geofence transition handling.\n\nCall this before adding geofences when you need native background POSTs\nor default entry/exit settings.",
+        "docs": "Configures native geofence transition handling.\n\nCall this before adding geofences when you need default entry/exit settings\nor native background POSTs. Android background POSTs require\n`backgroundLocation: true`.",
         "complexTypes": [
           "GeofenceSetupOptions"
         ],
@@ -741,7 +741,7 @@
     {
       "name": "GeofenceSetupOptions",
       "slug": "geofencesetupoptions",
-      "docs": "Options for configuring native geofence transition handling.\n\nWhen `url` is provided, native iOS and Android code sends a JSON `POST`\nwhenever a monitored region is entered or exited. This keeps geofence\nhandling useful when the WebView is suspended.",
+      "docs": "Options for configuring native geofence transition handling.\n\nWhen `url` is provided, native code can send a JSON `POST` whenever a\nmonitored region is entered or exited. Android background POST delivery\nrequires `backgroundLocation: true`.",
       "tags": [
         {
           "text": "8.0.30",
@@ -762,7 +762,7 @@
               "name": "example"
             }
           ],
-          "docs": "Endpoint that receives geofence transition payloads.",
+          "docs": "Endpoint that receives geofence transition payloads.\n\nOn Android, native background POST delivery requires `backgroundLocation: true`.",
           "complexTypes": [],
           "type": "string | undefined"
         },
@@ -840,7 +840,27 @@
               "name": "example"
             }
           ],
-          "docs": "Whether the plugin should request the native location permission needed for geofencing.\n\niOS geofencing needs Always location authorization. Android background geofencing\nneeds foreground location and, on Android 10+, background location permission.",
+          "docs": "Whether the plugin should request the native location permission needed for geofencing.\n\niOS geofencing needs Always location authorization. Android geofencing requests\nforeground location by default. Android background location is only requested when\n`backgroundLocation` is enabled.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
+        {
+          "name": "backgroundLocation",
+          "tags": [
+            {
+              "text": "8.0.34",
+              "name": "since"
+            },
+            {
+              "text": "false",
+              "name": "default"
+            },
+            {
+              "text": "false",
+              "name": "example"
+            }
+          ],
+          "docs": "Whether Android geofencing should opt into background location permission.\n\nThe plugin does not add `ACCESS_BACKGROUND_LOCATION` to your app manifest.\nLeave this disabled if your app does not have Google Play approval for Android\nbackground location. Enable it only after adding `ACCESS_BACKGROUND_LOCATION`\nto your app manifest and when you need Android geofence transitions while the\napp is in the background.\n\nThis option only affects Android. Android versions below 10 do not request\nan extra background-location runtime permission, but the option still gates\nnative Android background geofence delivery.",
           "complexTypes": [],
           "type": "boolean | undefined"
         }

package/dist/esm/definitions.d.ts

@@ -194,9 +194,9 @@ export interface SetPlannedRouteOptions {
 /**
  * Options for configuring native geofence transition handling.
  *
- * When `url` is provided, native iOS and Android code sends a JSON `POST`
- * whenever a monitored region is entered or exited. This keeps geofence
- * handling useful when the WebView is suspended.
+ * When `url` is provided, native code can send a JSON `POST` whenever a
+ * monitored region is entered or exited. Android background POST delivery
+ * requires `backgroundLocation: true`.
  *
  * @since 8.0.30
  */
@@ -204,6 +204,8 @@ export interface GeofenceSetupOptions {
     /**
      * Endpoint that receives geofence transition payloads.
      *
+     * On Android, native background POST delivery requires `backgroundLocation: true`.
+     *
      * @since 8.0.30
      * @example "https://api.example.com/geofences"
      */
@@ -234,14 +236,33 @@ export interface GeofenceSetupOptions {
     /**
      * Whether the plugin should request the native location permission needed for geofencing.
      *
-     * iOS geofencing needs Always location authorization. Android background geofencing
-     * needs foreground location and, on Android 10+, background location permission.
+     * iOS geofencing needs Always location authorization. Android geofencing requests
+     * foreground location by default. Android background location is only requested when
+     * `backgroundLocation` is enabled.
      *
      * @since 8.0.30
      * @default true
      * @example true
      */
     requestPermissions?: boolean;
+    /**
+     * Whether Android geofencing should opt into background location permission.
+     *
+     * The plugin does not add `ACCESS_BACKGROUND_LOCATION` to your app manifest.
+     * Leave this disabled if your app does not have Google Play approval for Android
+     * background location. Enable it only after adding `ACCESS_BACKGROUND_LOCATION`
+     * to your app manifest and when you need Android geofence transitions while the
+     * app is in the background.
+     *
+     * This option only affects Android. Android versions below 10 do not request
+     * an extra background-location runtime permission, but the option still gates
+     * native Android background geofence delivery.
+     *
+     * @since 8.0.34
+     * @default false
+     * @example false
+     */
+    backgroundLocation?: boolean;
 }
 /**
  * A circular geofence region.
@@ -494,8 +515,9 @@ export interface BackgroundGeolocationPlugin {
     /**
      * Configures native geofence transition handling.
      *
-     * Call this before adding geofences when you need native background POSTs
-     * or default entry/exit settings.
+     * Call this before adding geofences when you need default entry/exit settings
+     * or native background POSTs. Android background POSTs require
+     * `backgroundLocation: true`.
      *
      * @param options The geofence configuration options
      * @returns A promise that resolves once geofencing is configured
@@ -503,7 +525,6 @@ export interface BackgroundGeolocationPlugin {
      * @since 8.0.30
      * @example
      * await BackgroundGeolocation.setupGeofencing({
-     *   url: "https://api.example.com/geofences",
      *   notifyOnEntry: true,
      *   notifyOnExit: true,
      *   payload: { userId: "123" }

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\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 * Options for configuring native geofence transition handling.\n *\n * When `url` is provided, native iOS and Android code sends a JSON `POST`\n * whenever a monitored region is entered or exited. This keeps geofence\n * handling useful when the WebView is suspended.\n *\n * @since 8.0.30\n */\nexport interface GeofenceSetupOptions {\n  /**\n   * Endpoint that receives geofence transition payloads.\n   *\n   * @since 8.0.30\n   * @example \"https://api.example.com/geofences\"\n   */\n  url?: string;\n\n  /**\n   * Whether entry transitions should be monitored.\n   *\n   * @since 8.0.30\n   * @default true\n   * @example true\n   */\n  notifyOnEntry?: boolean;\n\n  /**\n   * Whether exit transitions should be monitored.\n   *\n   * @since 8.0.30\n   * @default true\n   * @example true\n   */\n  notifyOnExit?: boolean;\n\n  /**\n   * Base JSON payload merged into every native transition POST and listener event.\n   *\n   * @since 8.0.30\n   * @example { \"userId\": \"123\" }\n   */\n  payload?: Record<string, unknown>;\n\n  /**\n   * Whether the plugin should request the native location permission needed for geofencing.\n   *\n   * iOS geofencing needs Always location authorization. Android background geofencing\n   * needs foreground location and, on Android 10+, background location permission.\n   *\n   * @since 8.0.30\n   * @default true\n   * @example true\n   */\n  requestPermissions?: boolean;\n}\n\n/**\n * A circular geofence region.\n *\n * @since 8.0.30\n */\nexport interface AddGeofenceOptions {\n  /**\n   * Latitude in degrees for the region center.\n   *\n   * @since 8.0.30\n   * @example 40.7128\n   */\n  latitude: number;\n\n  /**\n   * Longitude in degrees for the region center.\n   *\n   * @since 8.0.30\n   * @example -74.006\n   */\n  longitude: number;\n\n  /**\n   * Region radius in meters.\n   *\n   * @since 8.0.30\n   * @default 50\n   * @example 150\n   */\n  radius?: number;\n\n  /**\n   * Stable identifier for the geofence.\n   *\n   * @since 8.0.30\n   * @example \"office\"\n   */\n  identifier: string;\n\n  /**\n   * Overrides the setup-level entry setting for this region.\n   *\n   * @since 8.0.30\n   */\n  notifyOnEntry?: boolean;\n\n  /**\n   * Overrides the setup-level exit setting for this region.\n   *\n   * @since 8.0.30\n   */\n  notifyOnExit?: boolean;\n\n  /**\n   * Region-specific payload merged over the setup payload.\n   *\n   * @since 8.0.30\n   * @example { \"storeId\": \"nyc-1\" }\n   */\n  payload?: Record<string, unknown>;\n}\n\n/**\n * Options for removing a monitored geofence.\n *\n * @since 8.0.30\n */\nexport interface RemoveGeofenceOptions {\n  /**\n   * Identifier passed to `addGeofence`.\n   *\n   * @since 8.0.30\n   * @example \"office\"\n   */\n  identifier: string;\n}\n\n/**\n * Result returned when listing monitored geofences.\n *\n * @since 8.0.30\n */\nexport interface MonitoredGeofencesResult {\n  /**\n   * Identifiers for all geofences currently monitored by this plugin.\n   *\n   * @since 8.0.30\n   * @example [\"office\", \"warehouse\"]\n   */\n  regions: string[];\n}\n\n/**\n * Event emitted when a monitored geofence is entered or exited.\n *\n * The same data is also sent to the configured `url`, when one is set.\n *\n * @since 8.0.30\n */\nexport interface GeofenceTransitionEvent {\n  /**\n   * Identifier of the geofence that changed state.\n   *\n   * @since 8.0.30\n   * @example \"office\"\n   */\n  identifier: string;\n\n  /**\n   * Transition name.\n   *\n   * @since 8.0.30\n   * @example \"enter\"\n   */\n  transition: 'enter' | 'exit';\n\n  /**\n   * `true` for entry transitions, `false` for exit transitions.\n   *\n   * @since 8.0.30\n   * @example true\n   */\n  enter: boolean;\n\n  /**\n   * Latitude in degrees for the monitored region center, when available.\n   *\n   * @since 8.0.30\n   * @example 40.7128\n   */\n  latitude?: number;\n\n  /**\n   * Longitude in degrees for the monitored region center, when available.\n   *\n   * @since 8.0.30\n   * @example -74.006\n   */\n  longitude?: number;\n\n  /**\n   * Region radius in meters, when available.\n   *\n   * @since 8.0.30\n   * @example 150\n   */\n  radius?: number;\n\n  /**\n   * Merged setup and region payload.\n   *\n   * @since 8.0.30\n   */\n  payload?: Record<string, unknown>;\n}\n\n/**\n * Event emitted when native geofence monitoring fails.\n *\n * @since 8.0.30\n */\nexport interface GeofenceErrorEvent {\n  /**\n   * Identifier of the geofence that failed, when native APIs provide it.\n   *\n   * @since 8.0.30\n   * @example \"office\"\n   */\n  identifier?: string;\n\n  /**\n   * Native platform error code.\n   *\n   * @since 8.0.30\n   * @example 5\n   */\n  code?: number;\n\n  /**\n   * Native platform error message.\n   *\n   * @since 8.0.30\n   */\n  message: string;\n\n  /**\n   * Native error domain, when available.\n   *\n   * @since 8.0.30\n   */\n  domain?: 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(options: StartOptions, callback: (position?: Location, error?: CallbackError) => void): 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  /**\n   * Configures native geofence transition handling.\n   *\n   * Call this before adding geofences when you need native background POSTs\n   * or default entry/exit settings.\n   *\n   * @param options The geofence configuration options\n   * @returns A promise that resolves once geofencing is configured\n   *\n   * @since 8.0.30\n   * @example\n   * await BackgroundGeolocation.setupGeofencing({\n   *   url: \"https://api.example.com/geofences\",\n   *   notifyOnEntry: true,\n   *   notifyOnExit: true,\n   *   payload: { userId: \"123\" }\n   * });\n   */\n  setupGeofencing(options: GeofenceSetupOptions): Promise<void>;\n\n  /**\n   * Starts monitoring a circular native geofence.\n   *\n   * @param options The geofence region options\n   * @returns A promise that resolves when native monitoring starts\n   *\n   * @since 8.0.30\n   * @example\n   * await BackgroundGeolocation.addGeofence({\n   *   identifier: \"office\",\n   *   latitude: 40.7128,\n   *   longitude: -74.006,\n   *   radius: 150\n   * });\n   */\n  addGeofence(options: AddGeofenceOptions): Promise<void>;\n\n  /**\n   * Stops monitoring one geofence.\n   *\n   * @param options The geofence identifier\n   * @returns A promise that resolves when native monitoring stops\n   *\n   * @since 8.0.30\n   * @example\n   * await BackgroundGeolocation.removeGeofence({ identifier: \"office\" });\n   */\n  removeGeofence(options: RemoveGeofenceOptions): Promise<void>;\n\n  /**\n   * Stops monitoring every geofence registered by this plugin.\n   *\n   * @returns A promise that resolves when all native geofences are removed\n   *\n   * @since 8.0.30\n   * @example\n   * await BackgroundGeolocation.removeAllGeofences();\n   */\n  removeAllGeofences(): Promise<void>;\n\n  /**\n   * Lists the geofence identifiers currently monitored by this plugin.\n   *\n   * @returns A promise with monitored geofence identifiers\n   *\n   * @since 8.0.30\n   * @example\n   * const { regions } = await BackgroundGeolocation.getMonitoredGeofences();\n   */\n  getMonitoredGeofences(): Promise<MonitoredGeofencesResult>;\n\n  /**\n   * Listens for geofence enter/exit transitions while the WebView is alive.\n   *\n   * Native `url` delivery configured through `setupGeofencing` is used for\n   * background-safe delivery.\n   *\n   * @since 8.0.30\n   * @example\n   * const handle = await BackgroundGeolocation.addListener(\n   *   \"geofenceTransition\",\n   *   (event) => console.log(event.identifier, event.transition)\n   * );\n   */\n  addListener(\n    eventName: 'geofenceTransition',\n    listenerFunc: (event: GeofenceTransitionEvent) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Listens for native geofence monitoring errors while the WebView is alive.\n   *\n   * @since 8.0.30\n   * @example\n   * const handle = await BackgroundGeolocation.addListener(\n   *   \"geofenceError\",\n   *   (event) => console.error(event.identifier, event.message)\n   * );\n   */\n  addListener(\n    eventName: 'geofenceError',\n    listenerFunc: (event: GeofenceErrorEvent) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Get the native Capacitor plugin version\n   *\n   * @returns {Promise<{ id: string }>} an Promise with version for this device\n   * @throws An error if the something went wrong\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\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 * Options for configuring native geofence transition handling.\n *\n * When `url` is provided, native code can send a JSON `POST` whenever a\n * monitored region is entered or exited. Android background POST delivery\n * requires `backgroundLocation: true`.\n *\n * @since 8.0.30\n */\nexport interface GeofenceSetupOptions {\n  /**\n   * Endpoint that receives geofence transition payloads.\n   *\n   * On Android, native background POST delivery requires `backgroundLocation: true`.\n   *\n   * @since 8.0.30\n   * @example \"https://api.example.com/geofences\"\n   */\n  url?: string;\n\n  /**\n   * Whether entry transitions should be monitored.\n   *\n   * @since 8.0.30\n   * @default true\n   * @example true\n   */\n  notifyOnEntry?: boolean;\n\n  /**\n   * Whether exit transitions should be monitored.\n   *\n   * @since 8.0.30\n   * @default true\n   * @example true\n   */\n  notifyOnExit?: boolean;\n\n  /**\n   * Base JSON payload merged into every native transition POST and listener event.\n   *\n   * @since 8.0.30\n   * @example { \"userId\": \"123\" }\n   */\n  payload?: Record<string, unknown>;\n\n  /**\n   * Whether the plugin should request the native location permission needed for geofencing.\n   *\n   * iOS geofencing needs Always location authorization. Android geofencing requests\n   * foreground location by default. Android background location is only requested when\n   * `backgroundLocation` is enabled.\n   *\n   * @since 8.0.30\n   * @default true\n   * @example true\n   */\n  requestPermissions?: boolean;\n\n  /**\n   * Whether Android geofencing should opt into background location permission.\n   *\n   * The plugin does not add `ACCESS_BACKGROUND_LOCATION` to your app manifest.\n   * Leave this disabled if your app does not have Google Play approval for Android\n   * background location. Enable it only after adding `ACCESS_BACKGROUND_LOCATION`\n   * to your app manifest and when you need Android geofence transitions while the\n   * app is in the background.\n   *\n   * This option only affects Android. Android versions below 10 do not request\n   * an extra background-location runtime permission, but the option still gates\n   * native Android background geofence delivery.\n   *\n   * @since 8.0.34\n   * @default false\n   * @example false\n   */\n  backgroundLocation?: boolean;\n}\n\n/**\n * A circular geofence region.\n *\n * @since 8.0.30\n */\nexport interface AddGeofenceOptions {\n  /**\n   * Latitude in degrees for the region center.\n   *\n   * @since 8.0.30\n   * @example 40.7128\n   */\n  latitude: number;\n\n  /**\n   * Longitude in degrees for the region center.\n   *\n   * @since 8.0.30\n   * @example -74.006\n   */\n  longitude: number;\n\n  /**\n   * Region radius in meters.\n   *\n   * @since 8.0.30\n   * @default 50\n   * @example 150\n   */\n  radius?: number;\n\n  /**\n   * Stable identifier for the geofence.\n   *\n   * @since 8.0.30\n   * @example \"office\"\n   */\n  identifier: string;\n\n  /**\n   * Overrides the setup-level entry setting for this region.\n   *\n   * @since 8.0.30\n   */\n  notifyOnEntry?: boolean;\n\n  /**\n   * Overrides the setup-level exit setting for this region.\n   *\n   * @since 8.0.30\n   */\n  notifyOnExit?: boolean;\n\n  /**\n   * Region-specific payload merged over the setup payload.\n   *\n   * @since 8.0.30\n   * @example { \"storeId\": \"nyc-1\" }\n   */\n  payload?: Record<string, unknown>;\n}\n\n/**\n * Options for removing a monitored geofence.\n *\n * @since 8.0.30\n */\nexport interface RemoveGeofenceOptions {\n  /**\n   * Identifier passed to `addGeofence`.\n   *\n   * @since 8.0.30\n   * @example \"office\"\n   */\n  identifier: string;\n}\n\n/**\n * Result returned when listing monitored geofences.\n *\n * @since 8.0.30\n */\nexport interface MonitoredGeofencesResult {\n  /**\n   * Identifiers for all geofences currently monitored by this plugin.\n   *\n   * @since 8.0.30\n   * @example [\"office\", \"warehouse\"]\n   */\n  regions: string[];\n}\n\n/**\n * Event emitted when a monitored geofence is entered or exited.\n *\n * The same data is also sent to the configured `url`, when one is set.\n *\n * @since 8.0.30\n */\nexport interface GeofenceTransitionEvent {\n  /**\n   * Identifier of the geofence that changed state.\n   *\n   * @since 8.0.30\n   * @example \"office\"\n   */\n  identifier: string;\n\n  /**\n   * Transition name.\n   *\n   * @since 8.0.30\n   * @example \"enter\"\n   */\n  transition: 'enter' | 'exit';\n\n  /**\n   * `true` for entry transitions, `false` for exit transitions.\n   *\n   * @since 8.0.30\n   * @example true\n   */\n  enter: boolean;\n\n  /**\n   * Latitude in degrees for the monitored region center, when available.\n   *\n   * @since 8.0.30\n   * @example 40.7128\n   */\n  latitude?: number;\n\n  /**\n   * Longitude in degrees for the monitored region center, when available.\n   *\n   * @since 8.0.30\n   * @example -74.006\n   */\n  longitude?: number;\n\n  /**\n   * Region radius in meters, when available.\n   *\n   * @since 8.0.30\n   * @example 150\n   */\n  radius?: number;\n\n  /**\n   * Merged setup and region payload.\n   *\n   * @since 8.0.30\n   */\n  payload?: Record<string, unknown>;\n}\n\n/**\n * Event emitted when native geofence monitoring fails.\n *\n * @since 8.0.30\n */\nexport interface GeofenceErrorEvent {\n  /**\n   * Identifier of the geofence that failed, when native APIs provide it.\n   *\n   * @since 8.0.30\n   * @example \"office\"\n   */\n  identifier?: string;\n\n  /**\n   * Native platform error code.\n   *\n   * @since 8.0.30\n   * @example 5\n   */\n  code?: number;\n\n  /**\n   * Native platform error message.\n   *\n   * @since 8.0.30\n   */\n  message: string;\n\n  /**\n   * Native error domain, when available.\n   *\n   * @since 8.0.30\n   */\n  domain?: 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(options: StartOptions, callback: (position?: Location, error?: CallbackError) => void): 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  /**\n   * Configures native geofence transition handling.\n   *\n   * Call this before adding geofences when you need default entry/exit settings\n   * or native background POSTs. Android background POSTs require\n   * `backgroundLocation: true`.\n   *\n   * @param options The geofence configuration options\n   * @returns A promise that resolves once geofencing is configured\n   *\n   * @since 8.0.30\n   * @example\n   * await BackgroundGeolocation.setupGeofencing({\n   *   notifyOnEntry: true,\n   *   notifyOnExit: true,\n   *   payload: { userId: \"123\" }\n   * });\n   */\n  setupGeofencing(options: GeofenceSetupOptions): Promise<void>;\n\n  /**\n   * Starts monitoring a circular native geofence.\n   *\n   * @param options The geofence region options\n   * @returns A promise that resolves when native monitoring starts\n   *\n   * @since 8.0.30\n   * @example\n   * await BackgroundGeolocation.addGeofence({\n   *   identifier: \"office\",\n   *   latitude: 40.7128,\n   *   longitude: -74.006,\n   *   radius: 150\n   * });\n   */\n  addGeofence(options: AddGeofenceOptions): Promise<void>;\n\n  /**\n   * Stops monitoring one geofence.\n   *\n   * @param options The geofence identifier\n   * @returns A promise that resolves when native monitoring stops\n   *\n   * @since 8.0.30\n   * @example\n   * await BackgroundGeolocation.removeGeofence({ identifier: \"office\" });\n   */\n  removeGeofence(options: RemoveGeofenceOptions): Promise<void>;\n\n  /**\n   * Stops monitoring every geofence registered by this plugin.\n   *\n   * @returns A promise that resolves when all native geofences are removed\n   *\n   * @since 8.0.30\n   * @example\n   * await BackgroundGeolocation.removeAllGeofences();\n   */\n  removeAllGeofences(): Promise<void>;\n\n  /**\n   * Lists the geofence identifiers currently monitored by this plugin.\n   *\n   * @returns A promise with monitored geofence identifiers\n   *\n   * @since 8.0.30\n   * @example\n   * const { regions } = await BackgroundGeolocation.getMonitoredGeofences();\n   */\n  getMonitoredGeofences(): Promise<MonitoredGeofencesResult>;\n\n  /**\n   * Listens for geofence enter/exit transitions while the WebView is alive.\n   *\n   * Native `url` delivery configured through `setupGeofencing` is used for\n   * background-safe delivery.\n   *\n   * @since 8.0.30\n   * @example\n   * const handle = await BackgroundGeolocation.addListener(\n   *   \"geofenceTransition\",\n   *   (event) => console.log(event.identifier, event.transition)\n   * );\n   */\n  addListener(\n    eventName: 'geofenceTransition',\n    listenerFunc: (event: GeofenceTransitionEvent) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Listens for native geofence monitoring errors while the WebView is alive.\n   *\n   * @since 8.0.30\n   * @example\n   * const handle = await BackgroundGeolocation.addListener(\n   *   \"geofenceError\",\n   *   (event) => console.error(event.identifier, event.message)\n   * );\n   */\n  addListener(\n    eventName: 'geofenceError',\n    listenerFunc: (event: GeofenceErrorEvent) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Get the native Capacitor plugin version\n   *\n   * @returns {Promise<{ id: string }>} an Promise with version for this device\n   * @throws An error if the something went wrong\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n"]}

package/ios/Sources/CapgoBackgroundGeolocationPlugin/CapgoCapacitorBackgroundGeolocationPlugin.swift

@@ -38,7 +38,7 @@ func formatLocation(_ location: CLLocation) -> PluginCallResultData {
 @objc(BackgroundGeolocation)
 // swiftlint:disable:next type_body_length
 public class BackgroundGeolocation: CAPPlugin, CLLocationManagerDelegate, CAPBridgedPlugin {
-    private let pluginVersion: String = "8.0.33"
+    private let pluginVersion: String = "8.0.35"
     public let identifier = "BackgroundGeolocationPlugin"
     public let jsName = "BackgroundGeolocation"
     public let pluginMethods: [CAPPluginMethod] = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/background-geolocation",
-  "version": "8.0.33",
+  "version": "8.0.35",
   "description": "Accurate background geolocation and native geofencing for Capacitor apps on iOS and Android.",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",