spotny-sdk 1.0.0

package/ios/SpotnyBeaconScanner.swift

@@ -0,0 +1,938 @@
+//
+//  SpotnyBeaconScanner.swift
+//  SpotnySdk
+//
+//  Core iBeacon scanning logic using Kontakt.io SDK.
+//  Handles campaign fetching and proximity / impression tracking against
+//  the Spotny backend.
+//
+
+import Foundation
+import CoreLocation
+import KontaktSDK
+import UserNotifications
+import Security
+
+// MARK: - Public ObjC-visible typealias for the event callback block
+
+public typealias SpotnyEventCallback = @convention(block) (_ name: String, _ body: [String: Any]) -> Void
+
+// MARK: - Internal data structures
+
+private struct CampaignData {
+  let campaignId: Int?    // nil when no active campaign
+  let screenId: Int
+  let sessionId: String?  // set after first proximity response
+  let inQueue: Bool       // campaign is queued — skip impressions
+  let major: Int
+  let minor: Int
+}
+
+// MARK: - SpotnyBeaconScanner
+
+@objc(SpotnyBeaconScanner)
+public class SpotnyBeaconScanner: NSObject {
+
+  // ── Callback to send events back to SpotnySdk.mm ─────────────────────────
+  private var eventCallback: SpotnyEventCallback?
+
+  // ── Managers ──────────────────────────────────────────────────────────────
+  private var beaconManager: KTKBeaconManager!
+  private var locationManager: CLLocationManager!
+
+  // ── Session state ─────────────────────────────────────────────────────────
+  private var scanning: Bool = false
+  /// Authenticated user ID — required at initialize(). Embedded in the JWT via /api/app/sdk/verify.
+  private var userId: String?
+
+  // ── JS event deduplication ─────────────────────────────────────────
+  /// Signature of the last emitted `onBeaconsRanged` payload (sorted major_minor_proximity).
+  /// Event is only emitted when this changes, or when debounceInterval has elapsed.
+  private var lastRangedSignature: String = ""
+  private var lastRangedEmit: Date = .distantPast
+
+  // ── Configuration ────────────────────────────────────────────────────────────
+  // backendURL and kontaktAPIKey are fixed — not overridable by consumers.
+  private let backendURL: String = "https://api.spotny.app"
+  private let kontaktAPIKey: String = "mgrz08TOKNHafeY02cWIs9mxUHbynNQJ"
+  private var maxDetectionDistance: Double = 8.0
+  /// Multiplier applied to raw RSSI-derived distance to compensate for low TX power.
+  /// Overridable via configure(). Default 0.5 matches Kontakt.io -12 dBm beacons.
+  private var distanceCorrectionFactor: Double = 0.5
+  /// API key identifying the SDK consumer (e.g. "nike"). Set during initialize().
+  private var apiKey: String?
+  /// JWT returned by /api/app/sdk/verify. Injected as Authorization header on all subsequent calls.
+  private var sdkToken: String?
+  /// Expiry date of the current JWT. When exceeded, a new JWT is automatically fetched before every call.
+  private var sdkTokenExpiry: Date?
+  /// Original SDK token — persisted so JWT can be refreshed without calling initialize() again.
+  private var sdkCredential: String?
+  // JWT refresh coordination — queues concurrent callers while a single refresh is in-flight
+  private var jwtRefreshInProgress = false
+  private var jwtRefreshQueue: [(Error?) -> Void] = []
+
+  // ── Session TTL ────────────────────────────────────────────────────────────
+  /// Sessions older than this when the app resumes are considered stale (crash / force-quit).
+  private let sessionTTL: TimeInterval = 24 * 3600  // 24 hours
+  private var lastSessionHeartbeat: Date = .distantPast
+
+  // ── Beacon UUID (standard Kontakt.io default) ─────────────────────────────
+  private let beaconUUID = UUID(uuidString: "f7826da6-4fa2-4e98-8024-bc5b71e0893e")!
+
+  // ── Timing constants ──────────────────────────────────────────────────────
+  private let campaignFetchCooldown: TimeInterval    = 5.0
+  private let proximityDistanceThreshold: Double     = 0.75
+  private let impressionEventInterval: TimeInterval  = 10.0
+  private let impressionDistance: Double             = 2.0
+  private var debounceInterval: TimeInterval         = 5.0
+
+  // ── Per-beacon tracking state ──────────────────────────────────────────────
+  private var activeCampaigns:              [String: CampaignData] = [:]
+  private var lastProximityEventSent:       [String: Date]         = [:]
+  private var lastProximityDistance:        [String: Double]       = [:]
+  private var lastImpressionEventSent:      [String: Date]         = [:]
+  private var lastCampaignFetchAttempt:     [String: Date]         = [:]
+  private var fetchInProgress:              [String: Bool]         = [:]
+  private var fetchRetryCount:              [String: Int]          = [:]
+  private var proximityEventInProgress:     [String: Bool]         = [:]
+  private var impressionEventInProgress:    [String: Bool]         = [:]
+
+  // MARK: - Init
+
+  @objc
+  public init(eventCallback: @escaping SpotnyEventCallback) {
+    self.eventCallback = eventCallback
+    super.init()
+    setupManagers()
+    resumeStoredSession()
+  }
+
+  // MARK: - Setup
+
+  private func setupManagers() {
+    // Initialise the Kontakt.io SDK with the API key before creating any manager
+    Kontakt.setAPIKey(kontaktAPIKey)
+    print("✅ SpotnySDK: Kontakt.io SDK initialised")
+
+    locationManager = CLLocationManager()
+    locationManager.delegate = self
+    // allowsBackgroundLocationUpdates = true requires the app to declare the
+    // "location" UIBackgroundModes entry. Setting it without that entitlement
+    // raises NSInternalInconsistencyException and terminates the app.
+    if let modes = Bundle.main.object(forInfoDictionaryKey: "UIBackgroundModes") as? [String],
+       modes.contains("location") {
+      locationManager.allowsBackgroundLocationUpdates = true
+      locationManager.pausesLocationUpdatesAutomatically = false
+    }
+
+    beaconManager = KTKBeaconManager(delegate: self)
+  }
+
+  private func resumeStoredSession() {
+    // Resume scanning only if a valid session was previously active
+    guard let ts = UserDefaults.standard.object(forKey: "SpotnySDK_sessionTimestamp") as? Double else { return }
+    let age = Date().timeIntervalSince1970 - ts
+    if age > sessionTTL {
+      print("⚠️ SpotnySDK: Stale session (\(Int(age / 3600))h old) — discarding")
+      clearStoredSession()
+      return
+    }
+    // Restore persisted JWT + credentials so all API calls work without initialize()
+    sdkToken      = keychainRead(key: "SpotnySDK_jwt")
+    sdkCredential = keychainRead(key: "SpotnySDK_sdkCredential")
+    apiKey        = keychainRead(key: "SpotnySDK_apiKey")
+    userId        = keychainRead(key: "SpotnySDK_userId")
+    if let expiryStr = keychainRead(key: "SpotnySDK_jwtExpiry"), let ts = Double(expiryStr) {
+      sdkTokenExpiry = Date(timeIntervalSince1970: ts)
+    }
+    print("🔄 SpotnySDK: Resuming session (device: \(getDeviceId()))")
+    startPersistentScanning()
+    scanning = true
+  }
+
+  private func clearStoredSession() {
+    // Only clears the scanning session — identity (Keychain) is intentionally kept
+    UserDefaults.standard.removeObject(forKey: "SpotnySDK_sessionTimestamp")
+    UserDefaults.standard.synchronize()
+  }
+
+  // MARK: - ObjC-Exposed Methods (called from SpotnySdk.mm)
+
+  @objc
+  public func startScanner(
+    withResolve resolve: @escaping (Any?) -> Void,
+    reject: @escaping (String?, String?, Error?) -> Void
+  ) {
+    if scanning {
+      resolve("Already scanning")
+      return
+    }
+
+    UserDefaults.standard.set(Date().timeIntervalSince1970, forKey: "SpotnySDK_sessionTimestamp")
+    UserDefaults.standard.synchronize()
+
+    let status = locationManager.authorizationStatus
+    if status == .notDetermined {
+      locationManager.requestAlwaysAuthorization()
+    }
+
+    startPersistentScanning()
+    scanning = true
+    print("✅ SpotnySDK: Started scanning (device: \(getDeviceId()))")
+    resolve("Scanning started")
+  }
+
+  @objc
+  public func stopScanner(
+    withResolve resolve: @escaping (Any?) -> Void,
+    reject: @escaping (String?, String?, Error?) -> Void
+  ) {
+    beaconManager.stopMonitoringForAllRegions()
+    beaconManager.stopRangingBeaconsInAllRegions()
+    cleanupAllProximityState()
+
+    clearStoredSession()
+
+    scanning = false
+
+    print("⏹️ SpotnySDK: Stopped scanning")
+    resolve("Scanning stopped")
+  }
+
+  @objc
+  public func isScanning(
+    withResolve resolve: @escaping (Any?) -> Void,
+    reject: @escaping (String?, String?, Error?) -> Void
+  ) {
+    resolve(scanning)
+  }
+
+  @objc
+  public func initialize(
+    with config: NSDictionary,
+    resolve: @escaping (Any?) -> Void,
+    reject: @escaping (String?, String?, Error?) -> Void
+  ) {
+    // Apply config values
+    if let dist = config["maxDetectionDistance"] as? Double {
+      maxDetectionDistance = dist
+      print("⚙️ SpotnySDK: maxDetectionDistance = \(dist)m")
+    }
+    if let key = config["apiKey"] as? String {
+      apiKey = key
+      print("⚙️ SpotnySDK: apiKey = \(key)")
+    }
+    if let factor = config["distanceCorrectionFactor"] as? Double, factor > 0 {
+      distanceCorrectionFactor = factor
+      print("⚙️ SpotnySDK: distanceCorrectionFactor = \(factor)")
+    }
+    if let uid = config["userId"] as? String, !uid.isEmpty {
+      userId = uid
+    }
+    guard let token = config["token"] as? String, !token.isEmpty else {
+      reject("MISSING_TOKEN", "initialize() requires a token", nil)
+      return
+    }
+    guard let key = apiKey, !key.isEmpty else {
+      reject("MISSING_API_KEY", "initialize() requires an apiKey", nil)
+      return
+    }
+    guard let uid = userId, !uid.isEmpty else {
+      reject("MISSING_USER_ID", "initialize() requires a userId", nil)
+      return
+    }
+
+    // Send token + apiKey + userId to backend — response returns a JWT used for all subsequent calls
+    // sdkToken is nil here so no Authorization header is injected on this call
+    let verifyPayload: [String: Any] = ["token": token, "api_key": key, "user_id": uid]
+    post(endpoint: "/api/app/sdk/verify", payload: verifyPayload) { [weak self] result in
+      guard let self = self else { return }
+      switch result {
+      case .success(let (status, data)):
+        if 200...299 ~= status {
+          guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+                let dataObj = json["data"] as? [String: Any],
+                let jwt = dataObj["jwt"] as? String, !jwt.isEmpty else {
+            reject("VERIFY_FAILED", "SDK verification response missing JWT", nil)
+            return
+          }
+          self.sdkToken = jwt
+          self.sdkCredential = token
+          if let ts = dataObj["expires_at"] as? Double {
+            self.sdkTokenExpiry = Date(timeIntervalSince1970: ts)
+          } else if let i = dataObj["expires_at"] as? Int {
+            self.sdkTokenExpiry = Date(timeIntervalSince1970: Double(i))
+          }
+          self.persistJWT()
+          let expiryDesc = self.sdkTokenExpiry?.description ?? "no expiry"
+          print("\u{2705} SpotnySDK: Initialized \u{2014} JWT stored, expires: \(expiryDesc)")
+          resolve("SDK initialized")
+        } else if status == 401 || status == 403 {
+          print("❌ SpotnySDK: Token unauthorized (\(status))")
+          reject("UNAUTHORIZED", "Invalid or expired SDK token", nil)
+        } else {
+          print("❌ SpotnySDK: Verification failed (\(status))")
+          reject("VERIFY_FAILED", "SDK verification returned status \(status)", nil)
+        }
+      case .failure(let error):
+        print("❌ SpotnySDK: Verification network error — \(error.localizedDescription)")
+        reject("VERIFY_ERROR", error.localizedDescription, error)
+      }
+    }
+  }
+
+  @objc
+  public func requestNotificationPermissions(
+    withResolve resolve: @escaping (Any?) -> Void,
+    reject: @escaping (String?, String?, Error?) -> Void
+  ) {
+    UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) { granted, error in
+      DispatchQueue.main.async {
+        if let error = error {
+          reject("PERMISSION_ERROR", error.localizedDescription, error)
+        } else {
+          resolve(granted ? "granted" : "denied")
+        }
+      }
+    }
+  }
+
+  @objc
+  public func setDebounceInterval(
+    _ interval: Double,
+    resolve: @escaping (Any?) -> Void,
+    reject: @escaping (String?, String?, Error?) -> Void
+  ) {
+    debounceInterval = interval
+    resolve("Debounce interval set to \(interval)s")
+  }
+
+  @objc
+  public func clearDebounceCache(
+    withResolve resolve: @escaping (Any?) -> Void,
+    reject: @escaping (String?, String?, Error?) -> Void
+  ) {
+    lastCampaignFetchAttempt.removeAll()
+    fetchInProgress.removeAll()
+    fetchRetryCount.removeAll()
+    resolve("Debounce cache cleared")
+  }
+
+  // MARK: - Debounce Status
+
+  @objc
+  public func getDebounceStatus(
+    withResolve resolve: @escaping (Any?) -> Void,
+    reject: @escaping (String?, String?, Error?) -> Void
+  ) {
+    var status: [String: Any] = [:]
+    for (key, _) in activeCampaigns {
+      var entry: [String: Any] = [:]
+      if let lastFetch = lastCampaignFetchAttempt[key] {
+        entry["lastFetchAttempt"] = lastFetch.timeIntervalSince1970
+      }
+      if let inProg = fetchInProgress[key] {
+        entry["fetchInProgress"] = inProg
+      }
+      if let lastProx = lastProximityEventSent[key] {
+        entry["lastProximityEvent"] = lastProx.timeIntervalSince1970
+      }
+      if let lastImp = lastImpressionEventSent[key] {
+        entry["lastImpressionEvent"] = lastImp.timeIntervalSince1970
+      }
+      status[key] = entry
+    }
+    resolve(status)
+  }
+
+  // MARK: - Debug Logging
+
+  @objc
+  public func getDebugLogs(
+    withResolve resolve: @escaping (Any?) -> Void,
+    reject: @escaping (String?, String?, Error?) -> Void
+  ) {
+    guard let docsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first else {
+      reject("ERROR", "Cannot access documents directory", nil); return
+    }
+    let logURL = docsURL.appendingPathComponent("spotny_beacon_debug.log")
+    resolve((try? String(contentsOf: logURL, encoding: .utf8)) ?? "No logs found")
+  }
+
+  @objc
+  public func clearDebugLogs(
+    withResolve resolve: @escaping (Any?) -> Void,
+    reject: @escaping (String?, String?, Error?) -> Void
+  ) {
+    guard let docsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first else {
+      reject("ERROR", "Cannot access documents directory", nil); return
+    }
+    try? FileManager.default.removeItem(at: docsURL.appendingPathComponent("spotny_beacon_debug.log"))
+    resolve("Logs cleared")
+  }
+
+  // MARK: - Scanning Setup
+
+  private func startPersistentScanning() {
+    print("🚀 SpotnySDK: Starting persistent beacon scanning…")
+
+    // General region — monitors all beacons with the Kontakt.io UUID
+    let generalRegion = KTKBeaconRegion(proximityUUID: beaconUUID, identifier: "SpotnySDK_GeneralRegion")
+    generalRegion.notifyOnEntry = true
+    generalRegion.notifyOnExit  = true
+    generalRegion.notifyEntryStateOnDisplay = true
+
+    beaconManager.startMonitoring(for: generalRegion)
+    beaconManager.startRangingBeacons(in: generalRegion)
+
+    print("🎯 SpotnySDK: Monitoring UUID \(beaconUUID.uuidString)")
+  }
+
+  // MARK: - Helpers
+
+  private func beaconKey(major: Int, minor: Int) -> String { "\(major)_\(minor)" }
+
+  // ── Keychain helpers (device ID survives uninstall/reinstall) ──────────────
+  private let keychainService = "app.spotny.sdk"
+
+  private func keychainRead(key: String) -> String? {
+    let query: [CFString: Any] = [
+      kSecClass:       kSecClassGenericPassword,
+      kSecAttrService: keychainService,
+      kSecAttrAccount: key,
+      kSecReturnData:  true,
+      kSecMatchLimit:  kSecMatchLimitOne
+    ]
+    var result: AnyObject?
+    guard SecItemCopyMatching(query as CFDictionary, &result) == errSecSuccess,
+          let data = result as? Data else { return nil }
+    return String(data: data, encoding: .utf8)
+  }
+
+  private func keychainWrite(key: String, value: String) {
+    guard let data = value.data(using: .utf8) else { return }
+    let query: [CFString: Any] = [
+      kSecClass:       kSecClassGenericPassword,
+      kSecAttrService: keychainService,
+      kSecAttrAccount: key
+    ]
+    if SecItemCopyMatching(query as CFDictionary, nil) == errSecSuccess {
+      SecItemUpdate(query as CFDictionary, [kSecValueData: data] as CFDictionary)
+    } else {
+      var item = query; item[kSecValueData] = data
+      SecItemAdd(item as CFDictionary, nil)
+    }
+  }
+
+  private func keychainDelete(key: String) {
+    let query: [CFString: Any] = [
+      kSecClass:       kSecClassGenericPassword,
+      kSecAttrService: keychainService,
+      kSecAttrAccount: key
+    ]
+    SecItemDelete(query as CFDictionary)
+  }
+
+  private func getDeviceId() -> String {
+    let kcKey = "SpotnySDK_deviceId"
+    // 1. Keychain — survives uninstall
+    if let stored = keychainRead(key: kcKey) { return stored }
+    // 2. Migrate existing UserDefaults value on first run after upgrade
+    if let legacy = UserDefaults.standard.string(forKey: kcKey) {
+      keychainWrite(key: kcKey, value: legacy)
+      UserDefaults.standard.removeObject(forKey: kcKey)
+      return legacy
+    }
+    // 3. Generate new ID
+    let id = UIDevice.current.identifierForVendor?.uuidString ?? UUID().uuidString
+    keychainWrite(key: kcKey, value: id)
+    return id
+  }
+
+  private func proximityLabel(from distance: Double) -> String {
+    if distance < 0    { return "unknown"   }
+    if distance < 0.5  { return "immediate" }
+    if distance < 3.0  { return "near"      }
+    return "far"
+  }
+
+  private func logToFile(_ message: String) {
+    guard let docsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first else { return }
+    let logURL = docsURL.appendingPathComponent("spotny_beacon_debug.log")
+    let ts = DateFormatter.localizedString(from: Date(), dateStyle: .short, timeStyle: .medium)
+    let entry = "[\(ts)] \(message)\n"
+    guard let data = entry.data(using: .utf8) else { return }
+    if FileManager.default.fileExists(atPath: logURL.path),
+       let handle = try? FileHandle(forWritingTo: logURL) {
+      handle.seekToEndOfFile(); handle.write(data); handle.closeFile()
+    } else {
+      try? data.write(to: logURL)
+    }
+  }
+
+  // MARK: - Backend API
+
+  private func isTokenExpired() -> Bool {
+    guard sdkToken != nil else { return true }
+    guard let expiry = sdkTokenExpiry else { return false } // no expiry field = treat as valid
+    return Date() >= expiry
+  }
+
+  private func persistJWT() {
+    if let jwt  = sdkToken       { keychainWrite(key: "SpotnySDK_jwt",           value: jwt)  }
+    if let exp  = sdkTokenExpiry { keychainWrite(key: "SpotnySDK_jwtExpiry",     value: String(exp.timeIntervalSince1970)) }
+    if let cred = sdkCredential  { keychainWrite(key: "SpotnySDK_sdkCredential", value: cred) }
+    if let key  = apiKey         { keychainWrite(key: "SpotnySDK_apiKey",        value: key)  }
+    if let uid  = userId         { keychainWrite(key: "SpotnySDK_userId",        value: uid)  }
+  }
+
+  /// Refresh the JWT. Concurrent callers are queued and flushed together when the single
+  /// in-flight request completes — avoids sending N parallel verify requests.
+  private func refreshJWT(completion: @escaping (Error?) -> Void) {
+    if jwtRefreshInProgress {
+      jwtRefreshQueue.append(completion)
+      return
+    }
+    guard let credential = sdkCredential, let key = apiKey else {
+      completion(NSError(domain: "SpotnySDK", code: -3,
+        userInfo: [NSLocalizedDescriptionKey: "Cannot refresh JWT — call initialize() first"]))
+      return
+    }
+    jwtRefreshInProgress = true
+    let refreshPayload: [String: Any] = ["token": credential, "api_key": key, "user_id": userId ?? ""]
+    performPost(endpoint: "/api/app/sdk/verify", payload: refreshPayload) { [weak self] result in
+      guard let self = self else { return }
+      let flush: (Error?) -> Void = { err in
+        let queue = self.jwtRefreshQueue
+        self.jwtRefreshQueue.removeAll()
+        self.jwtRefreshInProgress = false
+        completion(err)
+        queue.forEach { $0(err) }
+      }
+      switch result {
+      case .success(let (status, data)):
+        if 200...299 ~= status,
+           let json    = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+           let dataObj = json["data"] as? [String: Any],
+           let jwt     = dataObj["jwt"] as? String, !jwt.isEmpty {
+          self.sdkToken = jwt
+          if let ts = dataObj["expires_at"] as? Double {
+            self.sdkTokenExpiry = Date(timeIntervalSince1970: ts)
+          } else if let i = dataObj["expires_at"] as? Int {
+            self.sdkTokenExpiry = Date(timeIntervalSince1970: Double(i))
+          }
+          self.persistJWT()
+          let expiryDesc = self.sdkTokenExpiry?.description ?? "no expiry"
+          print("\u{1F504} SpotnySDK: JWT refreshed, expires: \(expiryDesc)")
+          flush(nil)
+        } else {
+          flush(NSError(domain: "SpotnySDK", code: -4,
+            userInfo: [NSLocalizedDescriptionKey: "JWT refresh failed — status \(status)"]))
+        }
+      case .failure(let error):
+        print("❌ SpotnySDK: JWT refresh error — \(error.localizedDescription)")
+        flush(error)
+      }
+    }
+  }
+
+  /// Entry point — checks JWT expiry and auto-refreshes before every call except verify itself.
+  private func post(
+    endpoint: String,
+    payload: [String: Any],
+    completion: @escaping (Result<(Int, Data), Error>) -> Void
+  ) {
+    guard endpoint == "/api/app/sdk/verify" || !isTokenExpired() else {
+      refreshJWT { [weak self] error in
+        if let error = error { completion(.failure(error)); return }
+        self?.performPost(endpoint: endpoint, payload: payload, completion: completion)
+      }
+      return
+    }
+    performPost(endpoint: endpoint, payload: payload, completion: completion)
+  }
+
+  private func performPost(
+    endpoint: String,
+    payload: [String: Any],
+    completion: @escaping (Result<(Int, Data), Error>) -> Void
+  ) {
+    guard let url = URL(string: "\(backendURL)\(endpoint)") else {
+      completion(.failure(NSError(domain: "SpotnySDK", code: -1,
+        userInfo: [NSLocalizedDescriptionKey: "Invalid URL: \(backendURL)\(endpoint)"])))
+      return
+    }
+    var req = URLRequest(url: url)
+    req.httpMethod = "POST"
+    req.setValue("application/json", forHTTPHeaderField: "Content-Type")
+    if let token = sdkToken { req.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization") }
+    req.timeoutInterval = 10.0
+
+    var bg: UIBackgroundTaskIdentifier = .invalid
+    bg = UIApplication.shared.beginBackgroundTask { UIApplication.shared.endBackgroundTask(bg); bg = .invalid }
+
+    do {
+      req.httpBody = try JSONSerialization.data(withJSONObject: payload)
+    } catch {
+      UIApplication.shared.endBackgroundTask(bg)
+      completion(.failure(error)); return
+    }
+
+    URLSession.shared.dataTask(with: req) { data, response, error in
+      DispatchQueue.main.async {
+        if bg != .invalid { UIApplication.shared.endBackgroundTask(bg); bg = .invalid }
+        if let error = error { completion(.failure(error)); return }
+        guard let http = response as? HTTPURLResponse, let data = data else {
+          completion(.failure(NSError(domain: "SpotnySDK", code: -2,
+            userInfo: [NSLocalizedDescriptionKey: "Bad response"]))); return
+        }
+        completion(.success((http.statusCode, data)))
+      }
+    }.resume()
+  }
+
+  // MARK: - Campaign Fetching
+
+  /// Exponential cooldown: 5 s → 15 s → 45 s. After 3 failures the key is
+  /// considered permanently failed until the beacon region is re-entered.
+  private func fetchCooldown(for key: String) -> TimeInterval {
+    let retries = fetchRetryCount[key] ?? 0
+    return campaignFetchCooldown * pow(3.0, Double(min(retries, 3)))
+  }
+
+  private func fetchCampaign(major: Int, minor: Int) {
+    let key = beaconKey(major: major, minor: minor)
+    guard activeCampaigns[key] == nil else { return }
+    guard fetchInProgress[key] != true else { return }
+    // Give up after 3 consecutive failures (cooldown would be 135 s+)
+    if (fetchRetryCount[key] ?? 0) > 3 { return }
+
+    if let last = lastCampaignFetchAttempt[key],
+       Date().timeIntervalSince(last) < fetchCooldown(for: key) { return }
+
+    lastCampaignFetchAttempt[key] = Date()
+    fetchInProgress[key] = true
+
+    let payload: [String: Any] = ["beacon_id": key]
+
+    post(endpoint: "/api/app/campaigns/beacon", payload: payload) { [weak self] result in
+      guard let self = self else { return }
+      defer { self.fetchInProgress[key] = false }
+
+      guard case .success(let (status, data)) = result, status == 200 else {
+        if case .success(let (s, _)) = result {
+          print("❌ SpotnySDK: Campaign fetch status \(s) for beacon \(key)")
+        }
+        // Increment retry count so next attempt uses a longer cooldown
+        self.fetchRetryCount[key] = (self.fetchRetryCount[key] ?? 0) + 1
+        logToFile("❌ Campaign fetch failed for beacon \(key) (retry \(self.fetchRetryCount[key] ?? 0))")
+        return
+      }
+      do {
+        guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any],
+              let dataObj = json["data"]     as? [String: Any],
+              let screen  = dataObj["screen"] as? [String: Any],
+              let screenId = screen["id"]    as? Int else {
+          print("⚠️ SpotnySDK: Unexpected campaign response format for \(key)")
+          return
+        }
+        var campaignId: Int?
+        var inQueue = false
+        if let campaignObj = dataObj["campaign"] as? [String: Any],
+           let cid = campaignObj["id"] as? Int {
+          campaignId = cid
+          inQueue = campaignObj["inQueue"] as? Bool ?? false
+        }
+        self.activeCampaigns[key] = CampaignData(
+          campaignId: campaignId, screenId: screenId,
+          sessionId: nil, inQueue: inQueue, major: major, minor: minor)
+        self.fetchRetryCount.removeValue(forKey: key)  // reset on success
+        logToFile("✅ Campaign loaded for beacon \(key) — screenId=\(screenId)")
+        print("✅ SpotnySDK: Campaign loaded for beacon \(key) — screenId=\(screenId)")
+      } catch {
+        print("❌ SpotnySDK: JSON parse error for beacon \(key): \(error)")
+      }
+    }
+  }
+
+  // MARK: - Tracking
+
+  private func sendTracking(
+    eventType: String,
+    key: String,
+    distance: Double,
+    endpoint: String
+  ) {
+    let isImpression = eventType == "IMPRESSION_HEARTBEAT"
+    let inProg = isImpression ? impressionEventInProgress[key] : proximityEventInProgress[key]
+    guard inProg != true else { return }
+
+    if isImpression { impressionEventInProgress[key] = true }
+    else            { proximityEventInProgress[key]  = true }
+
+    guard let campaign = activeCampaigns[key] else {
+      if isImpression { impressionEventInProgress[key] = false }
+      else            { proximityEventInProgress[key]  = false }
+      return
+    }
+    if isImpression {
+      guard let _ = campaign.campaignId, !campaign.inQueue else {
+        impressionEventInProgress[key] = false; return
+      }
+    }
+
+    var payload: [String: Any] = [
+      "event_type": eventType,
+      "distance":   distance,
+      "screen_id":  campaign.screenId
+    ]
+    if let cid = campaign.campaignId { payload["campaign_id"] = cid }
+    if let sid = campaign.sessionId  { payload["session_id"]  = sid }
+
+    post(endpoint: endpoint, payload: payload) { [weak self] result in
+      guard let self = self else { return }
+      switch result {
+      case .success(let (status, data)):
+        if 200...299 ~= status {
+          print("✅ SpotnySDK: \(eventType) sent — distance \(String(format: "%.2f", distance))m")
+          logToFile("✅ \(eventType) sent — beacon \(key) @ \(String(format: "%.2f", distance))m")
+          if !isImpression, campaign.sessionId == nil,
+             let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+             let dObj = json["data"] as? [String: Any],
+             let ev   = dObj["event"] as? [String: Any],
+             let sid  = ev["session_id"] as? String {
+            let updated = CampaignData(
+              campaignId: campaign.campaignId, screenId: campaign.screenId,
+              sessionId: sid, inQueue: campaign.inQueue,
+              major: campaign.major, minor: campaign.minor)
+            self.activeCampaigns[key] = updated
+            print("✅ SpotnySDK: session_id = \(sid)")
+          }
+        } else if status == 429 {
+          let penalty = Date().addingTimeInterval(10)
+          if isImpression { self.lastImpressionEventSent[key] = penalty }
+          else            { self.lastProximityEventSent[key]  = penalty }
+          print("⚠️ SpotnySDK: \(eventType) rate-limited (429)")
+        } else {
+          print("❌ SpotnySDK: \(eventType) failed — status \(status)")
+        }
+      case .failure(let error):
+        print("❌ SpotnySDK: \(eventType) error — \(error.localizedDescription)")
+      }
+      if isImpression { self.impressionEventInProgress[key] = false }
+      else            { self.proximityEventInProgress[key]  = false }
+    }
+  }
+
+  private func sendProximity(eventType: String, key: String, distance: Double) {
+    sendTracking(eventType: eventType, key: key, distance: distance,
+                 endpoint: "/api/app/impressions/proximity")
+  }
+
+  private func sendImpression(key: String, distance: Double) {
+    sendTracking(eventType: "IMPRESSION_HEARTBEAT", key: key, distance: distance,
+                 endpoint: "/api/app/impressions/track")
+  }
+
+  // MARK: - State Cleanup
+
+  private func cleanupBeacon(_ key: String, distance: Double = 0) {
+    sendProximity(eventType: "PROXIMITY_EXIT", key: key, distance: distance)
+    activeCampaigns.removeValue(forKey: key)
+    lastProximityEventSent.removeValue(forKey: key)
+    lastProximityDistance.removeValue(forKey: key)
+    lastImpressionEventSent.removeValue(forKey: key)
+    lastCampaignFetchAttempt.removeValue(forKey: key)
+    fetchInProgress.removeValue(forKey: key)
+    fetchRetryCount.removeValue(forKey: key)
+    proximityEventInProgress.removeValue(forKey: key)
+    impressionEventInProgress.removeValue(forKey: key)
+    print("🧹 SpotnySDK: Cleaned up state for beacon \(key)")
+  }
+
+  private func cleanupAllProximityState() {
+    // Stagger exit events to avoid firing N simultaneous network requests
+    let keys = Array(activeCampaigns.keys)
+    for (index, key) in keys.enumerated() {
+      DispatchQueue.main.asyncAfter(deadline: .now() + Double(index) * 0.3) { [weak self] in
+        self?.cleanupBeacon(key)
+      }
+    }
+  }
+}
+
+// MARK: - CLLocationManagerDelegate
+
+extension SpotnyBeaconScanner: CLLocationManagerDelegate {
+  public func locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {
+    switch status {
+    case .authorizedAlways:    print("✅ SpotnySDK: Location → ALWAYS")
+    case .authorizedWhenInUse: print("⚠️ SpotnySDK: Location → WHEN IN USE (limited background)")
+    case .denied, .restricted: print("❌ SpotnySDK: Location → DENIED")
+    case .notDetermined:       print("⏳ SpotnySDK: Location → not determined")
+    @unknown default:          break
+    }
+  }
+}
+
+// MARK: - KTKBeaconManagerDelegate
+
+extension SpotnyBeaconScanner: KTKBeaconManagerDelegate {
+
+  public func beaconManager(
+    _ manager: KTKBeaconManager,
+    didRangeBeacons beacons: [CLBeacon],
+    in region: KTKBeaconRegion
+  ) {
+    let now = Date()
+
+    // Refresh session heartbeat every 60 s to prevent TTL expiry on a live session
+    if now.timeIntervalSince(lastSessionHeartbeat) >= 60 {
+      UserDefaults.standard.set(now.timeIntervalSince1970, forKey: "SpotnySDK_sessionTimestamp")
+      lastSessionHeartbeat = now
+    }
+
+    // Build the JS event payload for ALL ranged beacons
+    let beaconPayload: [[String: Any]] = beacons.compactMap { beacon in
+      let raw = beacon.accuracy
+      let adjusted = raw * distanceCorrectionFactor
+      guard adjusted > 0 && adjusted <= maxDetectionDistance else { return nil }
+      return [
+        "uuid":      beacon.proximityUUID.uuidString,
+        "major":     beacon.major.intValue,
+        "minor":     beacon.minor.intValue,
+        "distance":  adjusted,
+        "rssi":      beacon.rssi,
+        "proximity": proximityLabel(from: adjusted)
+      ]
+    }
+
+    // Only emit onBeaconsRanged when proximity state changed, or after debounceInterval
+    if !beaconPayload.isEmpty {
+      let signature = beaconPayload
+        .map { "\($0["major"]!)_\($0["minor"]!)_\($0["proximity"]!)" }
+        .sorted().joined(separator: ",")
+      let stale = now.timeIntervalSince(lastRangedEmit) >= debounceInterval
+      if signature != lastRangedSignature || stale {
+        eventCallback?("onBeaconsRanged", ["beacons": beaconPayload, "region": region.identifier])
+        lastRangedSignature = signature
+        lastRangedEmit = now
+      }
+    } else if lastRangedSignature != "" {
+      // All beacons left range — emit empty to let JS clear its state
+      eventCallback?("onBeaconsRanged", ["beacons": [], "region": region.identifier])
+      lastRangedSignature = ""
+    }
+
+    // Per-beacon campaign & proximity logic
+    for beacon in beacons {
+      let major     = beacon.major.intValue
+      let minor     = beacon.minor.intValue
+      let key       = beaconKey(major: major, minor: minor)
+      let raw       = beacon.accuracy
+      let distance  = raw * distanceCorrectionFactor
+
+      guard distance > 0 && distance <= maxDetectionDistance else { continue }
+
+      if let campaign = activeCampaigns[key] {
+        let isFirst = lastProximityEventSent[key] == nil
+
+        if isFirst {
+          sendProximity(eventType: "NEARBY", key: key, distance: distance)
+          lastProximityDistance[key] = distance
+          lastProximityEventSent[key] = now
+        } else if distance >= 1.0,
+                  let lastDist = lastProximityDistance[key],
+                  abs(distance - lastDist) >= proximityDistanceThreshold {
+          sendProximity(eventType: "NEARBY", key: key, distance: distance)
+          lastProximityDistance[key] = distance
+          lastProximityEventSent[key] = now
+        }
+
+        // Impression heartbeat when user is very close
+        if let _ = campaign.campaignId, !campaign.inQueue, distance <= impressionDistance {
+          if let last = lastImpressionEventSent[key] {
+            if now.timeIntervalSince(last) >= impressionEventInterval {
+              sendImpression(key: key, distance: distance)
+              lastImpressionEventSent[key] = now
+            }
+          } else {
+            sendImpression(key: key, distance: distance)
+            lastImpressionEventSent[key] = now
+          }
+        }
+      } else {
+        fetchCampaign(major: major, minor: minor)
+      }
+    }
+  }
+
+  public func beaconManager(_ manager: KTKBeaconManager, didEnter region: KTKBeaconRegion) {
+    print("🎯 SpotnySDK: Entered region \(region.identifier)")
+    eventCallback?("onBeaconRegionEvent", ["region": region.identifier, "event": "enter"])
+
+    var bg: UIBackgroundTaskIdentifier = .invalid
+    bg = UIApplication.shared.beginBackgroundTask { UIApplication.shared.endBackgroundTask(bg); bg = .invalid }
+    defer {
+      DispatchQueue.main.asyncAfter(deadline: .now() + 3.0) {
+        if bg != .invalid { UIApplication.shared.endBackgroundTask(bg); bg = .invalid }
+      }
+    }
+
+    // Parse major/minor from named regions (e.g. "SpotnySDK_52885_35127")
+    let parts = region.identifier.components(separatedBy: "_")
+    if parts.count == 3, let major = Int(parts[1]), let minor = Int(parts[2]) {
+      let key = beaconKey(major: major, minor: minor)
+      // Reset fetch state on re-entry so retry backoff starts fresh
+      lastCampaignFetchAttempt.removeValue(forKey: key)
+      fetchRetryCount.removeValue(forKey: key)
+      if activeCampaigns[key] == nil {
+        fetchCampaign(major: major, minor: minor)
+      }
+    }
+  }
+
+  public func beaconManager(_ manager: KTKBeaconManager, didExitRegion region: KTKBeaconRegion) {
+    print("🚪 SpotnySDK: Exited region \(region.identifier)")
+    eventCallback?("onBeaconRegionEvent", ["region": region.identifier, "event": "exit"])
+
+    var bg: UIBackgroundTaskIdentifier = .invalid
+    bg = UIApplication.shared.beginBackgroundTask { UIApplication.shared.endBackgroundTask(bg); bg = .invalid }
+    defer {
+      DispatchQueue.main.asyncAfter(deadline: .now() + 2.0) {
+        if bg != .invalid { UIApplication.shared.endBackgroundTask(bg); bg = .invalid }
+      }
+    }
+
+    let parts = region.identifier.components(separatedBy: "_")
+    if parts.count == 3, let major = Int(parts[1]), let minor = Int(parts[2]) {
+      cleanupBeacon(beaconKey(major: major, minor: minor))
+    }
+
+    beaconManager.stopRangingBeacons(in: region)
+  }
+
+  public func beaconManager(
+    _ manager: KTKBeaconManager,
+    didDetermineState state: CLRegionState,
+    for region: KTKBeaconRegion
+  ) {
+    let label: String
+    switch state {
+    case .inside:  label = "inside"
+    case .outside: label = "outside"
+    case .unknown: label = "unknown"
+    @unknown default: label = "unknown"
+    }
+    eventCallback?("onBeaconRegionEvent", ["region": region.identifier, "event": "determined", "state": label])
+    print("📊 SpotnySDK: Region \(region.identifier) → \(label)")
+  }
+
+  public func beaconManager(
+    _ manager: KTKBeaconManager,
+    monitoringDidFailFor region: KTKBeaconRegion?,
+    withError error: Error?
+  ) {
+    print("❌ SpotnySDK: Monitoring failed for \(region?.identifier ?? "?") — \(error?.localizedDescription ?? "unknown error")")
+  }
+}