expo-beacon 0.1.0 → 0.3.0

package/README.md

@@ -11,7 +11,7 @@ An Expo module for scanning, pairing, and monitoring iBeacons in React Native ap
 | Platform | Native implementation                                                                                     |
 | -------- | --------------------------------------------------------------------------------------------------------- |
 | Android  | [AltBeacon](https://altbeacon.github.io/android-beacon-library/) (`org.altbeacon:android-beacon-library`) |
-| iOS      | CoreLocation / `CLLocationManager` (iBeacon native API)                                                   |
+| iOS      | CoreLocation (UUID-targeted scans & monitoring) + CoreBluetooth (wildcard scanning)                       |
 | Web      | Not supported (throws on all calls)                                                                        |
 
 ---
@@ -47,6 +47,8 @@ In Xcode under **Signing & Capabilities**, enable:
 - **Background Modes → Uses Bluetooth LE accessories**
 
 > iOS limits apps to **20 simultaneously monitored regions**.
+>
+> **Wildcard scanning**: When you call `scanForBeaconsAsync()` with an empty or omitted `uuids` array, iOS uses CoreBluetooth raw BLE scanning to discover all nearby iBeacons. This works **in the foreground only** — it is an Apple platform limitation. UUID-targeted scans and background monitoring continue to use CoreLocation.
 
 ### Android
 
@@ -111,7 +113,8 @@ export default function App() {
   }, []);
 
   async function scan() {
-    const results = await ExpoBeacon.scanForBeaconsAsync(5000);
+    // Wildcard scan — discovers all nearby iBeacons (no UUID filter)
+    const results = await ExpoBeacon.scanForBeaconsAsync([], 5000);
     setBeacons(results);
   }
 
@@ -158,23 +161,41 @@ if (!granted) {
 
 ---
 
-### `scanForBeaconsAsync(scanDurationMs?)`
+### `scanForBeaconsAsync(uuids?, scanDurationMs?)`
 
 ```ts
-scanForBeaconsAsync(scanDurationMs?: number): Promise<BeaconScanResult[]>
+scanForBeaconsAsync(uuids?: string[], scanDurationMs?: number): Promise<BeaconScanResult[]>
 ```
 
 Starts a **one-shot BLE scan**, waits for `scanDurationMs` milliseconds, then resolves with all beacons discovered during that window.
 
-| Parameter       | Type     | Default | Description                              |
-| --------------- | -------- | ------- | ---------------------------------------- |
-| `scanDurationMs`| `number` | `5000`  | How long to scan in milliseconds (1–60 000 recommended) |
+| Parameter        | Type       | Default | Description                              |
+| ---------------- | ---------- | ------- | ---------------------------------------- |
+| `uuids`          | `string[]` | `[]`    | Proximity UUIDs to filter by. Pass `[]` or omit for a **wildcard scan** that discovers all nearby iBeacons. |
+| `scanDurationMs` | `number`   | `5000`  | How long to scan in milliseconds (1–60 000 recommended) |
 
 Returns an array of [`BeaconScanResult`](#beaconscanresult) objects. Rejects with `SCAN_IN_PROGRESS` if another scan is already running.
 
+**Wildcard vs. targeted scans**
+
+| | Wildcard (`[]` / omitted) | Targeted (`['UUID-1', …]`) |
+|---|---|---|
+| **Android** | Discovers all iBeacons via AltBeacon | Filters results to matching UUIDs |
+| **iOS** | CoreBluetooth raw BLE scan (**foreground only**) | CoreLocation ranging (works in background) |
+
+> **iOS limitation**: Wildcard scanning uses CoreBluetooth, which cannot scan in the background. If your app is backgrounded during a wildcard scan, no new beacons will be discovered. Use UUID-targeted scans or `startMonitoring()` for background beacon detection.
+
 ```ts
-const beacons = await ExpoBeacon.scanForBeaconsAsync(8000); // 8-second scan
-beacons.forEach((b) =>
+// Wildcard scan — discover all nearby iBeacons
+const all = await ExpoBeacon.scanForBeaconsAsync([], 5000);
+
+// Targeted scan — only beacons matching these UUIDs
+const filtered = await ExpoBeacon.scanForBeaconsAsync(
+  ['E2C56DB5-DFFB-48D2-B060-D0F5A71096E0'],
+  8000,
+);
+
+filtered.forEach((b) =>
   console.log(`${b.uuid}  major=${b.major}  minor=${b.minor}  dist=${b.distance.toFixed(1)}m  rssi=${b.rssi}dBm`)
 );
 ```
@@ -191,6 +212,8 @@ Begins a **continuous BLE scan** that fires an [`onBeaconFound`](#onbeaconfound)
 
 Unlike `scanForBeaconsAsync`, this never resolves — it streams results in real time.
 
+> **iOS note**: Due to CoreLocation API constraints, `startContinuousScan()` on iOS only ranges beacons that have been previously paired with `pairBeacon()`. On Android, all nearby BLE beacons are reported regardless of pairing status.
+
 ```ts
 const sub = ExpoBeacon.addListener("onBeaconFound", (beacon) => {
   console.log("Live:", beacon.uuid, beacon.distance);
@@ -276,28 +299,46 @@ paired.forEach((b) =>
 
 ---
 
-### `startMonitoring(maxDistance?)`
+### `startMonitoring(options?)`
 
 ```ts
-startMonitoring(maxDistance?: number): Promise<void>
+startMonitoring(options?: MonitoringOptions | number): Promise<void>
 ```
 
 Starts background region monitoring for all paired beacons.
 
-| Parameter     | Type     | Default      | Description                                                                                   |
-| ------------- | -------- | ------------ | --------------------------------------------------------------------------------------------- |
-| `maxDistance` | `number` | `undefined`  | Optional distance threshold in metres. `onBeaconEnter` is only emitted when the measured distance is ≤ this value. `onBeaconExit` is always emitted. Omit to disable distance filtering. |
+Accepts either a `MonitoringOptions` object or a plain `number` (backward-compatible shorthand for `maxDistance`).
+
+**`MonitoringOptions`**
+
+| Property        | Type                 | Default     | Description                                                                                   |
+| --------------- | -------------------- | ----------- | --------------------------------------------------------------------------------------------- |
+| `maxDistance`   | `number`             | `undefined` | Optional distance threshold in metres. `onBeaconEnter` is only emitted when the measured distance is ≤ this value. `onBeaconExit` is always emitted. Omit to disable distance filtering. |
+| `notifications` | `NotificationConfig` | `undefined` | Notification config overrides applied for this session. Persisted and takes effect immediately. |
 
 **Android**: Launches `BeaconForegroundService` — a persistent foreground service required by Android 8+ for background BLE. Restarts automatically after device reboot.
 
 **iOS**: Activates `CLLocationManager` region monitoring. iOS can wake or relaunch the app when a region boundary is crossed, even if the app is terminated.
 
 ```ts
-// Monitor with no distance limit
-await ExpoBeacon.startMonitoring();
-
-// Only fire enter events when within 5 metres
+// Backward-compatible shorthand (number = maxDistance)
 await ExpoBeacon.startMonitoring(5);
+
+// Full options object
+await ExpoBeacon.startMonitoring({
+  maxDistance: 5,
+  notifications: {
+    beaconEvents: {
+      enterTitle: "Beacon nearby!",
+      body: "{identifier} is within range",
+    },
+  },
+});
+
+// Monitor with no distance limit and no enter/exit notifications
+await ExpoBeacon.startMonitoring({
+  notifications: { beaconEvents: { enabled: false } },
+});
 ```
 
 > Call `requestPermissionsAsync()` before `startMonitoring()`.
@@ -318,6 +359,48 @@ await ExpoBeacon.stopMonitoring();
 
 ---
 
+### `setNotificationConfig(config)`
+
+```ts
+setNotificationConfig(config: NotificationConfig): void
+```
+
+Persists notification configuration that is applied to all subsequent monitoring sessions. Values are stored in `SharedPreferences` (Android) / `UserDefaults` (iOS) and survive app restarts.
+
+For one-off overrides tied to a single session, pass `notifications` directly in [`startMonitoring(options)`](#startmonitoringoptions) instead — it calls this function automatically.
+
+```ts
+ExpoBeacon.setNotificationConfig({
+  // Enter/exit alert notifications
+  beaconEvents: {
+    enabled: true,                    // false to suppress all enter/exit notifications
+    enterTitle: "Beacon nearby",
+    exitTitle: "Beacon out of range",
+    body: "{identifier} {event}ed",   // {identifier} and {event} are replaced at runtime
+    sound: true,                      // iOS only — default true
+    icon: "ic_beacon_notification",   // Android only — drawable resource name
+  },
+
+  // Persistent status-bar notification while monitoring is active (Android only)
+  foregroundService: {
+    title: "My App is watching",
+    text: "Monitoring for nearby beacons",
+    icon: "ic_service",               // Android drawable resource name
+  },
+
+  // Android notification channel settings
+  channel: {
+    name: "Proximity Alerts",
+    description: "Alerts when beacons enter or leave range",
+    importance: "default",            // "low" | "default" | "high"
+  },
+});
+```
+
+> **Android channel importance note**: Android prevents decreasing channel importance once a user has been notified. Increasing importance always works; decreasing it will have no effect until the user clears the app's notification settings or reinstalls the app.
+
+---
+
 ## Events
 
 Subscribe to events using `ExpoBeacon.addListener(eventName, handler)`. Always call `.remove()` on the subscription when your component unmounts.
@@ -360,15 +443,7 @@ ExpoBeacon.addListener("onBeaconExit", (e) => {
 
 ### `onBeaconRanging`
 
-Fired periodically during active monitoring with the latest ranging measurement for a paired beacon.
-
-**Payload**: [`BeaconRangingEvent`](#beaconrangingevent)
-
-```ts
-ExpoBeacon.addListener("onBeaconRanging", (e) => {
-  console.log(`Ranging ${e.identifier}: ${e.distance.toFixed(2)} m  rssi=${e.rssi}`);
-});
-```
+> **Not currently emitted.** This event is declared in the TypeScript types ([`BeaconRangingEvent`](#beaconrangingevent)) but is not fired by either the iOS or Android native implementation. Use [`onBeaconDistance`](#onbeacondistance) for periodic distance updates during monitoring.
 
 ---
 
@@ -447,7 +522,7 @@ type BeaconRegionEvent = {
 
 ### `BeaconRangingEvent`
 
-Payload for `onBeaconRanging`.
+Payload type for the `onBeaconRanging` event. **Declared for future use — this event is not currently emitted by either platform.** Use [`BeaconDistanceEvent`](#beacondistanceevent) and [`onBeaconDistance`](#onbeacondistance) for real-time distance updates.
 
 ```ts
 type BeaconRangingEvent = {
@@ -476,6 +551,71 @@ type BeaconDistanceEvent = {
 
 ---
 
+### `MonitoringOptions`
+
+Passed to `startMonitoring(options)`.
+
+```ts
+type MonitoringOptions = {
+  maxDistance?: number;           // Distance threshold in metres for enter events
+  notifications?: NotificationConfig; // Notification overrides for this session
+};
+```
+
+### `NotificationConfig`
+
+Top-level config object accepted by `setNotificationConfig()` and `startMonitoring({ notifications })`.
+
+```ts
+type NotificationConfig = {
+  beaconEvents?: BeaconNotificationConfig;
+  foregroundService?: ForegroundServiceConfig;  // Android only
+  channel?: NotificationChannelConfig;          // Android only
+};
+```
+
+### `BeaconNotificationConfig`
+
+Controls the enter/exit alert notifications.
+
+```ts
+type BeaconNotificationConfig = {
+  enabled?: boolean;     // false to disable all enter/exit notifications. Default: true
+  enterTitle?: string;   // Default: "Beacon Entered"
+  exitTitle?: string;    // Default: "Beacon Exited"
+  body?: string;         // Template — {identifier} and {event} are replaced at runtime
+                         // Default: "{identifier} region {event}ed"
+  sound?: boolean;       // iOS only — play notification sound. Default: true
+  icon?: string;         // Android only — drawable resource name (e.g. "ic_notification")
+};
+```
+
+### `ForegroundServiceConfig`
+
+Controls the persistent Android status-bar notification while monitoring is active.
+
+```ts
+type ForegroundServiceConfig = {
+  title?: string;  // Default: "Beacon Monitoring Active"
+  text?: string;   // Default: "Monitoring for iBeacons in the background"
+  icon?: string;   // Android drawable resource name
+};
+```
+
+### `NotificationChannelConfig`
+
+Controls the Android notification channel shown in system settings.
+
+```ts
+type NotificationChannelConfig = {
+  name?: string;                          // Default: "Beacon Monitoring"
+  description?: string;                   // Default: "Used for background iBeacon region monitoring"
+  importance?: "low" | "default" | "high"; // Default: "low"
+};
+```
+
+---
+
 ## Background Behaviour
 
 ### Android
@@ -494,20 +634,36 @@ Default scan timing: 1.1 s scan window every 5 s.
 
 ## Notifications
 
-A local notification is posted for every `onBeaconEnter` and `onBeaconExit` event.
+A local notification is posted for every `onBeaconEnter` and `onBeaconExit` event. All notification settings can be customised via [`setNotificationConfig()`](#setnotificationconfigconfig) or inline in [`startMonitoring(options)`](#startmonitoringoptions).
+
+### Defaults
+
+| Property                       | Default value                                    |
+| ------------------------------ | ------------------------------------------------ |
+| Enter title                    | `"Beacon Entered"`                               |
+| Exit title                     | `"Beacon Exited"`                                |
+| Body                           | `"{identifier} region {event}ed"`                |
+| Sound (iOS)                    | `true`                                           |
+| Icon (Android)                 | System `ic_dialog_info`                          |
+| Foreground service title       | `"Beacon Monitoring Active"`                     |
+| Foreground service text        | `"Monitoring for iBeacons in the background"`    |
+| Channel name (Android)         | `"Beacon Monitoring"`                            |
+| Channel importance (Android)   | `"low"`                                          |
+
+### Channel IDs (Android)
 
 | Channel / type                  | Importance          |
 | ------------------------------- | ------------------- |
-| Foreground service (Android)    | `IMPORTANCE_LOW`    |
-| Enter / exit alerts             | `IMPORTANCE_DEFAULT`|
+| Foreground service (Android)    | configurable (default `low`) |
+| Enter / exit alerts             | configurable (default `default`) |
 
-Both channels share the id `expo_beacon_channel`.
+Both notifications share the channel id `expo_beacon_channel`. The channel is recreated on each `onStartCommand` so config changes take effect on the next monitoring start.
 
 ---
 
 ## Contributing
 
-Contributions are welcome! Please refer to the [contributing guide](https://github.com/expo/expo#contributing).
+Contributions are welcome! Open an issue or pull request on [GitHub](https://github.com/martinmikesCCS/expo-beacon).
 
 ## License
 

package/android/src/main/java/expo/modules/beacon/BeaconForegroundService.kt

@@ -18,7 +18,12 @@ private const val PREFS_NAME = "expo.beacon.paired"
 private const val PREFS_KEY = "paired_beacons"
 private const val CHANNEL_ID = "expo_beacon_channel"
 private const val FOREGROUND_NOTIF_ID = 1001
-private const val ENTER_EXIT_NOTIF_ID = 1002
+private const val ENTER_EXIT_NOTIF_BASE_ID = 2000
+
+/// Number of consecutive ranging misses before emitting a distance-based exit event.
+private const val EXIT_MISS_THRESHOLD = 3
+/// Number of consecutive readings required to confirm a distance-based enter or exit transition.
+private const val HYSTERESIS_COUNT = 3
 
 class BeaconForegroundService : Service(), BeaconConsumer {
 
@@ -30,6 +35,16 @@ class BeaconForegroundService : Service(), BeaconConsumer {
     private val rangingRegions = java.util.concurrent.CopyOnWriteArraySet<Region>()
     private val enteredRegions = java.util.concurrent.CopyOnWriteArraySet<String>()
 
+    // Hysteresis counters (synchronized on distanceLock)
+    private val distanceLock = Any()
+    private val enterCounters = java.util.concurrent.ConcurrentHashMap<String, Int>()
+    private val exitCounters = java.util.concurrent.ConcurrentHashMap<String, Int>()
+    private val missCounters = java.util.concurrent.ConcurrentHashMap<String, Int>()
+
+    // Notification ID counter for unique per-beacon notifications
+    private var notifIdCounter = 0
+    private val notifIdMap = java.util.concurrent.ConcurrentHashMap<String, Int>()
+
     // Distance logging
     private val distanceLogRegions = java.util.concurrent.CopyOnWriteArraySet<Region>()
 
@@ -70,7 +85,8 @@ class BeaconForegroundService : Service(), BeaconConsumer {
                 )
             }
             // Use continuous scanning (not JobScheduler) for foreground service
-            manager.setEnableScheduledScanJobs(false)
+            // Guard: throws if called after ranging/monitoring has already started
+            try { manager.setEnableScheduledScanJobs(false) } catch (_: IllegalStateException) {}
             manager.setBackgroundBetweenScanPeriod(5000L)  // 5s between scans
             manager.setBackgroundScanPeriod(1100L)         // 1.1s scan window
             manager.setForegroundScanPeriod(1000L)         // 1s scan window for distance logging
@@ -152,26 +168,62 @@ class BeaconForegroundService : Service(), BeaconConsumer {
             Log.d("BeaconMonitor", "[${region.uniqueId}] distance: ${"%.2f".format(closest.distance)} m  rssi=${closest.rssi}  txPower=${closest.txPower}")
             sendBeaconBroadcast(region, "distance", closest.distance)
 
+            // Reset miss counter — we got a valid reading
+            missCounters[region.uniqueId] = 0
+
             val maxDist = maxDistance
             if (maxDist != null) {
-                if (!enteredRegions.contains(region.uniqueId) && closest.distance <= maxDist) {
-                    // Distance-based entry
-                    Log.d("BeaconMonitor", "[${region.uniqueId}] distance ${closest.distance}m <= maxDistance ${maxDist}m — synthesizing enter")
-                    enteredRegions.add(region.uniqueId)
-                    rangingRegions.remove(region)
-                    sendBeaconBroadcast(region, "enter", closest.distance)
-                    showEnterExitNotification(region, "enter")
-                } else if (enteredRegions.contains(region.uniqueId) && closest.distance > maxDist) {
-                    // Distance-based exit
-                    Log.d("BeaconMonitor", "[${region.uniqueId}] distance ${closest.distance}m > maxDistance ${maxDist}m — synthesizing exit")
-                    enteredRegions.remove(region.uniqueId)
-                    rangingRegions.add(region)
-                    sendBeaconBroadcast(region, "exit", closest.distance)
-                    showEnterExitNotification(region, "exit")
+                synchronized(distanceLock) {
+                    if (closest.distance <= maxDist) {
+                        // Reading is inside threshold
+                        exitCounters[region.uniqueId] = 0
+                        val count = (enterCounters[region.uniqueId] ?: 0) + 1
+                        enterCounters[region.uniqueId] = count
+
+                        if (!enteredRegions.contains(region.uniqueId) && count >= HYSTERESIS_COUNT) {
+                            enteredRegions.add(region.uniqueId)
+                            enterCounters[region.uniqueId] = 0
+                            rangingRegions.remove(region)
+                            sendBeaconBroadcast(region, "enter", closest.distance)
+                            showEnterExitNotification(region, "enter")
+                        }
+                    } else {
+                        // Reading is outside threshold
+                        enterCounters[region.uniqueId] = 0
+                        val count = (exitCounters[region.uniqueId] ?: 0) + 1
+                        exitCounters[region.uniqueId] = count
+
+                        if (enteredRegions.contains(region.uniqueId) && count >= HYSTERESIS_COUNT) {
+                            enteredRegions.remove(region.uniqueId)
+                            exitCounters[region.uniqueId] = 0
+                            rangingRegions.add(region)
+                            sendBeaconBroadcast(region, "exit", closest.distance)
+                            showEnterExitNotification(region, "exit")
+                        }
+                    }
                 }
             }
         } else {
             Log.d("BeaconMonitor", "[${region.uniqueId}] no beacons in range")
+
+            // Beacon may have disappeared — track consecutive misses
+            val maxDist = maxDistance
+            if (maxDist != null) {
+                val count = (missCounters[region.uniqueId] ?: 0) + 1
+                missCounters[region.uniqueId] = count
+
+                if (enteredRegions.contains(region.uniqueId) && count >= EXIT_MISS_THRESHOLD) {
+                    synchronized(distanceLock) {
+                        if (enteredRegions.remove(region.uniqueId)) {
+                            missCounters[region.uniqueId] = 0
+                            enterCounters[region.uniqueId] = 0
+                            exitCounters[region.uniqueId] = 0
+                            sendBeaconBroadcast(region, "exit", -1.0)
+                            showEnterExitNotification(region, "exit")
+                        }
+                    }
+                }
+            }
         }
     }
 
@@ -189,8 +241,15 @@ class BeaconForegroundService : Service(), BeaconConsumer {
         }
 
         override fun didExitRegion(region: Region) {
-            // Remove from confirmation tracking (ranging stays active for distance logging)
             rangingRegions.remove(region)
+
+            if (maxDistance != null) {
+                // When maxDistance is set, distance ranging handles exit events.
+                // Just clean up tracked state so distance-driven exit can fire.
+                enteredRegions.remove(region.uniqueId)
+                return
+            }
+
             enteredRegions.remove(region.uniqueId)
             sendBeaconBroadcast(region, "exit", -1.0)
             showEnterExitNotification(region, "exit")
@@ -208,12 +267,19 @@ class BeaconForegroundService : Service(), BeaconConsumer {
             .filter { it.distance >= 0 }
             .minByOrNull { it.distance } ?: return@RangeNotifier
 
-        if (beacon.distance <= maxDist && !enteredRegions.contains(region.uniqueId)) {
-            enteredRegions.add(region.uniqueId)
-            // Remove from confirmation tracking (ranging stays active for distance logging)
-            rangingRegions.remove(region)
-            sendBeaconBroadcast(region, "enter", beacon.distance)
-            showEnterExitNotification(region, "enter")
+        synchronized(distanceLock) {
+            if (beacon.distance <= maxDist && !enteredRegions.contains(region.uniqueId)) {
+                val count = (enterCounters[region.uniqueId] ?: 0) + 1
+                enterCounters[region.uniqueId] = count
+
+                if (count >= HYSTERESIS_COUNT) {
+                    enteredRegions.add(region.uniqueId)
+                    enterCounters[region.uniqueId] = 0
+                    rangingRegions.remove(region)
+                    sendBeaconBroadcast(region, "enter", beacon.distance)
+                    showEnterExitNotification(region, "enter")
+                }
+            }
         }
     }
 
@@ -231,11 +297,33 @@ class BeaconForegroundService : Service(), BeaconConsumer {
     }
 
     private fun showEnterExitNotification(region: Region, eventType: String) {
-        val title = if (eventType == "enter") "Beacon Entered" else "Beacon Exited"
-        val message = "${region.uniqueId} region ${eventType}ed"
+        val config = readNotificationConfig()
+        val eventsConfig = config.optJSONObject("beaconEvents")
+
+        // Respect the enabled flag (defaults to true)
+        if (eventsConfig != null && !eventsConfig.optBoolean("enabled", true)) return
+
+        val defaultTitle = if (eventType == "enter") "Beacon Entered" else "Beacon Exited"
+        val title = if (eventType == "enter") {
+            eventsConfig?.optString("enterTitle")?.takeIf { it.isNotEmpty() } ?: defaultTitle
+        } else {
+            eventsConfig?.optString("exitTitle")?.takeIf { it.isNotEmpty() } ?: defaultTitle
+        }
+
+        val bodyTemplate = eventsConfig?.optString("body")?.takeIf { it.isNotEmpty() }
+            ?: "{identifier} region {event}ed"
+        val message = bodyTemplate
+            .replace("{identifier}", region.uniqueId)
+            .replace("{event}", eventType)
+
+        val iconName = eventsConfig?.optString("icon")?.takeIf { it.isNotEmpty() }
+        val iconResId = iconName?.let { name ->
+            try { resources.getIdentifier(name, "drawable", packageName).takeIf { it != 0 } }
+            catch (_: Exception) { null }
+        } ?: android.R.drawable.ic_dialog_info
 
         val notification = NotificationCompat.Builder(this, CHANNEL_ID)
-            .setSmallIcon(android.R.drawable.ic_dialog_info)
+            .setSmallIcon(iconResId)
             .setContentTitle(title)
             .setContentText(message)
             .setPriority(NotificationCompat.PRIORITY_DEFAULT)
@@ -243,7 +331,10 @@ class BeaconForegroundService : Service(), BeaconConsumer {
             .build()
 
         try {
-            NotificationManagerCompat.from(this).notify(ENTER_EXIT_NOTIF_ID, notification)
+            val notifId = notifIdMap.getOrPut(region.uniqueId) {
+                ENTER_EXIT_NOTIF_BASE_ID + notifIdCounter++
+            }
+            NotificationManagerCompat.from(this).notify(notifId, notification)
         } catch (_: SecurityException) {
             // POST_NOTIFICATIONS not granted — silently skip notification
         }
@@ -251,27 +342,59 @@ class BeaconForegroundService : Service(), BeaconConsumer {
 
     private fun createNotificationChannel() {
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-            val channel = NotificationChannel(
-                CHANNEL_ID,
-                "Beacon Monitoring",
-                NotificationManager.IMPORTANCE_LOW
-            ).apply {
-                description = "Used for background iBeacon region monitoring"
+            val config = readNotificationConfig()
+            val channelConfig = config.optJSONObject("channel")
+
+            val channelName = channelConfig?.optString("name")?.takeIf { it.isNotEmpty() }
+                ?: "Beacon Monitoring"
+            val channelDesc = channelConfig?.optString("description")?.takeIf { it.isNotEmpty() }
+                ?: "Used for background iBeacon region monitoring"
+            val importance = when (channelConfig?.optString("importance")) {
+                "high" -> NotificationManager.IMPORTANCE_HIGH
+                "default" -> NotificationManager.IMPORTANCE_DEFAULT
+                else -> NotificationManager.IMPORTANCE_LOW
+            }
+
+            val notifMgr = getSystemService(NotificationManager::class.java)
+            // Only create channel if it doesn't exist yet — preserves user notification preferences
+            if (notifMgr?.getNotificationChannel(CHANNEL_ID) == null) {
+                val channel = NotificationChannel(CHANNEL_ID, channelName, importance).apply {
+                    description = channelDesc
+                }
+                notifMgr?.createNotificationChannel(channel)
             }
-            getSystemService(NotificationManager::class.java)?.createNotificationChannel(channel)
         }
     }
 
     private fun buildForegroundNotification(): Notification {
+        val config = readNotificationConfig()
+        val fgConfig = config.optJSONObject("foregroundService")
+
+        val title = fgConfig?.optString("title")?.takeIf { it.isNotEmpty() }
+            ?: "Beacon Monitoring Active"
+        val text = fgConfig?.optString("text")?.takeIf { it.isNotEmpty() }
+            ?: "Monitoring for iBeacons in the background"
+        val iconName = fgConfig?.optString("icon")?.takeIf { it.isNotEmpty() }
+        val iconResId = iconName?.let { name ->
+            try { resources.getIdentifier(name, "drawable", packageName).takeIf { it != 0 } }
+            catch (_: Exception) { null }
+        } ?: android.R.drawable.ic_dialog_info
+
         return NotificationCompat.Builder(this, CHANNEL_ID)
-            .setSmallIcon(android.R.drawable.ic_dialog_info)
-            .setContentTitle("Beacon Monitoring Active")
-            .setContentText("Monitoring for iBeacons in the background")
+            .setSmallIcon(iconResId)
+            .setContentTitle(title)
+            .setContentText(text)
             .setPriority(NotificationCompat.PRIORITY_LOW)
             .setOngoing(true)
             .build()
     }
 
+    private fun readNotificationConfig(): org.json.JSONObject {
+        val json = getSharedPreferences("expo.beacon.notification_config", Context.MODE_PRIVATE)
+            .getString("config", null) ?: return org.json.JSONObject()
+        return try { org.json.JSONObject(json) } catch (_: Exception) { org.json.JSONObject() }
+    }
+
     override fun onDestroy() {
         beaconManager.removeMonitorNotifier(monitorNotifier)
         beaconManager.removeRangeNotifier(rangeNotifier)
@@ -285,6 +408,10 @@ class BeaconForegroundService : Service(), BeaconConsumer {
         }
         distanceLogRegions.clear()
         enteredRegions.clear()
+        enterCounters.clear()
+        exitCounters.clear()
+        missCounters.clear()
+        notifIdMap.clear()
         monitoredRegions.forEach {
             try { beaconManager.stopMonitoringBeaconsInRegion(it) } catch (_: RemoteException) {}
         }