@capgo/capacitor-ibeacon 8.1.2 → 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.2";
+    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);
@@ -525,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);
@@ -690,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

@@ -820,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"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -374,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).

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.2"
+    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.2",
+  "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",