expo-beacon 0.7.26 → 0.8.1

package/README.md

@@ -687,6 +687,65 @@ try {
 
 ---
 
+### CarPlay / Android Auto Detection
+
+Detect when the device connects to a car infotainment system and react in JS — or, when the bundled config plugin is installed, automatically start `react-native-background-geolocation` tracking on connect and stop it on disconnect.
+
+Detection covers both **wired and wireless CarPlay** on iOS and **Android Auto projection / Android Automotive OS** on Android. No special CarPlay entitlement or Android Auto certification is required.
+
+```ts
+import ExpoBeacon, {
+  CarPlayConnectedEvent,
+  CarPlayDisconnectedEvent,
+} from "expo-beacon";
+
+// Start observing
+await ExpoBeacon.startCarPlayMonitoring();
+
+const connectSub = ExpoBeacon.addListener(
+  "onCarPlayConnected",
+  (event: CarPlayConnectedEvent) => {
+    // event.transport: "wired" | "wireless" | "projection" | "native" | "unknown"
+    console.log(`Car connected via ${event.transport}`);
+  },
+);
+const disconnectSub = ExpoBeacon.addListener(
+  "onCarPlayDisconnected",
+  (_event: CarPlayDisconnectedEvent) => {
+    console.log("Car disconnected");
+  },
+);
+
+// Stop later (e.g. when feature is disabled)
+await ExpoBeacon.stopCarPlayMonitoring();
+connectSub.remove();
+disconnectSub.remove();
+```
+
+**How it works**
+
+- **iOS:** observes `AVAudioSession.routeChangeNotification` for output ports of type `.carAudio`. Wired-vs-wireless is reported on a best-effort basis (looking for a coexisting Bluetooth output port).
+- **Android:** observes `androidx.car.app.connection.CarConnection` LiveData. `transport` is `"projection"` for phones casting to a head unit, `"native"` for Android Automotive OS.
+- Connect/disconnect events flow through the same SQLite event log and remote API forwarder as beacon events.
+- When the config plugin is installed, the auto-generated `BeaconGeoPlugin` also calls `BackgroundGeolocation.start()` on connect and `.stop()` on disconnect — no extra wiring required.
+
+**Background detection**
+
+CarPlay observation is **persistent** — the enabled flag is stored in native preferences and the observer is automatically re-attached after app kill or device reboot. `startMonitoring()` also enables CarPlay observation by default; calling `startCarPlayMonitoring()` explicitly is only required if you want CarPlay events without beacon monitoring.
+
+- **Android:** the foreground service hosts the `CarConnection` observer. As long as the service runs (which it does whenever beacon monitoring or CarPlay monitoring is enabled, and is restarted on boot by `BootReceiver`), CarPlay events are captured even after the app process is killed. **Guaranteed background detection.**
+- **iOS:** the observer auto-restarts in the module's `OnCreate`, including background-launches triggered by beacon region monitoring. **iOS cannot wake a terminated app on CarPlay alone** — for guaranteed wake-from-suspension, also call `startMonitoring()` with at least one paired beacon (e.g. a beacon left in the vehicle). Region-wake events trigger a CarPlay state resync to reconcile any route changes that happened while the app was suspended.
+
+**Notes**
+
+- `startCarPlayMonitoring()` is idempotent. Calling it twice does not register a duplicate observer.
+- `stopCarPlayMonitoring()` clears the persisted flag, so the observer will not auto-restart on next launch.
+- The iOS detector does not require the CarPlay entitlement because it only reads the active audio route; you do not need to ship a CarPlay app.
+- On iOS, if the JS bundle is suspended in the background, the JS event delivery is deferred until the app resumes, but the native lifecycle delegate (used by the geolocation plugin) fires immediately on connect.
+- On Android, when CarPlay monitoring is enabled without beacon monitoring, the foreground service shows a generic "Connected device monitoring active" notification.
+
+---
+
 ## Full API Reference
 
 ### `requestPermissionsAsync()`

package/android/build.gradle

@@ -20,4 +20,7 @@ android {
 
 dependencies {
   implementation 'org.altbeacon:android-beacon-library:2.21.2'
+  // androidx.car.app provides CarConnection LiveData for detecting Android Auto sessions.
+  // No Android Auto certification or extra permissions required for read-only state.
+  implementation 'androidx.car.app:app:1.4.0'
 }

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

@@ -16,4 +16,10 @@ interface BeaconEventPlugin {
     fun onEddystoneEnter(identifier: String, namespace: String, instance: String, distance: Double)
     fun onEddystoneExit(identifier: String, namespace: String, instance: String, distance: Double)
     fun onEddystoneTimeout(identifier: String, namespace: String, instance: String, distance: Double)
+
+    // CarPlay / Android Auto
+    /** Called when the device connects to an Android Auto session. Default no-op. */
+    fun onCarPlayConnected(transport: String) {}
+    /** Called when the device disconnects from an Android Auto session. Default no-op. */
+    fun onCarPlayDisconnected() {}
 }

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

@@ -84,6 +84,12 @@ class BeaconForegroundService : Service(), BeaconConsumer {
     // Seconds of silence after last valid sighting before a disappearance-based exit fires.
     @Volatile private var exitTimeoutMs: Long = (DEFAULT_EXIT_TIMEOUT_SECONDS * 1000.0).toLong()
 
+    // CarPlay / Android Auto observer hosted by the foreground service so that
+    // CarConnection events are captured for as long as the service runs —
+    // independent of the JS bridge / module lifecycle. Survives app suspension
+    // and (via BootReceiver) device reboot.
+    @Volatile private var carPlayMonitor: CarPlayMonitor? = null
+
     override fun onCreate() {
         super.onCreate()
         activeService = this
@@ -106,6 +112,14 @@ class BeaconForegroundService : Service(), BeaconConsumer {
         // process and inherits the elevated priority. Calling enable/disable on the
         // shared singleton causes crashes when the ExpoBeaconModule has an active
         // scan bound to the same BeaconManager.
+
+        // Restore CarPlay observer if the user previously enabled CarPlay
+        // monitoring. Reading the flag here means cold-started services
+        // (e.g. via BootReceiver after reboot) automatically re-attach the
+        // observer with no JS interaction required.
+        if (isCarPlayEnabled(this)) {
+            startCarPlayObserverInternal()
+        }
     }
 
     override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
@@ -134,11 +148,32 @@ class BeaconForegroundService : Service(), BeaconConsumer {
             stopSelf()
             return START_NOT_STICKY
         }
+        // Handle CarPlay enable/disable actions. These can arrive after the
+        // service is already running for beacon monitoring, OR be the reason
+        // the service was started in the first place (CarPlay-only mode).
+        when (intent?.action) {
+            ACTION_ENABLE_CARPLAY -> {
+                setCarPlayEnabled(this, true)
+                startCarPlayObserverInternal()
+            }
+            ACTION_DISABLE_CARPLAY -> {
+                setCarPlayEnabled(this, false)
+                stopCarPlayObserverInternal()
+                // If the service is only alive for CarPlay (no beacon monitoring),
+                // shut it down so we don't keep an unnecessary foreground notification.
+                if (!isMonitoringActive(this)) {
+                    stopSelf()
+                    return START_NOT_STICKY
+                }
+            }
+        }
         if (serviceConnected) {
             // Already bound from a prior onStartCommand — reload regions directly
             // so that re-starting monitoring from JS always takes effect.
             loadAndMonitorRegions()
-        } else {
+        } else if (isMonitoringActive(this)) {
+            // Only bind to AltBeacon when beacon monitoring is active.
+            // CarPlay-only mode keeps the service alive without scanning.
             beaconManager.bind(this)
         }
         return START_STICKY
@@ -765,6 +800,64 @@ class BeaconForegroundService : Service(), BeaconConsumer {
         }
     }
 
+    // MARK: - CarPlay observer (service-hosted)
+
+    /**
+     * Lazily instantiate and start the CarPlay observer. Idempotent —
+     * `CarPlayMonitor.start` itself is safe to call multiple times.
+     * Must be called from any thread; the monitor hops to main internally.
+     */
+    private fun startCarPlayObserverInternal() {
+        val monitor = carPlayMonitor ?: try {
+            CarPlayMonitor(applicationContext).also { carPlayMonitor = it }
+        } catch (e: Throwable) {
+            Log.w(TAG, "Failed to create CarPlayMonitor", e)
+            return
+        }
+        try {
+            monitor.start { eventName, payload ->
+                emitCarPlayEvent(eventName, payload)
+            }
+        } catch (e: Throwable) {
+            Log.w(TAG, "Failed to start CarPlayMonitor", e)
+        }
+    }
+
+    private fun stopCarPlayObserverInternal() {
+        carPlayMonitor?.stop()
+        // Keep the instance — it's idempotent, and recreating costs nothing
+        // beyond the `CarConnection` LiveData wrapper. Setting null here is
+        // also safe but unnecessary.
+    }
+
+    /**
+     * Fan out a CarPlay event to all sinks: SQLite log, remote API forwarder,
+     * native plugin registry, and (best-effort) the live JS bridge. Runs from
+     * the main thread (CarPlayMonitor's emit hop).
+     */
+    private fun emitCarPlayEvent(eventName: String, payload: Map<String, Any?>) {
+        // SQLite log (only if event logging is enabled).
+        try {
+            if (BeaconEventLogger.isLoggingEnabled(this)) {
+                val identifier = payload["identifier"] as? String
+                getOrCreateEventLogger().logEvent(eventName, identifier, payload)
+            }
+        } catch (e: Throwable) {
+            Log.w(TAG, "CarPlay log write failed", e)
+        }
+        // Remote API forwarder (no-op if unconfigured).
+        try { apiForwarder?.forwardEvent(payload) } catch (_: Throwable) {}
+        // Native plugin registry (BeaconGeoPlugin etc.).
+        when (eventName) {
+            "onCarPlayConnected" -> BeaconPluginRegistry.dispatchCarPlayConnected(
+                payload["transport"] as? String ?: "unknown"
+            )
+            "onCarPlayDisconnected" -> BeaconPluginRegistry.dispatchCarPlayDisconnected()
+        }
+        // Best-effort delivery to the live JS bridge if a module instance is bound.
+        try { boundModule?.get()?.forwardCarPlayEventFromService(eventName, payload) } catch (_: Throwable) {}
+    }
+
     private fun createNotificationChannel() {
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
             val config = readNotificationConfig()
@@ -814,13 +907,20 @@ class BeaconForegroundService : Service(), BeaconConsumer {
         const val DISTANCE_JUMP_FACTOR = 5.0
 
         private const val PREF_IS_MONITORING = "expo.beacon.is_monitoring"
+        private const val PREF_CARPLAY_ENABLED = "expo.beacon.carplay_enabled"
         private const val EXTRA_RETRY_COUNT = "retryCount"
+        /** Intent action: enable CarPlay/Android Auto observation in the foreground service. */
+        const val ACTION_ENABLE_CARPLAY = "expo.modules.beacon.ENABLE_CARPLAY"
+        /** Intent action: disable CarPlay/Android Auto observation. Stops the service if no other reason to run. */
+        const val ACTION_DISABLE_CARPLAY = "expo.modules.beacon.DISABLE_CARPLAY"
         private const val MAX_STARTFOREGROUND_RETRIES = 3
         private const val RETRY_DELAY_MS = 10_000L
         private const val RETRY_SERVICE_REQUEST_CODE = 0x42454143 // "BEAC"
         /** Minimum milliseconds between consecutive loadAndMonitorRegions() calls. */
         private const val LOAD_REGIONS_DEBOUNCE_MS = 500L
         @Volatile private var activeService: BeaconForegroundService? = null
+        /** Weak reference to the live ExpoBeaconModule for best-effort JS bridge fan-out. */
+        @Volatile private var boundModule: java.lang.ref.WeakReference<ExpoBeaconModule>? = null
 
         fun start(context: Context) {
             context.getSharedPreferences(PREF_IS_MONITORING, Context.MODE_PRIVATE)
@@ -837,6 +937,12 @@ class BeaconForegroundService : Service(), BeaconConsumer {
         fun stop(context: Context) {
             context.getSharedPreferences(PREF_IS_MONITORING, Context.MODE_PRIVATE)
                 .edit().putBoolean("active", false).apply()
+            // Keep the service alive if it's still needed for CarPlay observation;
+            // otherwise the user would silently lose CarPlay events when calling
+            // stopMonitoring() while CarPlay monitoring was independently enabled.
+            if (isCarPlayEnabled(context)) {
+                return
+            }
             context.stopService(Intent(context, BeaconForegroundService::class.java))
         }
 
@@ -845,6 +951,70 @@ class BeaconForegroundService : Service(), BeaconConsumer {
                 .getBoolean("active", false)
         }
 
+        // MARK: - CarPlay public API
+
+        /**
+         * Persist whether the user wants CarPlay observation. Cold service starts
+         * (e.g. via [BootReceiver]) read this flag in [onCreate] and re-attach
+         * the observer automatically.
+         */
+        internal fun setCarPlayEnabled(context: Context, enabled: Boolean) {
+            context.getSharedPreferences(PREF_CARPLAY_ENABLED, Context.MODE_PRIVATE)
+                .edit().putBoolean("enabled", enabled).apply()
+        }
+
+        fun isCarPlayEnabled(context: Context): Boolean {
+            return context.getSharedPreferences(PREF_CARPLAY_ENABLED, Context.MODE_PRIVATE)
+                .getBoolean("enabled", false)
+        }
+
+        /**
+         * Enable CarPlay observation. Starts the foreground service if it's not
+         * already running so the observer survives app suspension and process death.
+         * Idempotent and safe to call from any context.
+         */
+        fun enableCarPlay(context: Context) {
+            setCarPlayEnabled(context, true)
+            ensureNotificationChannel(context)
+            val intent = Intent(context, BeaconForegroundService::class.java)
+                .setAction(ACTION_ENABLE_CARPLAY)
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                context.startForegroundService(intent)
+            } else {
+                context.startService(intent)
+            }
+        }
+
+        /**
+         * Disable CarPlay observation. The foreground service stops itself
+         * if no other monitoring reason remains.
+         */
+        fun disableCarPlay(context: Context) {
+            setCarPlayEnabled(context, false)
+            val intent = Intent(context, BeaconForegroundService::class.java)
+                .setAction(ACTION_DISABLE_CARPLAY)
+            // Best-effort: if the service isn't running, sending the intent will
+            // start it just to stop it. Skip startForegroundService unless beacon
+            // monitoring is also active (otherwise the start might fail with
+            // ForegroundServiceStartNotAllowedException on some Android versions).
+            if (activeService != null || isMonitoringActive(context)) {
+                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                    context.startForegroundService(intent)
+                } else {
+                    context.startService(intent)
+                }
+            }
+        }
+
+        /**
+         * Bind a live module instance for best-effort JS-bridge delivery of
+         * service-emitted events. The reference is weak; pass `null` from the
+         * module's OnDestroy to clear it.
+         */
+        fun bindModule(module: ExpoBeaconModule?) {
+            boundModule = module?.let { java.lang.ref.WeakReference(it) }
+        }
+
         fun getMonitoringRuntimeSnapshot(): Map<String, MonitoringRuntimeState> {
             return activeService?.snapshotMonitoringRuntimeState() ?: emptyMap()
         }
@@ -891,10 +1061,16 @@ class BeaconForegroundService : Service(), BeaconConsumer {
             val config = try { org.json.JSONObject(json ?: "") } catch (_: Exception) { org.json.JSONObject() }
             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"
+            // If beacon monitoring is not active and the service is alive only
+            // for CarPlay observation, fall back to a generic notification so
+            // users don't see "Monitoring for iBeacons" when no beacons are being
+            // monitored.
+            val carPlayOnly = !isMonitoringActive(context) && isCarPlayEnabled(context)
+            val defaultTitle = if (carPlayOnly) "Connected device monitoring active" else "Beacon Monitoring Active"
+            val defaultText = if (carPlayOnly) "Monitoring connected vehicle (CarPlay/Android Auto)" else "Monitoring for iBeacons in the background"
+
+            val title = fgConfig?.optString("title")?.takeIf { it.isNotEmpty() } ?: defaultTitle
+            val text = fgConfig?.optString("text")?.takeIf { it.isNotEmpty() } ?: defaultText
             val iconName = fgConfig?.optString("icon")?.takeIf { it.isNotEmpty() }
             val iconResId = iconName?.let { name ->
                 try { context.resources.getIdentifier(name, "drawable", context.packageName).takeIf { it != 0 } }
@@ -921,6 +1097,13 @@ class BeaconForegroundService : Service(), BeaconConsumer {
         if (activeService === this) {
             activeService = null
         }
+        // Stop CarPlay observer first so the LiveData observer doesn't leak
+        // past the service lifecycle. Safe even if it was never started.
+        try {
+            carPlayMonitor?.stop()
+        } catch (_: Throwable) {}
+        carPlayMonitor = null
+        val wasBound = serviceConnected
         serviceConnected = false
         timeoutHandler.removeCallbacksAndMessages(null)
         timeoutRunnables.clear()
@@ -944,7 +1127,11 @@ class BeaconForegroundService : Service(), BeaconConsumer {
         monitoredRegions.forEach {
             try { beaconManager.stopMonitoringBeaconsInRegion(it) } catch (_: RemoteException) {}
         }
-        beaconManager.unbind(this)
+        // Only unbind if we successfully bound — CarPlay-only service
+        // instances skip beaconManager.bind() in onStartCommand.
+        if (wasBound) {
+            try { beaconManager.unbind(this) } catch (_: Throwable) {}
+        }
         super.onDestroy()
     }
 

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

@@ -77,4 +77,12 @@ object BeaconPluginRegistry {
             }
         }
     }
+
+    internal fun dispatchCarPlayConnected(transport: String) {
+        plugins.forEach { it.onCarPlayConnected(transport) }
+    }
+
+    internal fun dispatchCarPlayDisconnected() {
+        plugins.forEach { it.onCarPlayDisconnected() }
+    }
 }

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

@@ -29,11 +29,16 @@ class BootReceiver : BroadcastReceiver() {
                 logMemoryKillDiagnostics(context)
                 if (BeaconForegroundService.isMonitoringActive(context)) {
                     tryStartService(context)
+                } else if (BeaconForegroundService.isCarPlayEnabled(context)) {
+                    // CarPlay-only mode: re-attach the observer so it survives reboot.
+                    tryEnableCarPlay(context)
                 }
             }
             ACTION_RETRY_MONITORING -> {
                 if (BeaconForegroundService.isMonitoringActive(context)) {
                     tryStartService(context)
+                } else if (BeaconForegroundService.isCarPlayEnabled(context)) {
+                    tryEnableCarPlay(context)
                 }
             }
         }
@@ -54,6 +59,16 @@ class BootReceiver : BroadcastReceiver() {
         }
     }
 
+    private fun tryEnableCarPlay(context: Context) {
+        try {
+            BeaconForegroundService.enableCarPlay(context)
+            Log.d(TAG, "BootReceiver: CarPlay-only service started successfully")
+        } catch (e: Exception) {
+            Log.e(TAG, "BootReceiver: Failed to start CarPlay-only service — retrying in ${RETRY_DELAY_MS}ms", e)
+            scheduleRetry(context)
+        }
+    }
+
     private fun scheduleRetry(context: Context) {
         val alarmManager = context.getSystemService(AlarmManager::class.java) ?: return
         val retryIntent = Intent(context, BootReceiver::class.java).apply {

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

@@ -0,0 +1,103 @@
+package expo.modules.beacon
+
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import androidx.car.app.connection.CarConnection
+import androidx.lifecycle.LiveData
+import androidx.lifecycle.Observer
+
+/**
+ * Wraps [CarConnection] LiveData to surface Android Auto / Automotive OS
+ * connection events. No special permissions or Android Auto certification
+ * are required — `CarConnection.type` is read-only state.
+ *
+ * Lifecycle: this monitor uses `observeForever` and therefore must be
+ * explicitly stopped to avoid leaks. The owning module is responsible for
+ * calling [stop] in `OnDestroy`.
+ *
+ * All observer registration / removal happens on the main thread because
+ * [LiveData.observeForever] requires it.
+ */
+internal class CarPlayMonitor(private val context: Context) {
+
+    /** Emit callback signature: (eventName, payload). */
+    fun interface Emit {
+        operator fun invoke(eventName: String, payload: Map<String, Any?>)
+    }
+
+    private val mainHandler = Handler(Looper.getMainLooper())
+    private val liveData: LiveData<Int> = CarConnection(context.applicationContext).type
+    private var observer: Observer<Int>? = null
+    private var emit: Emit? = null
+    @Volatile private var lastConnected: Boolean? = null
+
+    /**
+     * Begin observing connection state. Idempotent — calling twice replaces the
+     * emit callback but does not register a duplicate observer.
+     * Emits `onCarPlayConnected` immediately if already connected.
+     */
+    fun start(emit: Emit) {
+        runOnMain {
+            this.emit = emit
+            if (observer == null) {
+                val obs = Observer<Int> { type -> handleType(type) }
+                observer = obs
+                try {
+                    liveData.observeForever(obs)
+                    Log.d(TAG, "CarPlay monitoring started")
+                } catch (e: Exception) {
+                    Log.w(TAG, "Failed to start CarPlay monitoring: ${e.message}")
+                }
+            }
+        }
+    }
+
+    /** Stop observing connection state and release the emit callback. */
+    fun stop() {
+        runOnMain {
+            observer?.let {
+                try { liveData.removeObserver(it) } catch (_: Exception) {}
+            }
+            observer = null
+            emit = null
+            lastConnected = null
+            Log.d(TAG, "CarPlay monitoring stopped")
+        }
+    }
+
+    private fun handleType(type: Int) {
+        val connected = type != CarConnection.CONNECTION_TYPE_NOT_CONNECTED
+        if (lastConnected == connected) return
+        lastConnected = connected
+        val callback = emit ?: return
+        if (connected) {
+            val transport = when (type) {
+                CarConnection.CONNECTION_TYPE_PROJECTION -> "projection"
+                CarConnection.CONNECTION_TYPE_NATIVE -> "native"
+                else -> "unknown"
+            }
+            callback("onCarPlayConnected", mapOf(
+                "transport" to transport,
+                "timestamp" to System.currentTimeMillis(),
+            ))
+        } else {
+            callback("onCarPlayDisconnected", mapOf(
+                "timestamp" to System.currentTimeMillis(),
+            ))
+        }
+    }
+
+    private fun runOnMain(block: () -> Unit) {
+        if (Looper.myLooper() == Looper.getMainLooper()) {
+            block()
+        } else {
+            mainHandler.post(block)
+        }
+    }
+
+    private companion object {
+        const val TAG = "CarPlayMonitor"
+    }
+}

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

@@ -85,7 +85,7 @@ class ExpoBeaconModule : Module(), BeaconConsumer {
     override fun definition() = ModuleDefinition {
         Name("ExpoBeacon")
 
-        Events("onBeaconEnter", "onBeaconExit", "onBeaconDistance", "onBeaconTimeout", "onBeaconFound", "onEddystoneFound", "onEddystoneEnter", "onEddystoneExit", "onEddystoneDistance", "onEddystoneTimeout", "onBeaconError")
+        Events("onBeaconEnter", "onBeaconExit", "onBeaconDistance", "onBeaconTimeout", "onBeaconFound", "onEddystoneFound", "onEddystoneEnter", "onEddystoneExit", "onEddystoneDistance", "onEddystoneTimeout", "onBeaconError", "onCarPlayConnected", "onCarPlayDisconnected")
 
         AsyncFunction("scanForBeaconsAsync") { uuids: List<String>?, scanDurationMs: Int, promise: Promise ->
             if (scanDurationMs <= 0) {
@@ -376,6 +376,10 @@ class ExpoBeaconModule : Module(), BeaconConsumer {
                 sendEvent("onBeaconError", mapOf("identifier" to "", "code" to "SERVICE_START_FAILED", "message" to "Failed to start monitoring service: ${e.message}"))
                 return@AsyncFunction
             }
+            // Auto-enable CarPlay observation alongside beacon monitoring so
+            // the service captures CarPlay/Android Auto events for the same
+            // lifetime. Users can opt out at any time via stopCarPlayMonitoring().
+            try { BeaconForegroundService.enableCarPlay(ctx) } catch (_: Throwable) {}
             promise.resolve(null)
         }
 
@@ -459,6 +463,11 @@ class ExpoBeaconModule : Module(), BeaconConsumer {
             loggingEnabled = false
         }
 
+        Function("isEventLoggingEnabled") {
+            val ctx = appContext.reactContext ?: return@Function false
+            BeaconEventLogger.isLoggingEnabled(ctx)
+        }
+
         Function("getEventLogs") { options: Map<String, Any?>? ->
             val logger = getOrCreateEventLogger() ?: return@Function emptyList<Map<String, Any?>>()
             val limit = (options?.get("limit") as? Number)?.toInt() ?: 1000
@@ -562,8 +571,51 @@ class ExpoBeaconModule : Module(), BeaconConsumer {
             }
         }
 
+        // MARK: - CarPlay / Android Auto
+
+        AsyncFunction("startCarPlayMonitoring") { promise: Promise ->
+            val ctx = appContext.reactContext
+            if (ctx == null) {
+                promise.reject("NO_CONTEXT", "React context is not available", null)
+                return@AsyncFunction
+            }
+            try {
+                BeaconForegroundService.enableCarPlay(ctx)
+                promise.resolve(null)
+            } catch (e: Throwable) {
+                promise.reject("CARPLAY_START_FAILED", "Failed to start CarPlay monitoring: ${e.message}", e)
+            }
+        }
+
+        AsyncFunction("stopCarPlayMonitoring") { promise: Promise ->
+            val ctx = appContext.reactContext
+            if (ctx == null) {
+                promise.reject("NO_CONTEXT", "React context is not available", null)
+                return@AsyncFunction
+            }
+            try {
+                BeaconForegroundService.disableCarPlay(ctx)
+                promise.resolve(null)
+            } catch (e: Throwable) {
+                promise.reject("CARPLAY_STOP_FAILED", "Failed to stop CarPlay monitoring: ${e.message}", e)
+            }
+        }
+
+        Function("isCarPlayMonitoringEnabled") {
+            val ctx = appContext.reactContext ?: return@Function false
+            BeaconForegroundService.isCarPlayEnabled(ctx)
+        }
+
+        OnCreate {
+            // Register this module instance for best-effort JS-bridge fan-out
+            // of CarPlay events emitted by the foreground service. The service
+            // holds a weak reference; cleared in OnDestroy.
+            BeaconForegroundService.bindModule(this@ExpoBeaconModule)
+        }
+
         OnDestroy {
             with(this@ExpoBeaconModule) {
+                BeaconForegroundService.bindModule(null)
                 unregisterEventReceiver()
                 loggingEnabled = false
                 eventLogger?.close()
@@ -1007,4 +1059,14 @@ class ExpoBeaconModule : Module(), BeaconConsumer {
         val identifier = params["identifier"] as? String
         getOrCreateEventLogger()?.logEvent(eventType, identifier, params)
     }
+
+    /**
+     * Called by [BeaconForegroundService] (via weak reference) when it emits a
+     * CarPlay event from its own observer. Best-effort delivery to the JS bridge
+     * — the service has already handled SQLite logging, API forwarding, and
+     * native plugin dispatch, so this method only needs to relay to JS.
+     */
+    fun forwardCarPlayEventFromService(eventName: String, payload: Map<String, Any?>) {
+        try { sendEvent(eventName, payload) } catch (_: Throwable) { /* JS bridge may be torn down */ }
+    }
 }

package/build/ExpoBeacon.types.d.ts

@@ -254,6 +254,19 @@ export type EddystoneTimeoutEvent = {
     /** Current distance in metres at the time the timeout fired. */
     distance: number;
 };
+/** Transport reported with CarPlay / Android Auto connection events. */
+export type CarPlayTransport = "wired" | "wireless" | "projection" | "native" | "unknown";
+/** Payload fired when the device connects to a CarPlay or Android Auto session. */
+export type CarPlayConnectedEvent = {
+    transport: CarPlayTransport;
+    /** Timestamp in milliseconds since epoch. */
+    timestamp: number;
+};
+/** Payload fired when the device disconnects from a CarPlay or Android Auto session. */
+export type CarPlayDisconnectedEvent = {
+    /** Timestamp in milliseconds since epoch. */
+    timestamp: number;
+};
 /** Payload for native beacon error events (monitoring/ranging failures). */
 export type BeaconErrorEvent = {
     /** Region or constraint identifier, empty string if unavailable. */
@@ -281,6 +294,10 @@ export type ExpoBeaconModuleEvents = {
     onEddystoneTimeout: (params: EddystoneTimeoutEvent) => void;
     /** Fired when a native monitoring or ranging failure occurs (logged to DB and forwarded to JS). */
     onBeaconError: (params: BeaconErrorEvent) => void;
+    /** Fired when the device connects to a CarPlay (iOS) or Android Auto (Android) session. */
+    onCarPlayConnected: (params: CarPlayConnectedEvent) => void;
+    /** Fired when the device disconnects from a CarPlay (iOS) or Android Auto (Android) session. */
+    onCarPlayDisconnected: (params: CarPlayDisconnectedEvent) => void;
 };
 /** Options for filtering event logs. */
 export type EventLogQueryOptions = {