spotny-sdk 1.0.6 → 1.0.7

package/README.md

@@ -269,14 +269,14 @@ Returns `Promise<Object>`.
 
 1. `initialize()` sends your `token`, `apiKey`, and `identifierId` to the Spotny backend, which issues a session JWT. The JWT is persisted locally and auto-refreshed when it expires.
 2. `startScanner()` begins monitoring for iBeacons with the Spotny UUID.
-3. When a beacon is detected, the SDK immediately sends a `NEARBY` proximity event with only the `beacon_id` — the backend resolves the associated screen.
-4. The backend returns campaign data (`campaign_id`, `session_id`, `inQueue` flag) in the response.
-5. The SDK stores this campaign data and includes it in subsequent events.
-6. Additional `NEARBY` events are sent automatically as the user moves closer or further (when distance changes > 0.75m). All events send `beacon_id` — the backend handles screen resolution.
-7. `IMPRESSION_HEARTBEAT` events are sent every 10 s when the user is within 2 m of a beacon with an active campaign (not queued).
+3. When a beacon is first detected, the SDK immediately sends a `NEARBY` proximity event with the `beacon_id` to log the user's presence.
+4. When the user gets within **3 meters**, the SDK calls `/distribute` with the `beacon_id` to fetch campaign data (`screen_id`, `campaign_id`, `session_id`, `inQueue` flag).
+5. The SDK stores this campaign data and uses it for subsequent impression events.
+6. Additional `NEARBY` events are sent automatically as the user moves closer or further (when distance changes > 0.75m).
+7. `IMPRESSION_HEARTBEAT` events are sent every 10 s when the user is within 2 m of a beacon with an active campaign (not queued). These events include `screen_id`, `campaign_id`, and `session_id`.
 8. On exit, `PROXIMITY_EXIT` is sent and all state is cleaned up.
 
-**The SDK is fully backend-driven:** It only sends `beacon_id` + distance. The backend owns the beacon → screen mapping, so you can reassign beacons to different screens without updating the SDK.
+**Two-stage tracking:** Proximity events are lightweight (beacon_id only) and sent immediately. Campaign data is fetched only when needed (at 3m), optimizing network usage while ensuring timely engagement tracking.
 
 All events are tied to the authenticated `identifierId` supplied during `initialize()` — no additional identity calls are required.
 

package/android/src/main/java/com/spotnysdk/SpotnySdkModule.kt

@@ -70,6 +70,8 @@ class SpotnySdkModule(private val reactContext: ReactApplicationContext) :
   private val lastImpressionEventSent   = mutableMapOf<String, Long>()
   private val proximityEventInProgress  = mutableMapOf<String, Boolean>()
   private val impressionEventInProgress = mutableMapOf<String, Boolean>()
+  private val campaignFetchInProgress   = mutableMapOf<String, Boolean>()
+  private val campaignFetched           = mutableMapOf<String, Boolean>()
 
   // ── Module registration ───────────────────────────────────────────────────
 
@@ -310,6 +312,11 @@ class SpotnySdkModule(private val reactContext: ReactApplicationContext) :
         }
       }
       
+      // Fetch campaign when distance <= 3m
+      if (distance <= 3.0 && campaignFetched[key] != true) {
+        fetchCampaign(key, major, minor)
+      }
+      
       // Impression heartbeat when user is very close AND campaign exists
       val campaign = activeCampaigns[key]
       if (campaign?.campaignId != null && campaign.inQueue == false && distance <= impressionDistance) {
@@ -406,6 +413,8 @@ class SpotnySdkModule(private val reactContext: ReactApplicationContext) :
     lastImpressionEventSent.remove(key)
     proximityEventInProgress.remove(key)
     impressionEventInProgress.remove(key)
+    campaignFetchInProgress.remove(key)
+    campaignFetched.remove(key)
     Log.d(TAG, "Cleaned up state for beacon $key")
   }
 
@@ -541,7 +550,7 @@ class SpotnySdkModule(private val reactContext: ReactApplicationContext) :
     if (isImpression) impressionEventInProgress[key] = true
     else              proximityEventInProgress[key]  = true
 
-    // Build payload — all events now use beacon_id, backend resolves screen_id
+    // Build payload — proximity events send beacon_id only, impressions include campaign data
     val payload = mutableMapOf<String, Any?>(
       "event_type" to eventType,
       "beacon_id"  to key,
@@ -555,71 +564,74 @@ class SpotnySdkModule(private val reactContext: ReactApplicationContext) :
         impressionEventInProgress[key] = false
         return
       }
+      payload["screen_id"] = campaign.screenId
       campaign.campaignId?.let { payload["campaign_id"] = it }
       campaign.sessionId?.let  { payload["session_id"]  = it }
-    } else {
-      // Proximity events also send campaign/session if available
-      activeCampaigns[key]?.let { campaign ->
-        campaign.campaignId?.let { payload["campaign_id"] = it }
-        campaign.sessionId?.let  { payload["session_id"]  = it }
-      }
     }
 
     post(endpoint, payload) { status, body ->
       if (status in 200..299) {
         Log.d(TAG, "$eventType sent — distance ${"%.2f".format(distance)}m")
-        
-        // Parse campaign_id, session_id from proximity response
-        if (!isImpression) {
-          try {
-            val json = parseJsonObject(body)
-            val dataObj = json?.get("data") as? Map<*, *>
-            
+      } else if (status == 429) {
+        val penalty = System.currentTimeMillis() + 10_000L
+        if (isImpression) lastImpressionEventSent[key] = penalty
+        else              lastProximityEventSent[key]  = penalty
+        Log.w(TAG, "$eventType rate-limited (429)")
+      } else {
+        Log.w(TAG, "$eventType failed — status $status")
+      }
+      if (isImpression) impressionEventInProgress[key] = false
+      else              proximityEventInProgress[key]  = false
+    }
+  }
+
+  private fun fetchCampaign(key: String, major: Int, minor: Int) {
+    if (campaignFetchInProgress[key] == true) return
+    if (campaignFetched[key] == true) return
+    
+    campaignFetchInProgress[key] = true
+    
+    val payload = mapOf("beacon_id" to key)
+    
+    post("$apiBasePath/distribute", payload) { status, body ->
+      campaignFetchInProgress[key] = false
+      
+      if (status in 200..299) {
+        try {
+          val json = parseJsonObject(body)
+          val dataObj = json?.get("data") as? Map<*, *>
+          
+          if (dataObj != null) {
+            val screenId = (dataObj["screen_id"] as? Number)?.toInt() ?: 0
             var campaignId: Int? = null
             var sessionId: String? = null
             var inQueue = false
             
-            // Extract session_id from event object
-            val eventObj = dataObj?.get("event") as? Map<*, *>
-            if (eventObj != null) {
-              sessionId = eventObj["session_id"] as? String
-            }
-            
-            // Extract from campaign object
-            val campaignObj = dataObj?.get("campaign") as? Map<*, *>
+            val campaignObj = dataObj["campaign"] as? Map<*, *>
             if (campaignObj != null) {
               campaignId = (campaignObj["id"] as? Number)?.toInt()
+              sessionId = campaignObj["session_id"] as? String
               inQueue = campaignObj["inQueue"] as? Boolean ?: false
             }
             
-            // Store campaign data
-            // Parse major/minor from key
-            val parts = key.split("_")
-            val major = parts.getOrNull(0)?.toIntOrNull() ?: 0
-            val minor = parts.getOrNull(1)?.toIntOrNull() ?: 0
-            
             activeCampaigns[key] = CampaignData(
+              screenId = screenId,
               campaignId = campaignId,
               sessionId = sessionId,
               inQueue = inQueue,
               major = major,
               minor = minor
             )
-            Log.d(TAG, "Stored campaign — campaignId=$campaignId, sessionId=$sessionId, inQueue=$inQueue")
-          } catch (e: Exception) {
-            Log.w(TAG, "Error parsing proximity response: ${e.message}")
+            campaignFetched[key] = true
+            
+            Log.d(TAG, "Campaign fetched — screenId=$screenId, campaignId=$campaignId, sessionId=$sessionId, inQueue=$inQueue")
           }
+        } catch (e: Exception) {
+          Log.w(TAG, "Error parsing campaign response: ${e.message}")
         }
-      } else if (status == 429) {
-        val penalty = System.currentTimeMillis() + 10_000L
-        if (isImpression) lastImpressionEventSent[key] = penalty
-        else              lastProximityEventSent[key]  = penalty
-        Log.w(TAG, "$eventType rate-limited (429)")
       } else {
-        Log.w(TAG, "$eventType failed — status $status")
+        Log.w(TAG, "Campaign fetch failed — status $status")
       }
-      if (isImpression) impressionEventInProgress[key] = false
-      else              proximityEventInProgress[key]  = false
     }
   }
 

package/ios/SpotnyBeaconScanner.swift

@@ -20,8 +20,9 @@ public typealias SpotnyEventCallback = @convention(block) (_ name: String, _ bod
 // MARK: - Internal data structures
 
 private struct CampaignData {
+  let screenId: Int
   let campaignId: Int?    // nil when no active campaign
-  let sessionId: String?  // set after first proximity response
+  let sessionId: String?  // set after campaign fetch response
   let inQueue: Bool       // campaign is queued — skip impressions
   let major: Int
   let minor: Int
@@ -92,6 +93,8 @@ public class SpotnyBeaconScanner: NSObject {
   private var lastImpressionEventSent:      [String: Date]         = [:]
   private var proximityEventInProgress:     [String: Bool]         = [:]
   private var impressionEventInProgress:    [String: Bool]         = [:]
+  private var campaignFetchInProgress:       [String: Bool]         = [:]
+  private var campaignFetched:              [String: Bool]         = [:]
 
   // MARK: - Init
 
@@ -593,7 +596,7 @@ public class SpotnyBeaconScanner: NSObject {
     if isImpression { impressionEventInProgress[key] = true }
     else            { proximityEventInProgress[key]  = true }
 
-    // Build payload — all events now use beacon_id, backend resolves screen_id
+    // Build payload — proximity events send beacon_id only, impressions include campaign data
     var payload: [String: Any] = [
       "event_type": eventType,
       "beacon_id":  key,
@@ -608,14 +611,9 @@ public class SpotnyBeaconScanner: NSObject {
         impressionEventInProgress[key] = false
         return
       }
+      payload["screen_id"] = campaign.screenId
       if let cid = campaign.campaignId { payload["campaign_id"] = cid }
       if let sid = campaign.sessionId  { payload["session_id"]  = sid }
-    } else {
-      // Proximity events also send campaign/session if available
-      if let campaign = activeCampaigns[key] {
-        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
@@ -625,43 +623,6 @@ public class SpotnyBeaconScanner: NSObject {
         if 200...299 ~= status {
           print("✅ SpotnySDK: \(eventType) sent — distance \(String(format: "%.2f", distance))m")
           logToFile("✅ \(eventType) sent — beacon \(key) @ \(String(format: "%.2f", distance))m")
-          
-          // Parse campaign_id, session_id from proximity response
-          if !isImpression,
-             let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
-             let dObj = json["data"] as? [String: Any] {
-            
-            var campaignId: Int?
-            var sessionId: String?
-            var inQueue = false
-            
-            // Extract session_id from event object
-            if let ev = dObj["event"] as? [String: Any] {
-              sessionId = ev["session_id"] as? String
-            }
-            
-            // Extract from campaign object
-            if let campaignObj = dObj["campaign"] as? [String: Any] {
-              campaignId = campaignObj["id"] as? Int
-              inQueue = campaignObj["inQueue"] as? Bool ?? false
-            }
-            
-            // Store campaign data
-            // Parse major/minor from key
-            let parts = key.components(separatedBy: "_")
-            let major = parts.count > 0 ? Int(parts[0]) ?? 0 : 0
-            let minor = parts.count > 1 ? Int(parts[1]) ?? 0 : 0
-            
-            let updated = CampaignData(
-              campaignId: campaignId,
-              sessionId: sessionId,
-              inQueue: inQueue,
-              major: major,
-              minor: minor
-            )
-            self.activeCampaigns[key] = updated
-            print("✅ SpotnySDK: Stored campaign — campaignId=\(campaignId ?? 0), sessionId=\(sessionId ?? "nil"), inQueue=\(inQueue)")
-          }
         } else if status == 429 {
           let penalty = Date().addingTimeInterval(10)
           if isImpression { self.lastImpressionEventSent[key] = penalty }
@@ -678,6 +639,63 @@ public class SpotnyBeaconScanner: NSObject {
     }
   }
 
+  private func fetchCampaign(key: String, major: Int, minor: Int) {
+    guard campaignFetchInProgress[key] != true else { return }
+    guard campaignFetched[key] != true else { return }
+    
+    campaignFetchInProgress[key] = true
+    
+    let payload: [String: Any] = ["beacon_id": key]
+    
+    post(endpoint: "\(apiBasePath)/distribute", payload: payload) { [weak self] result in
+      guard let self = self else { return }
+      self.campaignFetchInProgress[key] = false
+      
+      switch result {
+      case .success(let (status, data)):
+        if 200...299 ~= status {
+          guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+                let dObj = json["data"] as? [String: Any] else {
+            print("⚠️ SpotnySDK: Campaign fetch — invalid response format")
+            return
+          }
+          
+          var screenId: Int = 0
+          var campaignId: Int?
+          var sessionId: String?
+          var inQueue = false
+          
+          if let sid = dObj["screen_id"] as? Int {
+            screenId = sid
+          }
+          
+          if let campaignObj = dObj["campaign"] as? [String: Any] {
+            campaignId = campaignObj["id"] as? Int
+            sessionId = campaignObj["session_id"] as? String
+            inQueue = campaignObj["inQueue"] as? Bool ?? false
+          }
+          
+          let campaign = CampaignData(
+            screenId: screenId,
+            campaignId: campaignId,
+            sessionId: sessionId,
+            inQueue: inQueue,
+            major: major,
+            minor: minor
+          )
+          self.activeCampaigns[key] = campaign
+          self.campaignFetched[key] = true
+          
+          print("✅ SpotnySDK: Campaign fetched — screenId=\(screenId), campaignId=\(campaignId ?? 0), sessionId=\(sessionId ?? "nil"), inQueue=\(inQueue)")
+        } else {
+          print("❌ SpotnySDK: Campaign fetch failed — status \(status)")
+        }
+      case .failure(let error):
+        print("❌ SpotnySDK: Campaign fetch error — \(error.localizedDescription)")
+      }
+    }
+  }
+
   private func sendProximity(eventType: String, key: String, distance: Double) {
     sendTracking(eventType: eventType, key: key, distance: distance,
                  endpoint: "\(apiBasePath)/proximity")
@@ -698,6 +716,8 @@ public class SpotnyBeaconScanner: NSObject {
     lastImpressionEventSent.removeValue(forKey: key)
     proximityEventInProgress.removeValue(forKey: key)
     impressionEventInProgress.removeValue(forKey: key)
+    campaignFetchInProgress.removeValue(forKey: key)
+    campaignFetched.removeValue(forKey: key)
     print("🧹 SpotnySDK: Cleaned up state for beacon \(key)")
   }
 
@@ -800,6 +820,11 @@ extension SpotnyBeaconScanner: KTKBeaconManagerDelegate {
         lastProximityDistance[key] = distance
         lastProximityEventSent[key] = now
       }
+      
+      // Fetch campaign when distance <= 3m
+      if distance <= 3.0 && campaignFetched[key] != true {
+        fetchCampaign(key: key, major: major, minor: minor)
+      }
 
       // Impression heartbeat when user is very close AND campaign exists
       if let campaign = activeCampaigns[key],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spotny-sdk",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Beacon Scanner",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",