@capgo/capacitor-ibeacon 8.1.1 → 8.1.3

package/README.md

@@ -194,6 +194,34 @@ Enable ARMA filtering for distance calculations (Android only).
 await CapacitorIbeacon.enableARMAFilter({ enabled: true });
 ```
 
+### Android background scanning
+
+Android 8+ requires a foreground service to keep Bluetooth scanning alive in the background. You can opt in once and the plugin will automatically
+toggle background scanning when the app moves between foreground and background.
+
+```typescript
+// Enable background scanning globally (Android only)
+await CapacitorIbeacon.enableBackgroundMode({ enabled: true });
+
+// Or opt in per call
+await CapacitorIbeacon.startMonitoringForRegion({
+  identifier: 'MyBeaconRegion',
+  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
+  enableBackgroundMode: true,
+});
+```
+
+You can also enable it via Capacitor config:
+
+```typescript
+// capacitor.config.ts
+plugins: {
+  CapacitorIbeacon: {
+    enableBackgroundMode: true,
+  },
+}
+```
+
 ## Events
 
 Listen to beacon events using Capacitor's event system:

package/android/src/main/java/ee/forgr/plugin/capacitor_ibeacon/CapacitorIbeaconPlugin.java

@@ -43,11 +43,16 @@ import org.altbeacon.beacon.Region;
 )
 public class CapacitorIbeaconPlugin extends Plugin implements BeaconConsumer {
 
-    private final String pluginVersion = "8.1.1";
+    private final String pluginVersion = "8.1.3";
+    private static final String FOREGROUND_CHANNEL_ID = "beacon_service_channel";
+    private static final int FOREGROUND_NOTIFICATION_ID = 456;
     private BeaconManager beaconManager;
     private Map<String, Region> monitoredRegions = new HashMap<>();
     private Map<String, Region> rangedRegions = new HashMap<>();
     private boolean beaconManagerBound = false;
+    private boolean backgroundModeEnabled = false;
+    private boolean foregroundServiceEnabled = false;
+    private boolean isInBackground = false;
 
     @Override
     public void load() {
@@ -102,10 +107,16 @@ public class CapacitorIbeaconPlugin extends Plugin implements BeaconConsumer {
                 }
             }
         );
+
+        Boolean configBackgroundMode = getConfig().getBoolean("enableBackgroundMode", false);
+        if (configBackgroundMode != null && configBackgroundMode) {
+            backgroundModeEnabled = true;
+        }
     }
 
     @Override
     protected void handleOnDestroy() {
+        applyBackgroundMode(false);
         if (beaconManager != null && beaconManagerBound) {
             beaconManager.unbind(this);
             beaconManagerBound = false;
@@ -113,6 +124,20 @@ public class CapacitorIbeaconPlugin extends Plugin implements BeaconConsumer {
         super.handleOnDestroy();
     }
 
+    @Override
+    protected void handleOnPause() {
+        super.handleOnPause();
+        isInBackground = true;
+        applyBackgroundMode(backgroundModeEnabled);
+    }
+
+    @Override
+    protected void handleOnResume() {
+        super.handleOnResume();
+        isInBackground = false;
+        applyBackgroundMode(backgroundModeEnabled);
+    }
+
     @Override
     public void onBeaconServiceConnect() {
         beaconManagerBound = true;
@@ -139,6 +164,7 @@ public class CapacitorIbeaconPlugin extends Plugin implements BeaconConsumer {
         String uuid = call.getString("uuid");
         Integer major = call.getInt("major");
         Integer minor = call.getInt("minor");
+        Boolean enableBackgroundMode = call.getBoolean("enableBackgroundMode");
 
         if (identifier == null || uuid == null) {
             call.reject("Missing required parameters");
@@ -146,6 +172,9 @@ public class CapacitorIbeaconPlugin extends Plugin implements BeaconConsumer {
         }
 
         try {
+            if (enableBackgroundMode != null) {
+                setBackgroundModeEnabled(enableBackgroundMode);
+            }
             Region region = createRegion(identifier, uuid, major, minor);
             monitoredRegions.put(identifier, region);
             beaconManager.startMonitoring(region);
@@ -183,6 +212,7 @@ public class CapacitorIbeaconPlugin extends Plugin implements BeaconConsumer {
         String uuid = call.getString("uuid");
         Integer major = call.getInt("major");
         Integer minor = call.getInt("minor");
+        Boolean enableBackgroundMode = call.getBoolean("enableBackgroundMode");
 
         if (identifier == null || uuid == null) {
             call.reject("Missing required parameters");
@@ -190,6 +220,9 @@ public class CapacitorIbeaconPlugin extends Plugin implements BeaconConsumer {
         }
 
         try {
+            if (enableBackgroundMode != null) {
+                setBackgroundModeEnabled(enableBackgroundMode);
+            }
             Region region = createRegion(identifier, uuid, major, minor);
             rangedRegions.put(identifier, region);
             beaconManager.startRangingBeacons(region);
@@ -386,26 +419,108 @@ public class CapacitorIbeaconPlugin extends Plugin implements BeaconConsumer {
 
     @PermissionCallback
     private void bluetoothScanPermissionCallback(PluginCall call) {
-        // Continue with the original request
-        requestWhenInUseAuthorization(call);
+        // Check if BLUETOOTH_SCAN was granted
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            boolean hasBluetoothScan =
+                ActivityCompat.checkSelfPermission(getContext(), Manifest.permission.BLUETOOTH_SCAN) == PackageManager.PERMISSION_GRANTED;
+
+            if (hasBluetoothScan) {
+                // Continue with the original request
+                requestWhenInUseAuthorization(call);
+            } else {
+                // Permission denied, resolve with denied status
+                JSObject ret = new JSObject();
+                ret.put("status", "denied");
+                call.resolve(ret);
+            }
+        } else {
+            // Continue with the original request on older versions
+            requestWhenInUseAuthorization(call);
+        }
     }
 
     @PermissionCallback
     private void bluetoothConnectPermissionCallback(PluginCall call) {
-        // Continue with the original request
-        requestWhenInUseAuthorization(call);
+        // Check if BLUETOOTH_CONNECT was granted
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            boolean hasBluetoothConnect =
+                ActivityCompat.checkSelfPermission(getContext(), Manifest.permission.BLUETOOTH_CONNECT) ==
+                PackageManager.PERMISSION_GRANTED;
+
+            if (hasBluetoothConnect) {
+                // Continue with the original request
+                requestWhenInUseAuthorization(call);
+            } else {
+                // Permission denied, resolve with denied status
+                JSObject ret = new JSObject();
+                ret.put("status", "denied");
+                call.resolve(ret);
+            }
+        } else {
+            // Continue with the original request on older versions
+            requestWhenInUseAuthorization(call);
+        }
     }
 
     @PermissionCallback
     private void bluetoothScanForBackgroundCallback(PluginCall call) {
-        // Continue with the background authorization flow
-        requestAlwaysAuthorization(call);
+        // Check if BLUETOOTH_SCAN was granted
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            boolean hasBluetoothScan =
+                ActivityCompat.checkSelfPermission(getContext(), Manifest.permission.BLUETOOTH_SCAN) == PackageManager.PERMISSION_GRANTED;
+
+            if (hasBluetoothScan) {
+                // Continue with the background authorization flow
+                requestAlwaysAuthorization(call);
+            } else {
+                // Permission denied, check what we can offer
+                boolean hasFineLocation =
+                    ActivityCompat.checkSelfPermission(getContext(), Manifest.permission.ACCESS_FINE_LOCATION) ==
+                    PackageManager.PERMISSION_GRANTED;
+
+                JSObject ret = new JSObject();
+                if (hasFineLocation) {
+                    ret.put("status", "authorized_when_in_use");
+                } else {
+                    ret.put("status", "denied");
+                }
+                call.resolve(ret);
+            }
+        } else {
+            // Continue with the background authorization flow on older versions
+            requestAlwaysAuthorization(call);
+        }
     }
 
     @PermissionCallback
     private void bluetoothConnectForBackgroundCallback(PluginCall call) {
-        // Continue with the background authorization flow
-        requestAlwaysAuthorization(call);
+        // Check if BLUETOOTH_CONNECT was granted
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            boolean hasBluetoothConnect =
+                ActivityCompat.checkSelfPermission(getContext(), Manifest.permission.BLUETOOTH_CONNECT) ==
+                PackageManager.PERMISSION_GRANTED;
+
+            if (hasBluetoothConnect) {
+                // Continue with the background authorization flow
+                requestAlwaysAuthorization(call);
+            } else {
+                // Permission denied, check what we can offer
+                boolean hasFineLocation =
+                    ActivityCompat.checkSelfPermission(getContext(), Manifest.permission.ACCESS_FINE_LOCATION) ==
+                    PackageManager.PERMISSION_GRANTED;
+
+                JSObject ret = new JSObject();
+                if (hasFineLocation) {
+                    ret.put("status", "authorized_when_in_use");
+                } else {
+                    ret.put("status", "denied");
+                }
+                call.resolve(ret);
+            }
+        } else {
+            // Continue with the background authorization flow on older versions
+            requestAlwaysAuthorization(call);
+        }
     }
 
     @PluginMethod
@@ -443,44 +558,7 @@ public class CapacitorIbeaconPlugin extends Plugin implements BeaconConsumer {
     public void enableBackgroundMode(PluginCall call) {
         Boolean enabled = call.getBoolean("enabled", true);
         try {
-            if (enabled != null && enabled) {
-                // Enable foreground service for background beacon scanning
-                // This is required on Android 8+ for reliable background operation
-                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-                    // Create notification channel for foreground service
-                    android.app.NotificationChannel channel = new android.app.NotificationChannel(
-                        "beacon_service_channel",
-                        "Beacon Service",
-                        android.app.NotificationManager.IMPORTANCE_LOW
-                    );
-                    channel.setDescription("Background beacon monitoring service");
-
-                    android.app.NotificationManager notificationManager = getContext().getSystemService(
-                        android.app.NotificationManager.class
-                    );
-                    if (notificationManager != null) {
-                        notificationManager.createNotificationChannel(channel);
-                    }
-
-                    // Build notification for foreground service
-                    android.app.Notification.Builder builder = new android.app.Notification.Builder(getContext(), "beacon_service_channel");
-                    builder.setSmallIcon(android.R.drawable.ic_dialog_info);
-                    builder.setContentTitle("Beacon Monitoring");
-                    builder.setContentText("Scanning for nearby beacons");
-
-                    // Enable foreground service mode in AltBeacon
-                    beaconManager.enableForegroundServiceScanning(builder.build(), 456);
-                }
-
-                // Set background mode
-                beaconManager.setBackgroundMode(true);
-            } else {
-                // Disable background mode
-                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-                    beaconManager.disableForegroundServiceScanning();
-                }
-                beaconManager.setBackgroundMode(false);
-            }
+            setBackgroundModeEnabled(enabled != null && enabled);
             call.resolve();
         } catch (Exception e) {
             call.reject("Failed to enable background mode", e);
@@ -608,4 +686,63 @@ public class CapacitorIbeaconPlugin extends Plugin implements BeaconConsumer {
             return "far";
         }
     }
+
+    private void setBackgroundModeEnabled(boolean enabled) {
+        backgroundModeEnabled = enabled;
+        applyBackgroundMode(enabled);
+    }
+
+    private void applyBackgroundMode(boolean enabled) {
+        if (beaconManager == null) {
+            return;
+        }
+
+        boolean shouldEnableBackgroundMode = enabled && isInBackground;
+
+        if (shouldEnableBackgroundMode) {
+            enableForegroundServiceIfNeeded();
+            beaconManager.setBackgroundMode(true);
+        } else {
+            disableForegroundServiceIfNeeded();
+            beaconManager.setBackgroundMode(false);
+        }
+    }
+
+    private void enableForegroundServiceIfNeeded() {
+        if (foregroundServiceEnabled || Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
+            return;
+        }
+
+        // Create notification channel for foreground service
+        android.app.NotificationChannel channel = new android.app.NotificationChannel(
+            FOREGROUND_CHANNEL_ID,
+            "Beacon Service",
+            android.app.NotificationManager.IMPORTANCE_LOW
+        );
+        channel.setDescription("Background beacon monitoring service");
+
+        android.app.NotificationManager notificationManager = getContext().getSystemService(android.app.NotificationManager.class);
+        if (notificationManager != null) {
+            notificationManager.createNotificationChannel(channel);
+        }
+
+        // Build notification for foreground service
+        android.app.Notification.Builder builder = new android.app.Notification.Builder(getContext(), FOREGROUND_CHANNEL_ID);
+        builder.setSmallIcon(android.R.drawable.ic_dialog_info);
+        builder.setContentTitle("Beacon Monitoring");
+        builder.setContentText("Scanning for nearby beacons");
+
+        // Enable foreground service mode in AltBeacon
+        beaconManager.enableForegroundServiceScanning(builder.build(), FOREGROUND_NOTIFICATION_ID);
+        foregroundServiceEnabled = true;
+    }
+
+    private void disableForegroundServiceIfNeeded() {
+        if (!foregroundServiceEnabled || Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
+            return;
+        }
+
+        beaconManager.disableForegroundServiceScanning();
+        foregroundServiceEnabled = false;
+    }
 }

package/dist/docs.json

@@ -526,6 +526,254 @@
           "BackgroundScanPeriodOptions"
         ],
         "slug": "setbackgroundscanperiod"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'didRangeBeacons', listenerFunc: (data: RangingEventData) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "- The event name ('didRangeBeacons')",
+            "type": "'didRangeBeacons'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "- Callback function that receives beacon data",
+            "type": "(data: RangingEventData) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "eventName - The event name ('didRangeBeacons')"
+          },
+          {
+            "name": "param",
+            "text": "listenerFunc - Callback function that receives beacon data"
+          },
+          {
+            "name": "returns",
+            "text": "Promise that resolves with a PluginListenerHandle"
+          },
+          {
+            "name": "since",
+            "text": "1.0.0"
+          },
+          {
+            "name": "example",
+            "text": "```typescript\nconst listener = await CapacitorIbeacon.addListener('didRangeBeacons', (data) => {\n  console.log('Beacons:', data.beacons);\n});\n// Remove listener when done\nawait listener.remove();\n```"
+          }
+        ],
+        "docs": "Listen for beacon ranging events.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "RangingEventData"
+        ],
+        "slug": "addlistenerdidrangebeacons-"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'didEnterRegion', listenerFunc: (data: { region: BeaconRegion; }) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "- The event name ('didEnterRegion')",
+            "type": "'didEnterRegion'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "- Callback function that receives region data",
+            "type": "(data: { region: BeaconRegion; }) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "eventName - The event name ('didEnterRegion')"
+          },
+          {
+            "name": "param",
+            "text": "listenerFunc - Callback function that receives region data"
+          },
+          {
+            "name": "returns",
+            "text": "Promise that resolves with a PluginListenerHandle"
+          },
+          {
+            "name": "since",
+            "text": "1.0.0"
+          },
+          {
+            "name": "example",
+            "text": "```typescript\nconst listener = await CapacitorIbeacon.addListener('didEnterRegion', (data) => {\n  console.log('Entered region:', data.region.identifier);\n});\n```"
+          }
+        ],
+        "docs": "Listen for region enter events.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "BeaconRegion"
+        ],
+        "slug": "addlistenerdidenterregion-"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'didExitRegion', listenerFunc: (data: { region: BeaconRegion; }) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "- The event name ('didExitRegion')",
+            "type": "'didExitRegion'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "- Callback function that receives region data",
+            "type": "(data: { region: BeaconRegion; }) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "eventName - The event name ('didExitRegion')"
+          },
+          {
+            "name": "param",
+            "text": "listenerFunc - Callback function that receives region data"
+          },
+          {
+            "name": "returns",
+            "text": "Promise that resolves with a PluginListenerHandle"
+          },
+          {
+            "name": "since",
+            "text": "1.0.0"
+          },
+          {
+            "name": "example",
+            "text": "```typescript\nconst listener = await CapacitorIbeacon.addListener('didExitRegion', (data) => {\n  console.log('Exited region:', data.region.identifier);\n});\n```"
+          }
+        ],
+        "docs": "Listen for region exit events.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "BeaconRegion"
+        ],
+        "slug": "addlistenerdidexitregion-"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'didDetermineStateForRegion', listenerFunc: (data: MonitoringEventData) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "- The event name ('didDetermineStateForRegion')",
+            "type": "'didDetermineStateForRegion'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "- Callback function that receives region and state data",
+            "type": "(data: MonitoringEventData) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "eventName - The event name ('didDetermineStateForRegion')"
+          },
+          {
+            "name": "param",
+            "text": "listenerFunc - Callback function that receives region and state data"
+          },
+          {
+            "name": "returns",
+            "text": "Promise that resolves with a PluginListenerHandle"
+          },
+          {
+            "name": "since",
+            "text": "1.0.0"
+          },
+          {
+            "name": "example",
+            "text": "```typescript\nconst listener = await CapacitorIbeacon.addListener('didDetermineStateForRegion', (data) => {\n  console.log('Region state:', data.state, 'for', data.region.identifier);\n});\n```"
+          }
+        ],
+        "docs": "Listen for region state determination events.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "MonitoringEventData"
+        ],
+        "slug": "addlistenerdiddeterminestateforregion-"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'monitoringDidFailForRegion', listenerFunc: (data: { region: BeaconRegion; error: string; }) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "- The event name ('monitoringDidFailForRegion')",
+            "type": "'monitoringDidFailForRegion'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "- Callback function that receives error data",
+            "type": "(data: { region: BeaconRegion; error: string; }) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "eventName - The event name ('monitoringDidFailForRegion')"
+          },
+          {
+            "name": "param",
+            "text": "listenerFunc - Callback function that receives error data"
+          },
+          {
+            "name": "returns",
+            "text": "Promise that resolves with a PluginListenerHandle"
+          },
+          {
+            "name": "since",
+            "text": "1.0.0"
+          },
+          {
+            "name": "example",
+            "text": "```typescript\nconst listener = await CapacitorIbeacon.addListener('monitoringDidFailForRegion', (data) => {\n  console.error('Monitoring failed:', data.error);\n});\n```"
+          }
+        ],
+        "docs": "Listen for monitoring failure events.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "BeaconRegion"
+        ],
+        "slug": "addlistenermonitoringdidfailforregion-"
+      },
+      {
+        "name": "removeAllListeners",
+        "signature": "() => Promise<void>",
+        "parameters": [],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "Promise that resolves when all listeners are removed"
+          },
+          {
+            "name": "since",
+            "text": "1.0.0"
+          },
+          {
+            "name": "example",
+            "text": "```typescript\nawait CapacitorIbeacon.removeAllListeners();\n```"
+          }
+        ],
+        "docs": "Remove all listeners for this plugin.",
+        "complexTypes": [],
+        "slug": "removealllisteners"
       }
     ],
     "properties": []
@@ -572,6 +820,13 @@
           "docs": "Notify when device enters region (iOS only).",
           "complexTypes": [],
           "type": "boolean | undefined"
+        },
+        {
+          "name": "enableBackgroundMode",
+          "tags": [],
+          "docs": "Enable Android background mode for this monitoring/ranging call.\nWhen true, the plugin will keep scanning in background using a foreground service.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
         }
       ]
     },
@@ -641,6 +896,125 @@
           "type": "number | undefined"
         }
       ]
+    },
+    {
+      "name": "PluginListenerHandle",
+      "slug": "pluginlistenerhandle",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "remove",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "() => Promise<void>"
+        }
+      ]
+    },
+    {
+      "name": "RangingEventData",
+      "slug": "rangingeventdata",
+      "docs": "Event data when beacons are ranged.",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "region",
+          "tags": [],
+          "docs": "Region that was ranged.",
+          "complexTypes": [
+            "BeaconRegion"
+          ],
+          "type": "BeaconRegion"
+        },
+        {
+          "name": "beacons",
+          "tags": [],
+          "docs": "Array of detected beacons.",
+          "complexTypes": [
+            "Beacon"
+          ],
+          "type": "Beacon[]"
+        }
+      ]
+    },
+    {
+      "name": "Beacon",
+      "slug": "beacon",
+      "docs": "Detected beacon information.",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "uuid",
+          "tags": [],
+          "docs": "Beacon UUID.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "major",
+          "tags": [],
+          "docs": "Major value.",
+          "complexTypes": [],
+          "type": "number"
+        },
+        {
+          "name": "minor",
+          "tags": [],
+          "docs": "Minor value.",
+          "complexTypes": [],
+          "type": "number"
+        },
+        {
+          "name": "rssi",
+          "tags": [],
+          "docs": "RSSI (Received Signal Strength Indicator).",
+          "complexTypes": [],
+          "type": "number"
+        },
+        {
+          "name": "proximity",
+          "tags": [],
+          "docs": "Proximity: 'immediate', 'near', 'far', or 'unknown'.",
+          "complexTypes": [],
+          "type": "'immediate' | 'near' | 'far' | 'unknown'"
+        },
+        {
+          "name": "accuracy",
+          "tags": [],
+          "docs": "Estimated distance in meters.",
+          "complexTypes": [],
+          "type": "number"
+        }
+      ]
+    },
+    {
+      "name": "MonitoringEventData",
+      "slug": "monitoringeventdata",
+      "docs": "Event data when entering or exiting a region.",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "region",
+          "tags": [],
+          "docs": "Region that triggered the event.",
+          "complexTypes": [
+            "BeaconRegion"
+          ],
+          "type": "BeaconRegion"
+        },
+        {
+          "name": "state",
+          "tags": [],
+          "docs": "Event state: 'enter' or 'exit'.",
+          "complexTypes": [],
+          "type": "'enter' | 'exit'"
+        }
+      ]
     }
   ],
   "enums": [],

package/dist/esm/definitions.d.ts

@@ -1,9 +1,10 @@
+import type { Plugin, PluginListenerHandle } from '@capacitor/core';
 /**
  * Capacitor iBeacon Plugin - Proximity detection and beacon region monitoring.
  *
  * @since 1.0.0
  */
-export interface CapacitorIbeaconPlugin {
+export interface CapacitorIbeaconPlugin extends Plugin {
     /**
      * Start monitoring for a beacon region. Triggers events when entering/exiting the region.
      *
@@ -253,6 +254,101 @@ export interface CapacitorIbeaconPlugin {
      * ```
      */
     setBackgroundScanPeriod(options: BackgroundScanPeriodOptions): Promise<void>;
+    /**
+     * Listen for beacon ranging events.
+     *
+     * @param eventName - The event name ('didRangeBeacons')
+     * @param listenerFunc - Callback function that receives beacon data
+     * @returns Promise that resolves with a PluginListenerHandle
+     * @since 1.0.0
+     * @example
+     * ```typescript
+     * const listener = await CapacitorIbeacon.addListener('didRangeBeacons', (data) => {
+     *   console.log('Beacons:', data.beacons);
+     * });
+     * // Remove listener when done
+     * await listener.remove();
+     * ```
+     */
+    addListener(eventName: 'didRangeBeacons', listenerFunc: (data: RangingEventData) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for region enter events.
+     *
+     * @param eventName - The event name ('didEnterRegion')
+     * @param listenerFunc - Callback function that receives region data
+     * @returns Promise that resolves with a PluginListenerHandle
+     * @since 1.0.0
+     * @example
+     * ```typescript
+     * const listener = await CapacitorIbeacon.addListener('didEnterRegion', (data) => {
+     *   console.log('Entered region:', data.region.identifier);
+     * });
+     * ```
+     */
+    addListener(eventName: 'didEnterRegion', listenerFunc: (data: {
+        region: BeaconRegion;
+    }) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for region exit events.
+     *
+     * @param eventName - The event name ('didExitRegion')
+     * @param listenerFunc - Callback function that receives region data
+     * @returns Promise that resolves with a PluginListenerHandle
+     * @since 1.0.0
+     * @example
+     * ```typescript
+     * const listener = await CapacitorIbeacon.addListener('didExitRegion', (data) => {
+     *   console.log('Exited region:', data.region.identifier);
+     * });
+     * ```
+     */
+    addListener(eventName: 'didExitRegion', listenerFunc: (data: {
+        region: BeaconRegion;
+    }) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for region state determination events.
+     *
+     * @param eventName - The event name ('didDetermineStateForRegion')
+     * @param listenerFunc - Callback function that receives region and state data
+     * @returns Promise that resolves with a PluginListenerHandle
+     * @since 1.0.0
+     * @example
+     * ```typescript
+     * const listener = await CapacitorIbeacon.addListener('didDetermineStateForRegion', (data) => {
+     *   console.log('Region state:', data.state, 'for', data.region.identifier);
+     * });
+     * ```
+     */
+    addListener(eventName: 'didDetermineStateForRegion', listenerFunc: (data: MonitoringEventData) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for monitoring failure events.
+     *
+     * @param eventName - The event name ('monitoringDidFailForRegion')
+     * @param listenerFunc - Callback function that receives error data
+     * @returns Promise that resolves with a PluginListenerHandle
+     * @since 1.0.0
+     * @example
+     * ```typescript
+     * const listener = await CapacitorIbeacon.addListener('monitoringDidFailForRegion', (data) => {
+     *   console.error('Monitoring failed:', data.error);
+     * });
+     * ```
+     */
+    addListener(eventName: 'monitoringDidFailForRegion', listenerFunc: (data: {
+        region: BeaconRegion;
+        error: string;
+    }) => void): Promise<PluginListenerHandle>;
+    /**
+     * Remove all listeners for this plugin.
+     *
+     * @returns Promise that resolves when all listeners are removed
+     * @since 1.0.0
+     * @example
+     * ```typescript
+     * await CapacitorIbeacon.removeAllListeners();
+     * ```
+     */
+    removeAllListeners(): Promise<void>;
 }
 /**
  * Beacon region definition for monitoring and ranging.
@@ -278,6 +374,11 @@ export interface BeaconRegion {
      * Notify when device enters region (iOS only).
      */
     notifyEntryStateOnDisplay?: boolean;
+    /**
+     * Enable Android background mode for this monitoring/ranging call.
+     * When true, the plugin will keep scanning in background using a foreground service.
+     */
+    enableBackgroundMode?: boolean;
 }
 /**
  * Background scan period configuration options (Android only).
@@ -374,35 +475,3 @@ export interface MonitoringEventData {
      */
     state: 'enter' | 'exit';
 }
-/**
- * Event listeners for iBeacon plugin.
- */
-export interface BeaconEventListeners {
-    /**
-     * Called when beacons are detected during ranging.
-     */
-    didRangeBeacons?: (data: RangingEventData) => void;
-    /**
-     * Called when entering or exiting a monitored region.
-     */
-    didDetermineStateForRegion?: (data: MonitoringEventData) => void;
-    /**
-     * Called when entering a monitored region.
-     */
-    didEnterRegion?: (data: {
-        region: BeaconRegion;
-    }) => void;
-    /**
-     * Called when exiting a monitored region.
-     */
-    didExitRegion?: (data: {
-        region: BeaconRegion;
-    }) => void;
-    /**
-     * Called when monitoring state changes.
-     */
-    monitoringDidFailForRegion?: (data: {
-        region: BeaconRegion;
-        error: string;
-    }) => void;
-}

package/ios/Sources/CapacitorIbeaconPlugin/CapacitorIbeaconPlugin.swift

@@ -4,7 +4,7 @@ import CoreLocation
 
 @objc(CapacitorIbeaconPlugin)
 public class CapacitorIbeaconPlugin: CAPPlugin, CAPBridgedPlugin {
-    private let pluginVersion: String = "8.1.1"
+    private let pluginVersion: String = "8.1.3"
     public let identifier = "CapacitorIbeaconPlugin"
     public let jsName = "CapacitorIbeacon"
     public let pluginMethods: [CAPPluginMethod] = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/capacitor-ibeacon",
-  "version": "8.1.1",
+  "version": "8.1.3",
   "description": "iBeacon plugin for Capacitor - proximity detection and beacon region monitoring",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",