expo-beacon 0.10.2 → 0.10.4

package/README.md

@@ -271,6 +271,8 @@ function BeaconScreen() {
 | `getMonitoringConfig()` | Read the current monitoring config + active-state snapshot. |
 | `getMonitoredDeviceState()` / `getMonitoredDeviceStates()` | Native state snapshot for one / all paired devices. |
 | `setNotificationConfig()` | Persist notification configuration for monitoring sessions. |
+| `setBeaconNotificationConfig()` | Persist only beacon notification settings. |
+| `setCarPlayNotificationConfig()` | Persist only CarPlay / Android Auto notification settings. |
 | `enableEventLogging()` / `disableEventLogging()` | Toggle SQLite logging (updates `isEventLoggingEnabled`). |
 | `getEventLogs()` / `clearEventLogs()` / `destroyEventLogs()` | Read / clear / drop the persisted event log. |
 | `setApiEndpoint()` / `getApiEndpoint()` | Configure / read the native event-forwarding endpoint. |
@@ -660,28 +662,57 @@ await ExpoBeacon.startMonitoring();
 
 ```ts
 ExpoBeacon.setNotificationConfig({
-  // Enter/exit alert notifications (both platforms)
-  beaconEvents: {
-    enabled: true,                        // Set false to suppress notifications entirely
-    enterTitle: "Beacon nearby",
-    exitTitle: "Beacon out of range",
-    body: "{identifier} {event}ed",       // Placeholders: {identifier}, {event}
-    sound: true,                          // iOS only
-    icon: "ic_beacon_notification",       // Android only — drawable resource name
-  },
+  beacons: {
+    // Enter/exit/timeout alert notifications (both platforms)
+    events: {
+      enabled: true,                      // Set false to suppress beacon alerts
+      enterTitle: "Beacon nearby",
+      exitTitle: "Beacon out of range",
+      timeoutTitle: "Beacon timed out",
+      body: "{identifier} {event}ed",     // Placeholders: {identifier}, {event}
+      sound: true,                        // iOS only
+      icon: "ic_beacon_notification",     // Android only — drawable resource name
+    },
+
+    // Persistent status-bar notification for beacon monitoring (Android only)
+    foregroundService: {
+      title: "My App — Beacon monitoring",
+      text: "Watching for nearby beacons",
+      icon: "ic_service",
+    },
 
-  // Persistent status-bar notification (Android only)
-  foregroundService: {
-    title: "My App — Monitoring",
-    text: "Watching for nearby beacons",
-    icon: "ic_service",
+    // Android notification channel for beacon notifications
+    channel: {
+      name: "Proximity Alerts",
+      description: "Alerts when beacons enter or leave range",
+      importance: "default",              // "low" | "default" | "high"
+    },
   },
 
-  // Android notification channel
-  channel: {
-    name: "Proximity Alerts",
-    description: "Alerts when beacons enter or leave range",
-    importance: "default",                // "low" | "default" | "high"
+  carPlay: {
+    // Connect/disconnect notifications (both platforms)
+    events: {
+      enabled: true,                      // Set false to suppress CarPlay alerts
+      connectedTitle: "CarPlay connected",
+      disconnectedTitle: "CarPlay disconnected",
+      body: "CarPlay {event} {transport}", // Placeholders: {event}, {transport}
+      sound: true,                        // iOS only
+      icon: "ic_carplay_notification",    // Android only — drawable resource name
+    },
+
+    // Persistent status-bar notification in CarPlay-only mode (Android only)
+    foregroundService: {
+      title: "My App — Vehicle monitoring",
+      text: "Monitoring CarPlay / Android Auto",
+      icon: "ic_service",
+    },
+
+    // Android notification channel for CarPlay notifications
+    channel: {
+      name: "CarPlay Alerts",
+      description: "CarPlay and Android Auto connection notifications",
+      importance: "default",
+    },
   },
 });
 ```
@@ -1323,10 +1354,28 @@ setNotificationConfig(config: NotificationConfig): void
 
 Persists notification configuration applied to **all subsequent monitoring sessions**. Survives app restarts.
 
-For one-off overrides, pass `notifications` inside `startMonitoring(options)` instead.
+For one-off overrides, pass `notifications` inside `startMonitoring(options)` instead. Monitoring-time notification overrides are merged into the persisted notification config, so omitted beacon or CarPlay sections are preserved.
+
+Use the top-level `beacons` and `carPlay` sections to configure those notification streams independently. Legacy keys (`beaconEvents`, `carPlayEvents`, `foregroundService`, `channel`, `carPlayChannel`) are still accepted for existing apps.
 
 See [`NotificationConfig`](#notificationconfig) for the full shape.
 
+### `setBeaconNotificationConfig(config)`
+
+```ts
+setBeaconNotificationConfig(config: BeaconNotificationSettings | BeaconNotificationConfig): void
+```
+
+Persists only beacon notification settings without replacing CarPlay settings. Passing a plain `BeaconNotificationConfig` is treated as `beacons.events`.
+
+### `setCarPlayNotificationConfig(config)`
+
+```ts
+setCarPlayNotificationConfig(config: CarPlayNotificationSettings | CarPlayNotificationConfig): void
+```
+
+Persists only CarPlay / Android Auto notification settings without replacing beacon settings. Passing a plain `CarPlayNotificationConfig` is treated as `carPlay.events`.
+
 ---
 
 ### `enableEventLogging()`
@@ -1591,9 +1640,13 @@ import type {
   ExpoBeaconModuleEvents,
   MonitoringOptions,
   NotificationConfig,
+  BeaconNotificationSettings,
   BeaconNotificationConfig,
+  CarPlayNotificationSettings,
+  CarPlayNotificationConfig,
   ForegroundServiceConfig,
   NotificationChannelConfig,
+  CarPlayChannelConfig,
   EventLogQueryOptions,
   EventLogEntry,
 } from "expo-beacon";
@@ -1774,9 +1827,35 @@ Top-level notification configuration.
 
 ```ts
 type NotificationConfig = {
-  beaconEvents?: BeaconNotificationConfig;     // Enter/exit alerts
-  foregroundService?: ForegroundServiceConfig;  // Android only — persistent status bar
-  channel?: NotificationChannelConfig;          // Android only — channel settings
+  beacons?: BeaconNotificationSettings;
+  carPlay?: CarPlayNotificationSettings;
+
+  // Legacy aliases, still accepted:
+  beaconEvents?: BeaconNotificationConfig;
+  carPlayEvents?: CarPlayNotificationConfig;
+  foregroundService?: ForegroundServiceConfig;
+  channel?: NotificationChannelConfig;
+  carPlayChannel?: CarPlayChannelConfig;
+};
+```
+
+### `BeaconNotificationSettings`
+
+```ts
+type BeaconNotificationSettings = {
+  events?: BeaconNotificationConfig;
+  foregroundService?: ForegroundServiceConfig; // Android only, title/text/icon only
+  channel?: NotificationChannelConfig;         // Android only, beacon alert channel
+};
+```
+
+### `CarPlayNotificationSettings`
+
+```ts
+type CarPlayNotificationSettings = {
+  events?: CarPlayNotificationConfig;
+  foregroundService?: ForegroundServiceConfig; // Android only, CarPlay-only title/text/icon
+  channel?: CarPlayChannelConfig;              // Android only, CarPlay alert channel
 };
 ```
 
@@ -1805,6 +1884,8 @@ type ForegroundServiceConfig = {
 };
 ```
 
+Foreground service notifications always use the dedicated Android channel `expo_beacon_foreground_channel`, created with low importance and no sound/vibration. This config only changes the notification content.
+
 ### `NotificationChannelConfig`
 
 ```ts
@@ -1815,6 +1896,30 @@ type NotificationChannelConfig = {
 };
 ```
 
+### `CarPlayNotificationConfig`
+
+```ts
+type CarPlayNotificationConfig = {
+  enabled?: boolean;          // Default: true. Set false to suppress.
+  connectedTitle?: string;    // Default: "CarPlay Connected"
+  disconnectedTitle?: string; // Default: "CarPlay Disconnected"
+  body?: string;              // Default: "CarPlay session {event}"
+                              // Supports {event} and {transport} placeholders.
+  sound?: boolean;            // iOS only. Default: true
+  icon?: string;              // Android only. Drawable resource name.
+};
+```
+
+### `CarPlayChannelConfig`
+
+```ts
+type CarPlayChannelConfig = {
+  name?: string;                            // Default: "CarPlay / Android Auto"
+  description?: string;                     // Default: "CarPlay and Android Auto connect/disconnect notifications"
+  importance?: "low" | "default" | "high"; // Default: "default"
+};
+```
+
 ### `BeaconTimeoutEvent`
 
 Payload for `onBeaconTimeout`.
@@ -2101,7 +2206,7 @@ override fun onCreate() {
 
 ## Notifications
 
-A local notification is posted automatically for every beacon enter/exit event (both iBeacon and Eddystone) during monitoring.
+Local notifications are posted automatically for beacon enter/exit/timeout events and CarPlay / Android Auto connect/disconnect events. Beacon notifications and CarPlay notifications have separate configuration sections and separate Android channels.
 
 ### Default Values
 
@@ -2110,16 +2215,25 @@ A local notification is posted automatically for every beacon enter/exit event (
 | Enter title | `"Beacon Entered"` |
 | Exit title | `"Beacon Exited"` |
 | Body | `"{identifier} region {event}ed"` |
+| CarPlay connected title | `"CarPlay Connected"` |
+| CarPlay disconnected title | `"CarPlay Disconnected"` |
+| CarPlay body | `"CarPlay session {event}"` |
 | Sound (iOS) | `true` |
 | Icon (Android) | System `ic_dialog_info` |
 | Foreground service title | `"Beacon Monitoring Active"` |
 | Foreground service text | `"Monitoring for iBeacons in the background"` |
+| CarPlay-only foreground title | `"Connected device monitoring active"` |
+| CarPlay-only foreground text | `"Monitoring connected vehicle (CarPlay/Android Auto)"` |
+| Foreground channel name (Android) | `"Beacon Foreground Service"` |
+| Foreground channel importance (Android) | `"low"` (no sound/vibration) |
 | Channel name (Android) | `"Beacon Monitoring"` |
 | Channel importance (Android) | `"low"` |
+| CarPlay channel name (Android) | `"CarPlay / Android Auto"` |
+| CarPlay channel importance (Android) | `"default"` |
 
-### Android Channel
+### Android Channels
 
-Both the foreground service and enter/exit alerts share the channel ID `expo_beacon_channel`. The channel is recreated on each `onStartCommand`, so config changes take effect on the next monitoring start.
+Foreground-service notifications use their own quiet channel ID, `expo_beacon_foreground_channel`, so the persistent status notification does not make sound or vibrate. Beacon event notifications use `expo_beacon_channel`; CarPlay / Android Auto event notifications use `expo_beacon_carplay_channel`. In CarPlay-only mode, the foreground-service notification still uses the quiet foreground channel but reads title/text/icon from `carPlay.foregroundService`.
 
 > **Android channel importance note**: Android prevents decreasing channel importance after the first notification. Increasing works; decreasing has no effect until the user clears notification settings or reinstalls the app.
 

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

@@ -19,6 +19,7 @@ import org.altbeacon.beacon.*
 import org.json.JSONArray
 
 private const val CHANNEL_ID = "expo_beacon_channel"
+private const val FOREGROUND_CHANNEL_ID = "expo_beacon_foreground_channel"
 private const val CARPLAY_CHANNEL_ID = "expo_beacon_carplay_channel"
 internal const val FOREGROUND_NOTIF_ID = 1001
 /**
@@ -102,6 +103,7 @@ class BeaconForegroundService : Service(), BeaconConsumer {
     override fun onCreate() {
         super.onCreate()
         activeService = this
+        ensureForegroundNotificationChannel(this)
         ensureNotificationChannel(this)
         ensureCarPlayNotificationChannel(this)
         apiForwarder = BeaconApiForwarder(this)
@@ -947,7 +949,7 @@ class BeaconForegroundService : Service(), BeaconConsumer {
 
     private fun showEnterExitNotification(region: Region, eventType: String) {
         val config = readNotificationConfig()
-        val eventsConfig = config.optJSONObject("beaconEvents")
+        val eventsConfig = notificationSection(config, "beacons", "events", "beaconEvents")
 
         // Respect the enabled flag (defaults to true)
         if (eventsConfig != null && !eventsConfig.optBoolean("enabled", true)) return
@@ -1162,7 +1164,7 @@ class BeaconForegroundService : Service(), BeaconConsumer {
 
     private fun showCarPlayNotification(eventType: String, transport: String?) {
         val config = readNotificationConfig()
-        val eventsConfig = config.optJSONObject("carPlayEvents")
+        val eventsConfig = notificationSection(config, "carPlay", "events", "carPlayEvents")
 
         // Respect the enabled flag (defaults to true)
         if (eventsConfig != null && !eventsConfig.optBoolean("enabled", true)) return
@@ -1239,6 +1241,7 @@ class BeaconForegroundService : Service(), BeaconConsumer {
                     .edit()
                     .putBoolean(MONITORING_ACTIVE_KEY, true)
                     .apply()
+            ensureForegroundNotificationChannel(context)
             ensureNotificationChannel(context)
             ensureCarPlayNotificationChannel(context)
             val intent = Intent(context, BeaconForegroundService::class.java)
@@ -1307,6 +1310,7 @@ class BeaconForegroundService : Service(), BeaconConsumer {
          */
         fun enableCarPlay(context: Context) {
             setCarPlayEnabled(context, true)
+            ensureForegroundNotificationChannel(context)
             ensureNotificationChannel(context)
             ensureCarPlayNotificationChannel(context)
             // Arm the WorkManager watchdog (15-min periodic safety net) and the
@@ -1468,6 +1472,15 @@ class BeaconForegroundService : Service(), BeaconConsumer {
             }
         }
 
+        internal fun notificationSection(
+                config: org.json.JSONObject,
+                parentKey: String,
+                childKey: String,
+                legacyKey: String
+        ): org.json.JSONObject? =
+                config.optJSONObject(parentKey)?.optJSONObject(childKey)
+                        ?: config.optJSONObject(legacyKey)
+
         /**
          * Resolve the configured small-icon drawable from [config], falling back to a stock icon.
          */
@@ -1488,13 +1501,21 @@ class BeaconForegroundService : Service(), BeaconConsumer {
         private fun ensureChannel(
                 context: Context,
                 channelId: String,
-                configKey: String,
+                parentKey: String,
+                childKey: String,
+                legacyKey: String,
                 defaultName: String,
                 defaultDescription: String,
                 fallbackImportance: Int
         ) {
             if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
-            val channelConfig = readNotificationConfig(context).optJSONObject(configKey)
+            val channelConfig =
+                    notificationSection(
+                            readNotificationConfig(context),
+                            parentKey,
+                            childKey,
+                            legacyKey
+                    )
 
             val channelName =
                     channelConfig?.optString("name")?.takeIf { it.isNotEmpty() } ?: defaultName
@@ -1528,6 +1549,8 @@ class BeaconForegroundService : Service(), BeaconConsumer {
                 ensureChannel(
                         context,
                         CHANNEL_ID,
+                        "beacons",
+                        "channel",
                         "channel",
                         "Beacon Monitoring",
                         "Used for background iBeacon region monitoring",
@@ -1543,19 +1566,47 @@ class BeaconForegroundService : Service(), BeaconConsumer {
                 ensureChannel(
                         context,
                         CARPLAY_CHANNEL_ID,
+                        "carPlay",
+                        "channel",
                         "carPlayChannel",
                         "CarPlay / Android Auto",
                         "CarPlay and Android Auto connect/disconnect notifications",
                         NotificationManager.IMPORTANCE_DEFAULT
                 )
 
+        /**
+         * Ensure the persistent foreground-service notification has a quiet channel of its own.
+         * Event channels can be default/high importance, but the always-on service status should
+         * never make sound or vibrate.
+         */
+        fun ensureForegroundNotificationChannel(context: Context) {
+            if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+            val notifMgr = context.getSystemService(NotificationManager::class.java)
+            if (notifMgr?.getNotificationChannel(FOREGROUND_CHANNEL_ID) == null) {
+                val channel =
+                        NotificationChannel(
+                                        FOREGROUND_CHANNEL_ID,
+                                        "Beacon Foreground Service",
+                                        NotificationManager.IMPORTANCE_LOW
+                                )
+                                .apply {
+                                    description =
+                                            "Persistent status for beacon and CarPlay background monitoring"
+                                    setSound(null, null)
+                                    enableVibration(false)
+                                }
+                notifMgr?.createNotificationChannel(channel)
+            }
+        }
+
         /**
          * Build the persistent foreground-service notification from any Context. Static so
          * cold-start paths that run before a service instance exists (e.g. [BootReceiver]) read the
          * same persisted config.
          */
         fun buildForegroundNotification(context: Context): Notification {
-            val fgConfig = readNotificationConfig(context).optJSONObject("foregroundService")
+            ensureForegroundNotificationChannel(context)
+            val config = readNotificationConfig(context)
 
             // If beacon monitoring is not active and the service is alive only
             // for CarPlay observation, fall back to a generic notification so
@@ -1568,15 +1619,31 @@ class BeaconForegroundService : Service(), BeaconConsumer {
             val defaultText =
                     if (carPlayOnly) "Monitoring connected vehicle (CarPlay/Android Auto)"
                     else "Monitoring for iBeacons in the background"
-
+            val fgConfig =
+                    if (carPlayOnly) {
+                        notificationSection(
+                                config,
+                                "carPlay",
+                                "foregroundService",
+                                "foregroundService"
+                        )
+                    } else {
+                        notificationSection(
+                                config,
+                                "beacons",
+                                "foregroundService",
+                                "foregroundService"
+                        )
+                    }
             val title = fgConfig?.optString("title")?.takeIf { it.isNotEmpty() } ?: defaultTitle
             val text = fgConfig?.optString("text")?.takeIf { it.isNotEmpty() } ?: defaultText
 
-            return NotificationCompat.Builder(context, CHANNEL_ID)
+            return NotificationCompat.Builder(context, FOREGROUND_CHANNEL_ID)
                     .setSmallIcon(resolveIconRes(context, fgConfig))
                     .setContentTitle(title)
                     .setContentText(text)
                     .setPriority(NotificationCompat.PRIORITY_LOW)
+                    .setSilent(true)
                     .setOngoing(true)
                     .build()
         }