expo-beacon 0.8.1 → 0.8.2

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

@@ -28,9 +28,6 @@ internal class BeaconApiForwarder(private val context: Context) {
         context.getSharedPreferences(API_PREFS, Context.MODE_PRIVATE)
     }
 
-    val isConfigured: Boolean
-        get() = prefs.getString(API_URL_KEY, null)?.isNotEmpty() == true
-
     fun configure(url: String, apiKey: String?, id: String? = null) {
         prefs.edit().apply {
             putString(API_URL_KEY, url)

package/ios/BeaconApiForwarder.swift

@@ -14,11 +14,6 @@ final class BeaconApiForwarder {
     private let defaults: UserDefaults
     private let session: URLSession
 
-    var isConfigured: Bool {
-        guard let url = defaults.string(forKey: API_URL_KEY) else { return false }
-        return !url.isEmpty
-    }
-
     init(defaults: UserDefaults? = nil) {
         self.defaults = defaults ?? (UserDefaults(suiteName: "expo.modules.beacon") ?? .standard)
         let config = URLSessionConfiguration.default

package/ios/BeaconCarPlaySceneDelegate.swift

@@ -0,0 +1,78 @@
+import Foundation
+import UIKit
+import CarPlay
+import os.log
+
+/// CarPlay scene delegate used when the consumer app is provisioned with the
+/// `com.apple.developer.carplay-driving-task` entitlement (driver / fleet
+/// workflow apps).
+///
+/// Wiring is performed by the config plugin (`carplayDrivingTask: true`):
+///   1. The entitlement is added to the app's `*.entitlements`.
+///   2. `Info.plist` `UIApplicationSceneManifest` declares a
+///      `CPTemplateApplicationSceneSessionRoleApplication` configuration with
+///      `UISceneDelegateClassName = "ExpoBeacon.BeaconCarPlaySceneDelegate"`.
+///
+/// When CarPlay attaches, iOS launches (or wakes) the app and instantiates this
+/// delegate. We notify the shared `CarPlayMonitor` which produces an
+/// `onCarPlayConnected` event through the standard pipeline (JS bridge,
+/// SQLite log, HTTP forwarder, lifecycle plugin registry).
+///
+/// Apple requires that a CarPlay-entitled app present a meaningful CarPlay UI.
+/// We install a minimal `CPInformationTemplate` titled "Driver tracking active"
+/// as the root template so the app passes review without forcing every consumer
+/// to build a full CarPlay UX. Consumers that need richer UI can subclass this
+/// delegate (or replace the scene class) and override `makeRootTemplate()`.
+///
+/// IMPORTANT: This class must be accessible to the Objective-C runtime so that
+/// `Info.plist`'s `UISceneDelegateClassName` string can resolve via
+/// `NSClassFromString`. Hence `@objc(...)` and `: NSObject`.
+@objc(BeaconCarPlaySceneDelegate)
+open class BeaconCarPlaySceneDelegate: NSObject, CPTemplateApplicationSceneDelegate {
+
+    private static let log = OSLog(subsystem: "expo.modules.beacon", category: "CarPlayScene")
+
+    private var interfaceController: CPInterfaceController?
+
+    public override init() {
+        super.init()
+    }
+
+    // MARK: - CPTemplateApplicationSceneDelegate
+
+    public func templateApplicationScene(
+        _ templateApplicationScene: CPTemplateApplicationScene,
+        didConnect interfaceController: CPInterfaceController
+    ) {
+        os_log("CarPlay templateApplicationScene didConnect", log: Self.log, type: .info)
+        self.interfaceController = interfaceController
+        let template = makeRootTemplate()
+        interfaceController.setRootTemplate(template, animated: false, completion: nil)
+        CarPlayMonitor.shared.notifyEntitledConnect()
+    }
+
+    public func templateApplicationScene(
+        _ templateApplicationScene: CPTemplateApplicationScene,
+        didDisconnectInterfaceController interfaceController: CPInterfaceController
+    ) {
+        os_log("CarPlay templateApplicationScene didDisconnect", log: Self.log, type: .info)
+        self.interfaceController = nil
+        CarPlayMonitor.shared.notifyEntitledDisconnect()
+    }
+
+    // MARK: - Override hooks
+
+    /// Build the root template shown when CarPlay attaches. Override in a
+    /// consumer subclass to install a richer template (e.g. `CPListTemplate`,
+    /// `CPMapTemplate`, `CPNowPlayingTemplate`). Default is a minimal
+    /// `CPInformationTemplate` confirming the app is tracking.
+    open func makeRootTemplate() -> CPTemplate {
+        let item = CPInformationItem(title: "Status", detail: "Tracking active")
+        return CPInformationTemplate(
+            title: "Driver tracking",
+            layout: .leading,
+            items: [item],
+            actions: []
+        )
+    }
+}

package/ios/BluetoothDelegate.swift

@@ -0,0 +1,43 @@
+import CoreBluetooth
+
+// MARK: - CBCentralManagerDelegate (Eddystone BLE scanning)
+
+internal final class BluetoothDelegate: NSObject, CBCentralManagerDelegate {
+    private weak var module: ExpoBeaconModule?
+
+    init(module: ExpoBeaconModule) {
+        self.module = module
+    }
+
+    func centralManagerDidUpdateState(_ central: CBCentralManager) {
+        switch central.state {
+        case .poweredOn:
+            module?.ensureBleScanRunning()
+        case .unauthorized:
+            print("[ExpoBeacon] Bluetooth authorization denied — Eddystone scanning/monitoring unavailable. " +
+                  "Ensure NSBluetoothAlwaysUsageDescription is set in Info.plist.")
+            module?.handleBluetoothStateError(code: "BLUETOOTH_UNAUTHORIZED", message: "Bluetooth authorization denied — Eddystone scanning/monitoring unavailable")
+            module?.eddystoneScanPromise?.reject("BLUETOOTH_UNAUTHORIZED", "Bluetooth permission denied")
+            module?.eddystoneScanPromise = nil
+        case .poweredOff:
+            print("[ExpoBeacon] Bluetooth is powered off — Eddystone scanning/monitoring unavailable.")
+            module?.handleBluetoothStateError(code: "BLUETOOTH_OFF", message: "Bluetooth is powered off — Eddystone scanning/monitoring unavailable")
+            module?.eddystoneScanPromise?.reject("BLUETOOTH_OFF", "Bluetooth is powered off")
+            module?.eddystoneScanPromise = nil
+        default:
+            break
+        }
+    }
+
+    func centralManager(_ central: CBCentralManager,
+                         didDiscover peripheral: CBPeripheral,
+                         advertisementData: [String: Any],
+                         rssi RSSI: NSNumber) {
+        module?.handleEddystoneDiscovery(advertisementData: advertisementData, rssi: RSSI)
+    }
+
+    func centralManager(_ central: CBCentralManager, willRestoreState dict: [String: Any]) {
+        // State restoration: CBCentralManager was recreated by iOS after app was killed.
+        // Scanning will be re-started in centralManagerDidUpdateState when state is .poweredOn.
+    }
+}

package/ios/CarPlayMonitor.swift

@@ -23,6 +23,12 @@ final class CarPlayMonitor {
     private var observer: NSObjectProtocol?
     private var emit: Emit?
     private var isConnected: Bool = false
+    /// When `true`, an authoritative source (CarPlay scene delegate, granted via the
+    /// `com.apple.developer.carplay-driving-task` entitlement) is providing
+    /// connect/disconnect events. The audio-session observer becomes a passive
+    /// secondary signal only — it will not emit events, to avoid duplicate
+    /// connect/disconnect notifications.
+    private var isEntitledMode: Bool = false
 
     private init() {}
 
@@ -39,8 +45,8 @@ final class CarPlayMonitor {
                     forName: AVAudioSession.routeChangeNotification,
                     object: nil,
                     queue: .main
-                ) { [weak self] _ in
-                    self?.handleRouteChange()
+                ) { [weak self] note in
+                    self?.handleRouteChange(notification: note)
                 }
                 os_log("CarPlay monitoring started", log: self.log, type: .info)
             }
@@ -74,21 +80,85 @@ final class CarPlayMonitor {
     /// was suspended and `AVAudioSession.routeChangeNotification` was not delivered.
     func resyncIfNeeded() {
         queue.async { [weak self] in
-            self?.handleRouteChange()
+            // Snapshot reads (initial start, region wake, explicit resync) are
+            // trusted: they reflect the actual current route, not a transient
+            // category/configuration change. Pass `nil` notification to bypass
+            // the route-change-reason filter.
+            self?.handleRouteChange(notification: nil)
         }
     }
 
-    /// Whether `start(emit:)` has been called and `stop()` has not.
-    /// Use to decide whether to skip a redundant start during auto-start logic.
-    var isObserving: Bool {
-        // Synchronous read from main queue is safe — `observer` is only mutated on `queue`.
+    // MARK: - Entitled (Driving Task) source
+
+    /// Called by `BeaconCarPlaySceneDelegate.templateApplicationScene(_:didConnect:)`.
+    /// Marks the entitled path as the authoritative source and emits an immediate
+    /// `onCarPlayConnected` event (if not already connected from this source).
+    /// Subsequent route-change notifications from `AVAudioSession` are suppressed
+    /// for emission purposes to prevent duplicate events.
+    func notifyEntitledConnect(transport: String = "carplay-scene") {
+        queue.async { [weak self] in
+            guard let self = self else { return }
+            self.isEntitledMode = true
+            os_log("CarPlay scene connected (entitled source)", log: self.log, type: .info)
+            if !self.isConnected {
+                self.isConnected = true
+                self.emitConnected(transport: transport)
+            }
+        }
+    }
+
+    /// Called by `BeaconCarPlaySceneDelegate.templateApplicationScene(_:didDisconnect:)`.
+    /// Emits `onCarPlayDisconnected` and keeps the entitled-mode flag set so
+    /// subsequent audio-session events remain suppressed (the scene delegate is
+    /// the source of truth for the lifetime of the process).
+    func notifyEntitledDisconnect() {
+        queue.async { [weak self] in
+            guard let self = self else { return }
+            os_log("CarPlay scene disconnected (entitled source)", log: self.log, type: .info)
+            if self.isConnected {
+                self.isConnected = false
+                self.emitDisconnected()
+            }
+        }
+    }
+
+    /// Whether an entitled CarPlay scene source has notified us at least once.
+    /// Consumers (e.g. SLC/Visit auto-start logic) can skip cheap fallbacks
+    /// when the entitled real-time path is active.
+    var isUsingEntitledSource: Bool {
         if Thread.isMainThread {
-            return observer != nil
+            return isEntitledMode
         }
-        return queue.sync { observer != nil }
+        return queue.sync { isEntitledMode }
     }
 
-    private func handleRouteChange() {
+    /// Process a route change. When invoked from a system notification the
+    /// reason is checked: only `.newDeviceAvailable` and `.oldDeviceUnavailable`
+    /// indicate a real device connect/disconnect. Other reasons (category change,
+    /// configuration change, override, etc.) are filtered to avoid spurious
+    /// disconnect events when the app suspends/resumes and iOS re-evaluates
+    /// the audio session category without the physical CarPlay link changing.
+    /// When `notification` is nil (initial start, explicit resync), the snapshot
+    /// is always trusted.
+    private func handleRouteChange(notification: Notification?) {
+        if let userInfo = notification?.userInfo,
+           let reasonRaw = userInfo[AVAudioSessionRouteChangeReasonKey] as? UInt,
+           let reason = AVAudioSession.RouteChangeReason(rawValue: reasonRaw) {
+            switch reason {
+            case .newDeviceAvailable, .oldDeviceUnavailable:
+                break // real device change — proceed
+            default:
+                // Category/override/configuration changes etc. don't represent
+                // a CarPlay connect/disconnect. Skip to avoid spurious events.
+                return
+            }
+        }
+        // When an entitled CarPlay scene source is active it is authoritative.
+        // The audio-session signal is kept as a redundant secondary check but
+        // must NOT emit events — the scene delegate already did, or will.
+        if isEntitledMode {
+            return
+        }
         let (connected, transport) = Self.currentCarPlayState()
         if connected == isConnected { return }
         isConnected = connected

package/ios/ExpoBeacon.podspec

@@ -19,8 +19,11 @@ Pod::Spec.new do |s|
 
   s.dependency 'ExpoModulesCore'
 
-  # Required system frameworks for iBeacon monitoring + wildcard BLE scanning
-  s.frameworks = 'CoreLocation', 'CoreBluetooth', 'UserNotifications'
+  # Required system frameworks for iBeacon monitoring + wildcard BLE scanning.
+  # CarPlay is used by `BeaconCarPlaySceneDelegate` for the optional "Driving
+  # Task" entitlement integration; linking is harmless when the entitlement is
+  # not granted.
+  s.frameworks = 'CoreLocation', 'CoreBluetooth', 'UserNotifications', 'CarPlay', 'AVFoundation'
 
   # Swift/Objective-C compatibility
   s.pod_target_xcconfig = {

package/ios/ExpoBeaconConstants.swift

@@ -0,0 +1,41 @@
+import Foundation
+
+// MARK: - UserDefaults keys
+
+internal let PAIRED_BEACONS_KEY = "expo.beacon.paired"
+internal let PAIRED_EDDYSTONES_KEY = "expo.beacon.paired_eddystones"
+internal let IS_MONITORING_KEY = "expo.beacon.is_monitoring"
+internal let MAX_DISTANCE_KEY = "expo.beacon.max_distance"
+internal let EXIT_DISTANCE_KEY = "expo.beacon.exit_distance"
+internal let NOTIFICATION_CONFIG_KEY = "expo.beacon.notification_config"
+internal let EVENT_LOGGING_ENABLED_KEY = "expo.beacon.event_logging_enabled"
+internal let MIN_RSSI_KEY = "expo.beacon.min_rssi"
+internal let EVENT_LEVEL_KEY = "expo.beacon.event_level"
+internal let EXIT_TIMEOUT_SECONDS_KEY = "expo.beacon.exit_timeout_seconds"
+internal let CARPLAY_MONITORING_ENABLED_KEY = "expo.beacon.carplay_monitoring_enabled"
+
+// MARK: - Tuning thresholds
+
+/// Default minimum RSSI (dBm) below which beacon readings are discarded as unreliable.
+internal let DEFAULT_MIN_RSSI: Int = -85
+/// Default seconds of silence after last beacon sighting before a disappearance-based exit fires.
+internal let DEFAULT_EXIT_TIMEOUT_SECONDS: TimeInterval = 300.0
+
+/// Number of consecutive in-range readings required before an enter event is emitted.
+/// IMPORTANT: Keep in sync with BeaconConstants.kt (Android).
+internal let ENTER_HYSTERESIS_COUNT = 1
+/// Number of consecutive out-of-range readings required before an exit event is emitted.
+/// IMPORTANT: Keep in sync with BeaconConstants.kt (Android).
+internal let EXIT_HYSTERESIS_COUNT = 3
+
+/// Eddystone monitoring timer interval in seconds.
+internal let EDDYSTONE_MONITORING_TICK_INTERVAL: TimeInterval = 2.0
+/// Maximum age (in seconds) before a beacon is considered "not recently seen".
+/// Set high enough to tolerate iOS background CoreBluetooth throttling which
+/// can cause 10-12 s gaps between Eddystone advertisements.
+internal let EDDYSTONE_RECENTLY_SEEN_THRESHOLD: TimeInterval = 15.0
+/// Minimum interval between consecutive distance event emissions per identifier.
+internal let DISTANCE_EVENT_THROTTLE_INTERVAL: TimeInterval = 1.0
+/// Seconds of no valid BLE readings before starting the timeout countdown.
+/// Acts as a safety net when ranging cycles stop entirely (e.g. Doze mode).
+internal let DISTANCE_INACTIVITY_SECONDS: TimeInterval = 60.0

package/ios/ExpoBeaconModule+CarPlay.swift

@@ -0,0 +1,49 @@
+import CoreLocation
+
+extension ExpoBeaconModule {
+    /// Starts the shared `CarPlayMonitor` and routes its events through the
+    /// standard `sendLoggedEvent` pipeline (JS bridge + SQLite + API forwarder
+    /// + lifecycle plugin registry). Idempotent — safe to call multiple times
+    /// (see `CarPlayMonitor.start(emit:)` semantics).
+    func startCarPlayMonitoringInternal() {
+        CarPlayMonitor.shared.start { [weak self] eventName, payload in
+            self?.sendLoggedEvent(eventName, payload)
+        }
+        // Tier 2 fallback: subscribe to background-wake signals so suspended
+        // apps still notice CarPlay route changes that happened off-process.
+        // Skipped when the entitled CarPlay scene path is providing real-time
+        // events — that source keeps the app awake for the entire CarPlay
+        // session and renders SLC/Visit redundant.
+        if !CarPlayMonitor.shared.isUsingEntitledSource {
+            startCarPlayBackgroundWakes()
+        }
+    }
+
+    /// Start Significant Location Change + Visit monitoring as background-wake
+    /// hooks for CarPlay state reconciliation. Both are extremely low cost
+    /// (no continuous GPS) and reuse the existing `CLLocationManager` /
+    /// `LocationDelegate`. Idempotent.
+    func startCarPlayBackgroundWakes() {
+        if !CLLocationManager.significantLocationChangeMonitoringAvailable() {
+            return
+        }
+        locationManager.startMonitoringSignificantLocationChanges()
+        locationManager.startMonitoringVisits()
+    }
+
+    /// Stop the SLC + Visit hooks. Called from `stopCarPlayMonitoring`.
+    func stopCarPlayBackgroundWakes() {
+        locationManager.stopMonitoringSignificantLocationChanges()
+        locationManager.stopMonitoringVisits()
+    }
+
+    /// Forwarded from `LocationDelegate` for SLC and Visit callbacks.
+    /// Cheap reconciliation: just snapshot the audio route. The entitled
+    /// scene-delegate path (when active) takes precedence in `CarPlayMonitor`
+    /// itself.
+    func handleBackgroundWakeForCarPlay() {
+        if defaults.bool(forKey: CARPLAY_MONITORING_ENABLED_KEY) {
+            CarPlayMonitor.shared.resyncIfNeeded()
+        }
+    }
+}