react-native-bg-geolocation 0.2.0

package/ios/locationpush/BGLocationPushService.swift

@@ -0,0 +1,161 @@
+//
+//  BGLocationPushService.swift
+//
+//  The principal class of the iOS Location Push Service Extension
+//  (CLLocationPushServiceExtension, iOS 15+).
+//
+//  ── WHAT THIS IS ──────────────────────────────────────────────────────────
+//  When your server sends an APNs push (apns-push-type: location, apns-topic:
+//  <bundle-id>.location-query) to the device's location-push token, iOS launches
+//  THIS extension in a separate, short-lived process — even if the host app has
+//  been force-quit. The extension grabs one location fix and ships it to your
+//  server, then signals completion and is torn down.
+//
+//  ── DELIVERY ──────────────────────────────────────────────────────────────
+//  The push payload carries a `location-query` id. Its presence means "capture
+//  and report a location now". We:
+//    1. requestLocation() — one GPS fix.
+//    2. Try Socket.IO (`location:update`) first, if socket config is present.
+//    3. Fall back to REST POST to the configured `url`.
+//  The captured location-query id is echoed back so the server can correlate.
+//
+//  ── REQUIREMENTS ──────────────────────────────────────────────────────────
+//    • Apple-approved `com.apple.developer.location.push` entitlement.
+//    • App Group shared with the host app (see BGLocationPushShared).
+//    • Host app calls startMonitoringLocationPushes + ships the token to server.
+//    • "Always" location authorization.
+//
+//  ~30s wall-clock budget. The socket attempt is tightly timed so REST always
+//  has room to run.
+//
+
+import CoreLocation
+import Foundation
+import os.log
+
+@available(iOS 15.0, *)
+@objc(BGLocationPushService)
+public final class BGLocationPushService: NSObject, CLLocationPushServiceExtension {
+
+    private var completion: (() -> Void)?
+    private var manager: CLLocationManager?
+    private var fetcher: BGLocationPushFetcher?
+
+    public override init() {
+        super.init()
+    }
+
+    public func didReceiveLocationPushPayload(
+        _ payload: [String: Any],
+        completion: @escaping () -> Void
+    ) {
+        BGLocationPushLog.log("didReceiveLocationPushPayload: \(payload)")
+        self.completion = completion
+
+        let queryId = Self.extractLocationQueryId(from: payload)
+        guard let queryId = queryId else {
+            // No location-query id → nothing to report. Finish cleanly.
+            BGLocationPushLog.log("no location-query id in payload — ignoring")
+            finish()
+            return
+        }
+        BGLocationPushLog.log("location-query id = \(queryId)")
+
+        let fetcher = BGLocationPushFetcher(queryId: queryId) { [weak self] in
+            self?.finish()
+        }
+        self.fetcher = fetcher
+
+        let mgr = CLLocationManager()
+        mgr.delegate = fetcher
+        mgr.desiredAccuracy = kCLLocationAccuracyBest
+        self.manager = mgr
+        mgr.requestLocation() // one-shot
+    }
+
+    public func serviceExtensionWillTerminate() {
+        BGLocationPushLog.log("serviceExtensionWillTerminate — flushing")
+        fetcher?.flushPendingIfNeeded()
+        finish()
+    }
+
+    private func finish() {
+        guard let completion = completion else { return }
+        self.completion = nil
+        self.manager = nil
+        self.fetcher = nil
+        completion()
+    }
+
+    /// Pull the location-query id out of the push payload. Accepts several key
+    /// spellings so it survives server-side naming differences.
+    static func extractLocationQueryId(from payload: [String: Any]) -> String? {
+        let candidates = ["location-query", "locationQuery", "location_query",
+                          "locationQueryId", "queryId", "query-id"]
+        // Top level, then nested under "aps".
+        var scopes: [[String: Any]] = [payload]
+        if let aps = payload["aps"] as? [String: Any] { scopes.append(aps) }
+        for scope in scopes {
+            for key in candidates {
+                if let value = scope[key] {
+                    if let s = value as? String, !s.isEmpty { return s }
+                    if let n = value as? NSNumber { return n.stringValue }
+                }
+            }
+        }
+        return nil
+    }
+}
+
+// MARK: - Location fetcher + delivery
+
+@available(iOS 15.0, *)
+final class BGLocationPushFetcher: NSObject, CLLocationManagerDelegate {
+
+    private let queryId: String
+    private let completion: () -> Void
+    private var didComplete = false
+
+    init(queryId: String, completion: @escaping () -> Void) {
+        self.queryId = queryId
+        self.completion = completion
+    }
+
+    func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
+        guard !didComplete, let location = locations.last else { return }
+        didComplete = true
+        BGLocationPushLog.log("got location \(location.coordinate.latitude),\(location.coordinate.longitude)")
+        // Delegate to the shared native deliverer (socket → REST), so the
+        // extension and the in-app handler use identical delivery logic.
+        BGLocationPushDeliverer.deliver(
+            latitude: location.coordinate.latitude,
+            longitude: location.coordinate.longitude,
+            accuracy: max(location.horizontalAccuracy, 0),
+            speed: location.speed,
+            heading: location.course,
+            altitude: location.altitude,
+            timestampISO: Self.iso8601(location.timestamp),
+            queryId: queryId
+        ) { [weak self] _ in
+            self?.completion()
+        }
+    }
+
+    func locationManager(_ manager: CLLocationManager, didFailWithError error: Error) {
+        guard !didComplete else { return }
+        didComplete = true
+        BGLocationPushLog.log("CLLocationManager failed: \(error.localizedDescription)")
+        completion()
+    }
+
+    func flushPendingIfNeeded() {
+        guard !didComplete else { return }
+        BGLocationPushLog.log("terminated before location fix arrived")
+    }
+
+    private static func iso8601(_ date: Date) -> String {
+        let formatter = ISO8601DateFormatter()
+        formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        return formatter.string(from: date)
+    }
+}

package/ios/locationpush/BGLocationPushShared.swift

@@ -0,0 +1,98 @@
+//
+//  BGLocationPushShared.swift
+//
+//  Constants shared between the host app (BGLocationManager engine) and the
+//  CLLocationPushServiceExtension. Because the extension runs in a SEPARATE
+//  process, the only channel between them is an App Group shared UserDefaults
+//  suite. Both sides MUST agree on the suite name and the keys below.
+//
+//  This file is compiled into BOTH:
+//    1. The `BgGeolocation` pod (so BGLocationManager can WRITE the config)
+//    2. The Location Push Service Extension target (so it can READ the config)
+//
+//  ── HOST-APP INTEGRATION ──────────────────────────────────────────────────
+//  Consumers of this package must:
+//    • Set `BGLocationPushAppGroupIdentifier` in BOTH the host app and extension
+//      Info.plist files to the same App Group identifier.
+//    • Add that App Group to BOTH the main app target and the extension target.
+//
+
+import Foundation
+import os.log
+
+// Shared logger for all location-push code (extension + in-app). Compiled into
+// both the pod and the extension target via BGLocationPushShared.swift.
+enum BGLocationPushLog {
+    private static let logger = OSLog(subsystem: "com.bggeolocation.locationpush", category: "LocationPush")
+    static func log(_ message: String) {
+        os_log("%{public}@", log: logger, type: .info, message)
+        NSLog("[BGGEO][PushExt] \(message)")
+    }
+}
+
+@objc public final class BGLocationPushShared: NSObject {
+
+    /// Safe fallback used by the public example. Production apps should set
+    /// `BGLocationPushAppGroupIdentifier` in both target Info.plist files.
+    public static let defaultAppGroupIdentifier = "group.com.example.bggeolocation"
+    public static let infoPlistAppGroupKey = "BGLocationPushAppGroupIdentifier"
+
+    // UserDefaults keys written by the host app and read by the extension.
+    public static let keyAppGroup       = "BGLocationPush_appGroup"
+    public static let keyUrl            = "BGLocationPush_url"
+    public static let keyMethod         = "BGLocationPush_method"
+    public static let keyHeaders        = "BGLocationPush_headers"
+    public static let keyParams         = "BGLocationPush_params"
+    public static let keyExtras         = "BGLocationPush_extras"
+    public static let keyRootProperty   = "BGLocationPush_rootProperty"
+    public static let keyAuthorization  = "BGLocationPush_authorization"
+    public static let keyAccessToken    = "BGLocationPush_accessToken"
+
+    // Socket delivery (preferred channel for the extension). Written by the host
+    // app via BackgroundGeolocation.setLocationPushConfig({...}). When socketUrl
+    // is present the extension tries Socket.IO first, then falls back to REST.
+    public static let keySocketUrl       = "BGLocationPush_socketUrl"
+    public static let keySocketPath      = "BGLocationPush_socketPath"
+    public static let keySocketEvent     = "BGLocationPush_socketEvent"
+    public static let keySocketAuthToken = "BGLocationPush_socketAuthToken"
+    public static let keySocketTimeout   = "BGLocationPush_socketTimeout"
+
+    // REST fallback used when the socket fails: POST {latitude, longitude,
+    // fcmToken, userCurrentTime} to fallbackUrl.
+    public static let keyFallbackUrl     = "BGLocationPush_fallbackUrl"
+    public static let keyFcmToken        = "BGLocationPush_fcmToken"
+
+    // Host-defined payload shape for the upload (socket + REST fallback). A dict
+    // whose values may contain tokens like "{latitude}", "{fcmToken}",
+    // "{userCurrentTime}" that the deliverer substitutes with live values. When
+    // absent, the deliverer uses its built-in default payload.
+    public static let keyPayloadTemplate = "BGLocationPush_payloadTemplate"
+
+    // The location push token (hex) the host app obtained from
+    // `startMonitoringLocationPushesWithCompletion`. Stored in BOTH the standard
+    // and the shared suite so JS can read it via getLocationPushToken().
+    public static let keyLocationPushToken = "BGLocationManager_locationPushToken"
+
+    /// Resolve the App Group identifier. Allows the host app to override the
+    /// default at runtime by writing `keyAppGroup` into standard UserDefaults
+    /// BEFORE the engine syncs config (rarely needed — the default is fine for
+    /// most apps).
+    @objc public static func resolveAppGroupIdentifier() -> String {
+        if let override = UserDefaults.standard.string(forKey: keyAppGroup),
+           !override.isEmpty {
+            return override
+        }
+        if let configured = Bundle.main.object(
+            forInfoDictionaryKey: infoPlistAppGroupKey
+        ) as? String, !configured.isEmpty {
+            return configured
+        }
+        return defaultAppGroupIdentifier
+    }
+
+    /// The shared UserDefaults suite, or nil if the App Group is not configured
+    /// (entitlement missing). Callers must handle nil gracefully.
+    @objc public static func sharedDefaults() -> UserDefaults? {
+        UserDefaults(suiteName: resolveAppGroupIdentifier())
+    }
+}

package/ios/locationpush/BGLocationPushSocketClient.swift

@@ -0,0 +1,198 @@
+//
+//  BGLocationPushSocketClient.swift
+//
+//  A minimal Socket.IO v4 (Engine.IO v4) client implemented directly on
+//  URLSessionWebSocketTask. The Location Push Service Extension runs in a tiny,
+//  RN-less Swift process, so it cannot load `socket.io-client` (a JS library).
+//  This emits a single `location:update` event with an ack, matching the app's
+//  JS socket protocol, then tears the connection down.
+//
+//  Protocol (Socket.IO v4 over a single WebSocket):
+//    • Connect to  wss://<host><path>/?EIO=4&transport=websocket
+//    • Server → "0{...}"            Engine.IO OPEN (we ignore the body)
+//    • Client → "40{auth-json}"     Socket.IO CONNECT to namespace "/" with auth
+//    • Server → "40{\"sid\":...}"   CONNECT ack (success) | "44{...}" connect_error
+//    • Client → "420[\"event\",payload]"  MESSAGE + EVENT with ack id 0
+//    • Server → "430[ackPayload]"   ack for id 0
+//    • Engine.IO PING "2" → we reply PONG "3"
+//
+//  Everything is bounded by `timeout` so we never blow the extension budget.
+//  Extension-safe: only Foundation + URLSession.
+//
+
+import Foundation
+
+@available(iOS 15.0, *)
+final class BGLocationPushSocketClient: NSObject {
+
+    struct Config {
+        let url: URL            // base, e.g. https://host  (ws/http both accepted)
+        let path: String        // socket.io path, e.g. /socket/location
+        let event: String       // event name, e.g. location:update
+        let authToken: String?  // sent in the CONNECT auth payload as {"token": ...}
+        let timeout: TimeInterval
+    }
+
+    private let config: Config
+    private var task: URLSessionWebSocketTask?
+    private var session: URLSession?
+    private var completion: ((Bool) -> Void)?
+    private var didFinish = false
+    private var connectAcked = false
+    private var payload: [String: Any] = [:]
+    private var timeoutWorkItem: DispatchWorkItem?
+
+    init(config: Config) {
+        self.config = config
+    }
+
+    /// Emit one event with `payload` and resolve `true` once the server acks it,
+    /// or `false` on any failure / timeout.
+    func emit(_ payload: [String: Any], completion: @escaping (Bool) -> Void) {
+        self.payload = payload
+        self.completion = completion
+
+        guard let wsURL = makeWebSocketURL() else {
+            finish(false)
+            return
+        }
+
+        let session = URLSession(configuration: .ephemeral)
+        self.session = session
+        let task = session.webSocketTask(with: wsURL)
+        self.task = task
+
+        let deadline = DispatchWorkItem { [weak self] in
+            BGLocationPushLog.log("socket timed out")
+            self?.finish(false)
+        }
+        timeoutWorkItem = deadline
+        DispatchQueue.global().asyncAfter(deadline: .now() + config.timeout, execute: deadline)
+
+        task.resume()
+        receiveLoop()
+    }
+
+    // MARK: - URL
+
+    private func makeWebSocketURL() -> URL? {
+        guard var components = URLComponents(url: config.url, resolvingAgainstBaseURL: false) else {
+            return nil
+        }
+        switch components.scheme {
+        case "https", "wss": components.scheme = "wss"
+        default: components.scheme = "ws"
+        }
+        // socket.io expects the engine.io handshake at <path>/ with these query items.
+        var path = config.path
+        if !path.hasPrefix("/") { path = "/" + path }
+        if !path.hasSuffix("/") { path += "/" }
+        components.path = path
+        components.queryItems = [
+            URLQueryItem(name: "EIO", value: "4"),
+            URLQueryItem(name: "transport", value: "websocket")
+        ]
+        return components.url
+    }
+
+    // MARK: - Receive loop
+
+    private func receiveLoop() {
+        task?.receive { [weak self] result in
+            guard let self = self, !self.didFinish else { return }
+            switch result {
+            case .failure(let error):
+                BGLocationPushLog.log("socket receive error: \(error.localizedDescription)")
+                self.finish(false)
+            case .success(let message):
+                switch message {
+                case .string(let text): self.handle(text)
+                case .data(let data): self.handle(String(decoding: data, as: UTF8.self))
+                @unknown default: break
+                }
+                if !self.didFinish { self.receiveLoop() }
+            }
+        }
+    }
+
+    private func handle(_ text: String) {
+        guard let first = text.first else { return }
+        switch first {
+        case "0": // Engine.IO OPEN → send Socket.IO CONNECT with auth
+            sendConnect()
+        case "2": // Engine.IO PING → PONG
+            send("3")
+        case "4": // Engine.IO MESSAGE → inspect Socket.IO packet type (2nd char)
+            handleSocketIO(text)
+        default:
+            break
+        }
+    }
+
+    private func handleSocketIO(_ text: String) {
+        // text[0] == "4" (MESSAGE). text[1] == Socket.IO packet type.
+        let idx = text.index(text.startIndex, offsetBy: 1)
+        guard idx < text.endIndex else { return }
+        let type = text[idx]
+        switch type {
+        case "0": // CONNECT success → now emit the event
+            connectAcked = true
+            sendEvent()
+        case "3": // ACK for our emit → success
+            BGLocationPushLog.log("socket ack received")
+            finish(true)
+        case "4": // CONNECT_ERROR
+            BGLocationPushLog.log("socket connect_error: \(text)")
+            finish(false)
+        default:
+            break
+        }
+    }
+
+    // MARK: - Send
+
+    private func sendConnect() {
+        var frame = "40"
+        if let token = config.authToken, !token.isEmpty,
+           let data = try? JSONSerialization.data(withJSONObject: ["token": token]),
+           let json = String(data: data, encoding: .utf8) {
+            frame += json
+        }
+        send(frame)
+    }
+
+    private func sendEvent() {
+        guard let data = try? JSONSerialization.data(withJSONObject: [config.event, payload]),
+              let json = String(data: data, encoding: .utf8) else {
+            finish(false)
+            return
+        }
+        // "42" = MESSAGE+EVENT, "0" = ack id we expect echoed back as "430[...]".
+        send("420" + json)
+    }
+
+    private func send(_ frame: String) {
+        task?.send(.string(frame)) { [weak self] error in
+            if let error = error {
+                BGLocationPushLog.log("socket send error: \(error.localizedDescription)")
+                self?.finish(false)
+            }
+        }
+    }
+
+    // MARK: - Teardown
+
+    private func finish(_ success: Bool) {
+        guard !didFinish else { return }
+        didFinish = true
+        timeoutWorkItem?.cancel()
+        timeoutWorkItem = nil
+        task?.cancel(with: .goingAway, reason: nil)
+        task = nil
+        session?.invalidateAndCancel()
+        session = nil
+        let cb = completion
+        completion = nil
+        cb?(success)
+    }
+}

package/lib/module/NativeBgGeolocation.js

@@ -0,0 +1,5 @@
+"use strict";
+
+import { TurboModuleRegistry } from 'react-native';
+export default TurboModuleRegistry.getEnforcing('BgGeolocation');
+//# sourceMappingURL=NativeBgGeolocation.js.map

package/lib/module/NativeBgGeolocation.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["TurboModuleRegistry","getEnforcing"],"sourceRoot":"../../src","sources":["NativeBgGeolocation.ts"],"mappings":";;AAAA,SAASA,mBAAmB,QAA0B,cAAc;AA2OpE,eAAeA,mBAAmB,CAACC,YAAY,CAAO,eAAe,CAAC","ignoreList":[]}

package/lib/module/events.js

@@ -0,0 +1,20 @@
+"use strict";
+
+export const BOOT = 'boot';
+export const TERMINATE = 'terminate';
+export const LOCATION = 'location';
+export const HTTP = 'http';
+export const MOTIONCHANGE = 'motionchange';
+export const PROVIDERCHANGE = 'providerchange';
+export const HEARTBEAT = 'heartbeat';
+export const ACTIVITYCHANGE = 'activitychange';
+export const GEOFENCE = 'geofence';
+export const GEOFENCESCHANGE = 'geofenceschange';
+export const SCHEDULE = 'schedule';
+export const CONNECTIVITYCHANGE = 'connectivitychange';
+export const ENABLEDCHANGE = 'enabledchange';
+export const POWERSAVECHANGE = 'powersavechange';
+export const NOTIFICATIONACTION = 'notificationaction';
+export const AUTHORIZATION = 'authorization';
+export const LOCATIONPUSH = 'locationpush';
+//# sourceMappingURL=events.js.map

package/lib/module/events.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["BOOT","TERMINATE","LOCATION","HTTP","MOTIONCHANGE","PROVIDERCHANGE","HEARTBEAT","ACTIVITYCHANGE","GEOFENCE","GEOFENCESCHANGE","SCHEDULE","CONNECTIVITYCHANGE","ENABLEDCHANGE","POWERSAVECHANGE","NOTIFICATIONACTION","AUTHORIZATION","LOCATIONPUSH"],"sourceRoot":"../../src","sources":["events.ts"],"mappings":";;AAAA,OAAO,MAAMA,IAAI,GAAG,MAAM;AAC1B,OAAO,MAAMC,SAAS,GAAG,WAAW;AACpC,OAAO,MAAMC,QAAQ,GAAG,UAAU;AAClC,OAAO,MAAMC,IAAI,GAAG,MAAM;AAC1B,OAAO,MAAMC,YAAY,GAAG,cAAc;AAC1C,OAAO,MAAMC,cAAc,GAAG,gBAAgB;AAC9C,OAAO,MAAMC,SAAS,GAAG,WAAW;AACpC,OAAO,MAAMC,cAAc,GAAG,gBAAgB;AAC9C,OAAO,MAAMC,QAAQ,GAAG,UAAU;AAClC,OAAO,MAAMC,eAAe,GAAG,iBAAiB;AAChD,OAAO,MAAMC,QAAQ,GAAG,UAAU;AAClC,OAAO,MAAMC,kBAAkB,GAAG,oBAAoB;AACtD,OAAO,MAAMC,aAAa,GAAG,eAAe;AAC5C,OAAO,MAAMC,eAAe,GAAG,iBAAiB;AAChD,OAAO,MAAMC,kBAAkB,GAAG,oBAAoB;AACtD,OAAO,MAAMC,aAAa,GAAG,eAAe;AAC5C,OAAO,MAAMC,YAAY,GAAG,cAAc","ignoreList":[]}