@capgo/background-geolocation 8.0.31 → 8.0.33

package/README.md

@@ -6,8 +6,16 @@
   <h2><a href="https://capgo.app/consulting/?ref=plugin_background_geolocation"> Missing a feature? We’ll build the plugin for you 💪</a></h2>
 </div>
 
-A Capacitor plugin that lets you receive accurate geolocation updates even while the app is backgrounded.
-It has a web API to facilitate for a similar usage, but background geolocation is not supported in a regular browser, only in an app environment.
+A Capacitor plugin for accurate background location tracking and native geofencing on iOS and Android.
+Use it to stream precise location updates, monitor circular geofence regions, react to enter/exit events in JavaScript, and POST geofence transitions natively while the WebView is suspended.
+
+## Features
+
+- Accurate foreground and background geolocation without a paid license.
+- Native geofencing on iOS and Android for circular regions.
+- Enter and exit events through `geofenceTransition` while the app is alive.
+- Native webhook delivery for geofence transitions when the WebView is suspended.
+- A web fallback for development and browser-based testing.
 
 ## This plugin's history
 
@@ -32,16 +40,17 @@ I hope you'll enjoy it!
 
 A short comparison between the three main background-geolocation plugins commonly used in Capacitor apps.
 
-| Plugin | Accuracy | Background | HTTP Upload | Pricing |
-|--------|----------|------------|-------------|---------|
-| `@capacitor-community/background-geolocation` (Community) | Not accurate | Yes | No | Free |
-| `@capgo/background-geolocation` (this plugin) | Accurate | Yes | No | Free |
-| Transistorsoft (original) | Accurate | Yes | Yes — built-in HTTP uploader to your API | Paid |
+| Plugin | Accuracy | Background | Geofencing | Native transition POST | Pricing |
+|--------|----------|------------|------------|------------------------|---------|
+| `@capacitor-community/background-geolocation` (Community) | Not accurate | Yes | No | No | Free |
+| `@capgo/background-geolocation` (this plugin) | Accurate | Yes | iOS and Android | Yes, for geofence transitions | Free |
+| Transistorsoft (original) | Accurate | Yes | Yes | Yes, built-in HTTP uploader | Paid |
 
 Notes:
 - The Community plugin is lightweight and continues to work in the background, but it is known to be less accurate than the options below.
-- This Cap-go plugin aims to provide accurate location fixes and reliable background operation without requiring a paid license.
-- Transistorsoft's plugin is a mature, accurate solution that also includes an HTTP uploader (it can send location updates to your API). It is a commercial product and requires a paid license for full use.
+- This Cap-go plugin aims to provide accurate location fixes, reliable background operation, and native geofence enter/exit handling without requiring a paid license.
+- Native geofence POST delivery is useful when iOS or Android wakes native code for a region transition but the Capacitor WebView is not running.
+- Transistorsoft's plugin is a mature, accurate solution that also includes a broader HTTP uploader. It is a commercial product and requires a paid license for full use.
 
 
 ## Usage
@@ -84,7 +93,51 @@ BackgroundGeolocation.start(
 // 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 });
+```
+
+## 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.
+
+```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.
+await BackgroundGeolocation.setupGeofencing({
+    url: "https://api.example.com/geofences",
+    notifyOnEntry: true,
+    notifyOnExit: true,
+    payload: { userId: "123" }
+});
+
+await BackgroundGeolocation.addGeofence({
+    identifier: "office",
+    latitude: 37.33182,
+    longitude: -122.03118,
+    radius: 150
+});
+
+const handle = await BackgroundGeolocation.addListener(
+    "geofenceTransition",
+    (event) => console.log(event.identifier, event.transition)
+);
+
+await BackgroundGeolocation.removeGeofence({ identifier: "office" });
+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:
 
+```xml
+<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
+```
+
+Apps that only use foreground location can omit this permission.
+
+```javascript
 // 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) {
@@ -123,15 +176,15 @@ The most complete doc is available here: https://capgo.app/docs/plugins/backgrou
 
 ## Installation
 
-This plugin supports Capacitor v7:
+This plugin supports Capacitor v8:
 
 | Capacitor  | Plugin |
 |------------|--------|
-| v7         | v7     |
+| v8         | v8     |
 
 ```sh
-npm install @capgo/background-geolocation
-npx cap update
+bun add @capgo/background-geolocation
+bunx cap update
 ```
 
 ### iOS
@@ -158,6 +211,8 @@ 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.
+
 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.
 
 Configuration specific to Android can be made in `strings.xml`:
@@ -212,8 +267,16 @@ Configuration specific to Android can be made in `strings.xml`:
 * [`stop()`](#stop)
 * [`openSettings()`](#opensettings)
 * [`setPlannedRoute(...)`](#setplannedroute)
+* [`setupGeofencing(...)`](#setupgeofencing)
+* [`addGeofence(...)`](#addgeofence)
+* [`removeGeofence(...)`](#removegeofence)
+* [`removeAllGeofences()`](#removeallgeofences)
+* [`getMonitoredGeofences()`](#getmonitoredgeofences)
+* [`addListener('geofenceTransition', ...)`](#addlistenergeofencetransition-)
+* [`addListener('geofenceError', ...)`](#addlistenergeofenceerror-)
 * [`getPluginVersion()`](#getpluginversion)
 * [Interfaces](#interfaces)
+* [Type Aliases](#type-aliases)
 
 </docgen-index>
 
@@ -288,6 +351,131 @@ This should be used to play a sound (in the background too, only for native).
 --------------------
 
 
+### setupGeofencing(...)
+
+```typescript
+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.
+
+| Param         | Type                                                                  | Description                        |
+| ------------- | --------------------------------------------------------------------- | ---------------------------------- |
+| **`options`** | <code><a href="#geofencesetupoptions">GeofenceSetupOptions</a></code> | The geofence configuration options |
+
+**Since:** 8.0.30
+
+--------------------
+
+
+### addGeofence(...)
+
+```typescript
+addGeofence(options: AddGeofenceOptions) => Promise<void>
+```
+
+Starts monitoring a circular native geofence.
+
+| Param         | Type                                                              | Description                 |
+| ------------- | ----------------------------------------------------------------- | --------------------------- |
+| **`options`** | <code><a href="#addgeofenceoptions">AddGeofenceOptions</a></code> | The geofence region options |
+
+**Since:** 8.0.30
+
+--------------------
+
+
+### removeGeofence(...)
+
+```typescript
+removeGeofence(options: RemoveGeofenceOptions) => Promise<void>
+```
+
+Stops monitoring one geofence.
+
+| Param         | Type                                                                    | Description             |
+| ------------- | ----------------------------------------------------------------------- | ----------------------- |
+| **`options`** | <code><a href="#removegeofenceoptions">RemoveGeofenceOptions</a></code> | The geofence identifier |
+
+**Since:** 8.0.30
+
+--------------------
+
+
+### removeAllGeofences()
+
+```typescript
+removeAllGeofences() => Promise<void>
+```
+
+Stops monitoring every geofence registered by this plugin.
+
+**Since:** 8.0.30
+
+--------------------
+
+
+### getMonitoredGeofences()
+
+```typescript
+getMonitoredGeofences() => Promise<MonitoredGeofencesResult>
+```
+
+Lists the geofence identifiers currently monitored by this plugin.
+
+**Returns:** <code>Promise&lt;<a href="#monitoredgeofencesresult">MonitoredGeofencesResult</a>&gt;</code>
+
+**Since:** 8.0.30
+
+--------------------
+
+
+### addListener('geofenceTransition', ...)
+
+```typescript
+addListener(eventName: 'geofenceTransition', listenerFunc: (event: GeofenceTransitionEvent) => void) => Promise<PluginListenerHandle>
+```
+
+Listens for geofence enter/exit transitions while the WebView is alive.
+
+Native `url` delivery configured through `setupGeofencing` is used for
+background-safe delivery.
+
+| Param              | Type                                                                                            |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'geofenceTransition'</code>                                                               |
+| **`listenerFunc`** | <code>(event: <a href="#geofencetransitionevent">GeofenceTransitionEvent</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+**Since:** 8.0.30
+
+--------------------
+
+
+### addListener('geofenceError', ...)
+
+```typescript
+addListener(eventName: 'geofenceError', listenerFunc: (event: GeofenceErrorEvent) => void) => Promise<PluginListenerHandle>
+```
+
+Listens for native geofence monitoring errors while the WebView is alive.
+
+| Param              | Type                                                                                  |
+| ------------------ | ------------------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'geofenceError'</code>                                                          |
+| **`listenerFunc`** | <code>(event: <a href="#geofenceerrorevent">GeofenceErrorEvent</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+**Since:** 8.0.30
+
+--------------------
+
+
 ### getPluginVersion()
 
 ```typescript
@@ -353,4 +541,100 @@ Extends the standard Error with optional error codes.
 | **`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 |
 
+
+#### GeofenceSetupOptions
+
+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 |
+
+
+#### AddGeofenceOptions
+
+A circular geofence region.
+
+| Prop                | Type                                                             | Description                                              | Default         | Since  |
+| ------------------- | ---------------------------------------------------------------- | -------------------------------------------------------- | --------------- | ------ |
+| **`latitude`**      | <code>number</code>                                              | Latitude in degrees for the region center.               |                 | 8.0.30 |
+| **`longitude`**     | <code>number</code>                                              | Longitude in degrees for the region center.              |                 | 8.0.30 |
+| **`radius`**        | <code>number</code>                                              | Region radius in meters.                                 | <code>50</code> | 8.0.30 |
+| **`identifier`**    | <code>string</code>                                              | Stable identifier for the geofence.                      |                 | 8.0.30 |
+| **`notifyOnEntry`** | <code>boolean</code>                                             | Overrides the setup-level entry setting for this region. |                 | 8.0.30 |
+| **`notifyOnExit`**  | <code>boolean</code>                                             | Overrides the setup-level exit setting for this region.  |                 | 8.0.30 |
+| **`payload`**       | <code><a href="#record">Record</a>&lt;string, unknown&gt;</code> | Region-specific payload merged over the setup payload.   |                 | 8.0.30 |
+
+
+#### RemoveGeofenceOptions
+
+Options for removing a monitored geofence.
+
+| Prop             | Type                | Description                         | Since  |
+| ---------------- | ------------------- | ----------------------------------- | ------ |
+| **`identifier`** | <code>string</code> | Identifier passed to `addGeofence`. | 8.0.30 |
+
+
+#### MonitoredGeofencesResult
+
+Result returned when listing monitored geofences.
+
+| Prop          | Type                  | Description                                                       | Since  |
+| ------------- | --------------------- | ----------------------------------------------------------------- | ------ |
+| **`regions`** | <code>string[]</code> | Identifiers for all geofences currently monitored by this plugin. | 8.0.30 |
+
+
+#### PluginListenerHandle
+
+| Prop         | Type                                      |
+| ------------ | ----------------------------------------- |
+| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |
+
+
+#### GeofenceTransitionEvent
+
+Event emitted when a monitored geofence is entered or exited.
+
+The same data is also sent to the configured `url`, when one is set.
+
+| Prop             | Type                                                             | Description                                                           | Since  |
+| ---------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------- | ------ |
+| **`identifier`** | <code>string</code>                                              | Identifier of the geofence that changed state.                        | 8.0.30 |
+| **`transition`** | <code>'enter' \| 'exit'</code>                                   | Transition name.                                                      | 8.0.30 |
+| **`enter`**      | <code>boolean</code>                                             | `true` for entry transitions, `false` for exit transitions.           | 8.0.30 |
+| **`latitude`**   | <code>number</code>                                              | Latitude in degrees for the monitored region center, when available.  | 8.0.30 |
+| **`longitude`**  | <code>number</code>                                              | Longitude in degrees for the monitored region center, when available. | 8.0.30 |
+| **`radius`**     | <code>number</code>                                              | Region radius in meters, when available.                              | 8.0.30 |
+| **`payload`**    | <code><a href="#record">Record</a>&lt;string, unknown&gt;</code> | Merged setup and region payload.                                      | 8.0.30 |
+
+
+#### GeofenceErrorEvent
+
+Event emitted when native geofence monitoring fails.
+
+| Prop             | Type                | Description                                                          | Since  |
+| ---------------- | ------------------- | -------------------------------------------------------------------- | ------ |
+| **`identifier`** | <code>string</code> | Identifier of the geofence that failed, when native APIs provide it. | 8.0.30 |
+| **`code`**       | <code>number</code> | Native platform error code.                                          | 8.0.30 |
+| **`message`**    | <code>string</code> | Native platform error message.                                       | 8.0.30 |
+| **`domain`**     | <code>string</code> | Native error domain, when available.                                 | 8.0.30 |
+
+
+### Type Aliases
+
+
+#### Record
+
+Construct a type with a set of properties K of type T
+
+<code>{
 [P in K]: T;
 }</code>
+
 </docgen-api>

package/android/build.gradle

@@ -4,6 +4,7 @@ ext {
     androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
     androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
     androidxLocalbroadcastmanagerVersion = project.hasProperty('androidxLocalbroadcastmanagerVersion') ? rootProject.ext.androidxLocalbroadcastmanagerVersion : '1.0.0'
+    androidxWorkRuntimeVersion = project.hasProperty('androidxWorkRuntimeVersion') ? rootProject.ext.androidxWorkRuntimeVersion : '2.11.2'
     playServicesLocationVersion = project.hasProperty('playServicesLocationVersion') ? rootProject.ext.playServicesLocationVersion : '21.3.0'
 }
 
@@ -55,6 +56,7 @@ dependencies {
     implementation project(':capacitor-android')
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
     implementation "androidx.localbroadcastmanager:localbroadcastmanager:$androidxLocalbroadcastmanagerVersion"
+    implementation "androidx.work:work-runtime:$androidxWorkRuntimeVersion"
     testImplementation "junit:junit:$junitVersion"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"

package/android/src/main/AndroidManifest.xml

@@ -5,6 +5,21 @@
             android:enabled="true"
             android:exported="true"
             android:foregroundServiceType="location" />
+
+        <receiver
+            android:name="com.capgo.capacitor_background_geolocation.GeofenceBroadcastReceiver"
+            android:enabled="true"
+            android:exported="false" />
+
+        <receiver
+            android:name="com.capgo.capacitor_background_geolocation.GeofenceBootReceiver"
+            android:enabled="true"
+            android:exported="false">
+            <intent-filter>
+                <action android:name="android.intent.action.BOOT_COMPLETED" />
+                <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
+            </intent-filter>
+        </receiver>
     </application>
 
     <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
@@ -18,6 +33,8 @@
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
     <!-- See https://github.com/Cap-go/capacitor-background-geolocation/issues/12 for more details-->
     <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+    <uses-permission android:name="android.permission.INTERNET" />
     <uses-feature android:name="android.hardware.location.gps" />
 </manifest>