@expofp/react-native-efp-crowdconnected 0.1.8 → 0.1.9

package/ExpofpCrowdconnected.podspec

@@ -10,7 +10,7 @@ Pod::Spec.new do |s|
   s.license      = package["license"]
   s.authors      = package["author"]
 
-  s.platforms    = { :ios => min_ios_version_supported }
+  s.platforms    = { :ios => '16.0' }
   s.source       = { :git => "https://github.com/expofp/react-native-crowdconnected.git", :tag => "#{s.version}" }
 
   s.source_files = "ios/**/*.{h,m,mm,cpp,swift}"

package/README.md

@@ -19,7 +19,7 @@ React Native Turbo Module for CrowdConnected location tracking and indoor positi
 ## Requirements
 
 - Android 7.0+ (API level 24+)
-- iOS minimum version follows your React Native installation
+- iOS 16.0+ (required by the bundled CrowdConnected SDK)
 
 ## Installation
 
@@ -59,8 +59,8 @@ import { CrowdConnectedLocationProvider } from '@expofp/react-native-efp-crowdco
 // Initialize
 await CrowdConnectedLocationProvider.setup({
   appKey: 'your-app-key',
-  token: 'your-token',
-  secret: 'your-secret',
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
   navigationType: 'all', // 'all' | 'GEO' | 'IPS'
   isBackgroundUpdateEnabled: false,
   isBluetoothEnabled: true,
@@ -100,8 +100,8 @@ Initializes the CrowdConnected SDK with configuration.
 
 **Parameters:**
 - `appKey` - CrowdConnected application key
-- `token` - Authentication token
-- `secret` - Authentication secret
+- `clientId` - CrowdConnected client ID
+- `clientSecret` - CrowdConnected client secret
 - `navigationType` - Positioning type: `'all'` (GPS + IPS), `'GEO'` (GPS only), `'IPS'` (indoor only)
 - `isBackgroundUpdateEnabled` - Enable background location updates
 - `isBluetoothEnabled` - Enable Bluetooth-based positioning
@@ -156,6 +156,68 @@ Subscribes to location errors.
 
 **Returns:** Unsubscribe function
 
+## Simulation Mode
+
+Simulation mode replays GPS/IPS paths on the device without physical movement. Simulated positions arrive through the regular `onLocationChange` listener.
+
+```typescript
+const simulationToken = '<signed JWT for the simulation session>';
+
+// The SDK must already be started (startUpdatingLocation) before activating.
+const unsubConnected = CrowdConnectedLocationProvider.onSimulationConnected(() => {
+  console.log('Simulation connected');
+});
+const unsubDisconnected = CrowdConnectedLocationProvider.onSimulationDisconnected(() => {
+  console.log('Simulation disconnected');
+});
+const unsubError = CrowdConnectedLocationProvider.onSimulationError((error) => {
+  console.error('Simulation error:', error.message);
+});
+
+CrowdConnectedLocationProvider.activateSimulation(simulationToken);
+
+// ...later
+CrowdConnectedLocationProvider.deactivateSimulation();
+
+// Cleanup
+unsubConnected();
+unsubDisconnected();
+unsubError();
+```
+
+### `activateSimulation(token: string): void`
+
+Starts a simulation session. Fire-and-forget: the outcome is reported via the `onSimulationConnected` / `onSimulationError` events.
+
+- `token` - A signed JWT issued for the simulation session (contains the `sid` session ID and `exp` claims)
+- The SDK must already be started via `startUpdatingLocation()`
+- Calling it again replaces the current session
+- Deactivate the simulation before calling `stopUpdatingLocation()` when a session is active
+
+---
+
+### `deactivateSimulation(): void`
+
+Stops the active simulation session. Safe no-op when no session is active.
+
+---
+
+### `onSimulationConnected(callback: () => void): Unsubscribe`
+
+Fires when the simulation session is established.
+
+---
+
+### `onSimulationDisconnected(callback: () => void): Unsubscribe`
+
+Fires when the simulation session ends.
+
+---
+
+### `onSimulationError(callback: (error: Error) => void): Unsubscribe`
+
+Fires when the simulation session fails (e.g. invalid or expired token).
+
 ## Development
 
 ### Setup

package/android/build.gradle

@@ -80,8 +80,8 @@ dependencies {
   implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2"
   implementation "androidx.fragment:fragment-ktx:1.6.2"
 
-  implementation "net.crowdconnected.android.core:android-core:3.0.0"
-  implementation "net.crowdconnected.android.ips:android-ips:3.0.0"
-  implementation "net.crowdconnected.android.geo:android-geo:3.0.0"
-  implementation "net.crowdconnected.android.background:android-background:3.0.0"
+  implementation "net.crowdconnected.android.core:android-core:3.1.0"
+  implementation "net.crowdconnected.android.ips:android-ips:3.1.0"
+  implementation "net.crowdconnected.android.geo:android-geo:3.1.0"
+  implementation "net.crowdconnected.android.background:android-background:3.1.0"
 }

package/android/src/main/java/com/expofpcrowdconnected/ExpoFpCrowdConnectedLocationProviderSettings.kt

@@ -25,23 +25,22 @@ enum class ExpoFpCrowdConnectedNavigationType {
 
 /**
  * Settings for CrowdConnected location provider
- * Maps to ExpoFpLocationSettings TypeScript interface.
- *
- * Note: since CrowdConnected SDK v3.0.0, the authentication scheme changed.
- * The JS-facing fields `token` and `secret` are kept for API compatibility, but
- * internally they are passed to the v3 SDK as `clientId` and `clientSecret`
- * via `Configuration.builder().withCredentials(appKey, token, secret)`.
+ * Maps 1:1 to the ExpoFpLocationSettings TypeScript interface (src/types.ts);
+ * credentials are passed to the v3 SDK via
+ * `Configuration.builder().withCredentials(appKey, clientId, clientSecret)`.
  */
 data class ExpoFpCrowdConnectedLocationProviderSettings(
     val appKey: String,
-    /** Passed to CrowdConnected v3 SDK as client ID (exposed as `token` in JS for backward compatibility). */
-    val token: String,
-    /** Passed to CrowdConnected v3 SDK as client secret (exposed as `secret` in JS for backward compatibility). */
-    val secret: String,
+    /** CrowdConnected v3 client ID. */
+    val clientId: String,
+    /** CrowdConnected v3 client secret. */
+    val clientSecret: String,
     val navigationType: ExpoFpCrowdConnectedNavigationType = ExpoFpCrowdConnectedNavigationType.ALL,
     val isBackgroundUpdateEnabled: Boolean = false,
     val isBluetoothEnabled: Boolean = false,
     val isHeadingEnabled: Boolean = false,
+    /** When true, the SDK is switched to low-power GPS mode right after start. */
+    val isLowPowerModeEnabled: Boolean = false,
     val aliases: Map<String, String> = emptyMap()
 ) {
     /**
@@ -53,11 +52,11 @@ data class ExpoFpCrowdConnectedLocationProviderSettings(
         if (appKey.isBlank()) {
             throw IllegalArgumentException("appKey cannot be blank")
         }
-        if (token.isBlank()) {
-            throw IllegalArgumentException("token cannot be blank")
+        if (clientId.isBlank()) {
+            throw IllegalArgumentException("clientId cannot be blank")
         }
-        if (secret.isBlank()) {
-            throw IllegalArgumentException("secret cannot be blank")
+        if (clientSecret.isBlank()) {
+            throw IllegalArgumentException("clientSecret cannot be blank")
         }
 
         // Validate background requirements
@@ -86,12 +85,12 @@ data class ExpoFpCrowdConnectedLocationProviderSettings(
             val appKey = map.getString("appKey")
                 ?.trim()
                 ?: throw IllegalArgumentException("appKey is required")
-            val token = map.getString("token")
+            val clientId = map.getString("clientId")
                 ?.trim()
-                ?: throw IllegalArgumentException("token is required")
-            val secret = map.getString("secret")
+                ?: throw IllegalArgumentException("clientId is required")
+            val clientSecret = map.getString("clientSecret")
                 ?.trim()
-                ?: throw IllegalArgumentException("secret is required")
+                ?: throw IllegalArgumentException("clientSecret is required")
 
             // Optional fields
             val navigationType = ExpoFpCrowdConnectedNavigationType.fromString(
@@ -109,6 +108,10 @@ data class ExpoFpCrowdConnectedLocationProviderSettings(
                 map.getBoolean("isHeadingEnabled")
             } else false
 
+            val isLowPowerModeEnabled = if (map.hasKey("isLowPowerModeEnabled")) {
+                map.getBoolean("isLowPowerModeEnabled")
+            } else false
+
             // Parse aliases map
             val aliases = if (map.hasKey("aliases")) {
                 val aliasesMap = map.getMap("aliases")
@@ -125,12 +128,13 @@ data class ExpoFpCrowdConnectedLocationProviderSettings(
 
             val settings = ExpoFpCrowdConnectedLocationProviderSettings(
                 appKey = appKey,
-                token = token,
-                secret = secret,
+                clientId = clientId,
+                clientSecret = clientSecret,
                 navigationType = navigationType,
                 isBackgroundUpdateEnabled = isBackgroundUpdateEnabled,
                 isBluetoothEnabled = isBluetoothEnabled,
                 isHeadingEnabled = isHeadingEnabled,
+                isLowPowerModeEnabled = isLowPowerModeEnabled,
                 aliases = aliases
             )
 

package/android/src/main/java/com/expofpcrowdconnected/RCTCrowdConnectedLocationProviderModule.kt

@@ -32,6 +32,7 @@ import net.crowdconnected.android.core.Configuration
 import net.crowdconnected.android.core.CrowdConnected
 import net.crowdconnected.android.core.ErrorCode
 import net.crowdconnected.android.core.Location
+import net.crowdconnected.android.core.SimulationCallback
 import net.crowdconnected.android.background.BackgroundModule
 import net.crowdconnected.android.geo.GeoModule
 import net.crowdconnected.android.ips.IPSModule
@@ -47,8 +48,10 @@ class PermissionDeniedException(
 
 /**
  * React Native module for CrowdConnected location provider
- * Provides cross-platform API: setup, startUpdatingLocation, stopUpdatingLocation, isLocationUpdating
- * Emits events: onLocationChange, onLocationError
+ * Provides cross-platform API: setup, startUpdatingLocation, stopUpdatingLocation,
+ * isLocationUpdating, activateSimulation, deactivateSimulation
+ * Emits events: onLocationChange, onLocationError,
+ * onSimulationConnected, onSimulationDisconnected, onSimulationError
  */
 class RCTCrowdConnectedLocationProviderModule(
     reactContext: ReactApplicationContext
@@ -59,6 +62,9 @@ class RCTCrowdConnectedLocationProviderModule(
         private const val TAG = "RCTCrowdConnected"
         private const val EVENT_LOCATION_CHANGE = "onLocationChange"
         private const val EVENT_LOCATION_ERROR = "onLocationError"
+        private const val EVENT_SIMULATION_CONNECTED = "onSimulationConnected"
+        private const val EVENT_SIMULATION_DISCONNECTED = "onSimulationDisconnected"
+        private const val EVENT_SIMULATION_ERROR = "onSimulationError"
         private const val TIMEOUT_DURATION_MS = 65_000L // 65 seconds timeout for SDK startup
 
         // Foreground service notification
@@ -140,6 +146,28 @@ class RCTCrowdConnectedLocationProviderModule(
     @Volatile private var azimuthProvider: ExpoFpAzimuthProvider? = null
     @Volatile private var isStarted = false
 
+    /**
+     * Receives simulation lifecycle events from the CrowdConnected SDK.
+     * The SDK may invoke these on a background thread, so each event hops to the
+     * main thread via moduleScope before emitting to JavaScript.
+     */
+    private val simulationCallback = object : SimulationCallback {
+        override fun onSimulationConnected() {
+            Log.d(TAG, "SimulationCallback.onSimulationConnected")
+            sendSimulationEvent(EVENT_SIMULATION_CONNECTED, null)
+        }
+
+        override fun onSimulationDisconnected() {
+            Log.d(TAG, "SimulationCallback.onSimulationDisconnected")
+            sendSimulationEvent(EVENT_SIMULATION_DISCONNECTED, null)
+        }
+
+        override fun onSimulationError(reason: String) {
+            Log.e(TAG, "SimulationCallback.onSimulationError: $reason")
+            sendSimulationEvent(EVENT_SIMULATION_ERROR, reason)
+        }
+    }
+
     override fun getName(): String = MODULE_NAME
 
     /**
@@ -252,6 +280,53 @@ class RCTCrowdConnectedLocationProviderModule(
         }
     }
 
+    /**
+     * Start a simulation session. The SDK must already be started
+     * (startUpdatingLocation); otherwise onSimulationError is emitted and the
+     * call is a no-op. Calling again replaces the current session.
+     * Fire-and-forget: results are reported via onSimulationConnected /
+     * onSimulationError events.
+     */
+    @ReactMethod
+    fun activateSimulation(token: String) {
+        Log.d(TAG, "activateSimulation")
+        // Without a running SDK instance the call is silently swallowed by the
+        // SDK — surface it to JS instead.
+        if (CrowdConnected.getInstance() == null) {
+            sendSimulationEvent(EVENT_SIMULATION_ERROR, "CrowdConnected is not running")
+            return
+        }
+        // runCatching is a crash barrier only: an uncaught exception in a
+        // @ReactMethod takes down the app; failures surface as onSimulationError.
+        runCatching { CrowdConnected.activateSimulation(token, simulationCallback) }
+            .onFailure {
+                Log.e(TAG, "activateSimulation failed", it)
+                sendSimulationEvent(EVENT_SIMULATION_ERROR, it.message ?: "Failed to activate simulation")
+            }
+    }
+
+    /**
+     * Stop the active simulation session. Safe no-op when none is active.
+     */
+    @ReactMethod
+    fun deactivateSimulation() {
+        Log.d(TAG, "deactivateSimulation")
+        runCatching { CrowdConnected.deactivateSimulation() }
+            .onFailure { Log.e(TAG, "deactivateSimulation failed", it) }
+    }
+
+    /**
+     * Manually toggle low-power GPS mode at runtime: true drops to low-frequency,
+     * battery-saving mode; false restores high-frequency navigation mode.
+     * Safe no-op when the SDK is not currently running (getInstance() == null).
+     */
+    @ReactMethod
+    fun setLowPowerMode(enabled: Boolean) {
+        Log.d(TAG, "setLowPowerMode: $enabled")
+        runCatching { CrowdConnected.getInstance()?.setLowPowerMode(enabled) }
+            .onFailure { Log.e(TAG, "setLowPowerMode failed", it) }
+    }
+
     /**
      * Ensures all required permissions are granted, requesting them from the user if necessary.
      * Must be called OUTSIDE the mutex to avoid blocking other module operations
@@ -423,6 +498,15 @@ class RCTCrowdConnectedLocationProviderModule(
                         }
                     }
                 }
+
+                // Force low-power mode on start when requested. Only act when enabled —
+                // when false we leave the SDK's automatic frequency management untouched.
+                // Reachable here for the same reason as setAlias: getInstance() is null before start.
+                if (currentSettings.isLowPowerModeEnabled) {
+                    Log.d(TAG, "Applying low-power mode on start")
+                    runCatching { CrowdConnected.getInstance()?.setLowPowerMode(true) }
+                        .onFailure { Log.w(TAG, "setLowPowerMode(startup) failed: ${it.message}") }
+                }
             }
 
             override fun onStartFailure(errorCode: ErrorCode) {
@@ -462,12 +546,10 @@ class RCTCrowdConnectedLocationProviderModule(
         val app = reactApplicationContext.applicationContext as Application
         val builder = Configuration.builder()
             .withContext(app)
-            // v3 SDK credentials — JS-level `token`/`secret` fields are passed through
-            // as the SDK's clientId/clientSecret for backward-compatible API.
             .withCredentials(
                 currentSettings.appKey,
-                currentSettings.token,
-                currentSettings.secret
+                currentSettings.clientId,
+                currentSettings.clientSecret
             )
             .withCallback(callback)
 
@@ -533,6 +615,12 @@ class RCTCrowdConnectedLocationProviderModule(
         isStarted = false
         providerInfo = providerInfo.copy(isLocationUpdating = false)
 
+        // End any active simulation session before stopping: the SDK retains
+        // simulation callbacks for the lifetime of the session even across
+        // stop(). Safe no-op when no session is active.
+        runCatching { CrowdConnected.deactivateSimulation() }
+            .onFailure { Log.w(TAG, "stopUpdatingLocationInternal: deactivateSimulation failed", it) }
+
         // Stop CrowdConnected SDK (v3: static, idempotent — wrap for safety)
         Log.d(TAG, "stopUpdatingLocationInternal: Stopping CrowdConnected SDK")
         runCatching { CrowdConnected.stop() }
@@ -584,6 +672,24 @@ class RCTCrowdConnectedLocationProviderModule(
         }
     }
 
+    /**
+     * Send a simulation lifecycle event to JavaScript.
+     * Body is null for connected/disconnected and the raw reason string for
+     * errors. Not routed through sendErrorEvent, which appends a Device ID
+     * suffix and emits onLocationError.
+     */
+    private fun sendSimulationEvent(eventName: String, body: String?) {
+        moduleScope.launch {
+            try {
+                reactApplicationContext
+                    .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+                    ?.emit(eventName, body)
+            } catch (e: Exception) {
+                Log.e(TAG, "Failed to send $eventName event to JavaScript", e)
+            }
+        }
+    }
+
     /**
      * Start timeout job that will stop SDK if it doesn't respond in time
      * Uses 65 second timeout for SDK startup

package/ios/ExpoFpLocationProvider/ExpoFpCrowdConnectedLocationProviderSettings.swift

@@ -34,10 +34,10 @@ struct ExpoFpCrowdConnectedLocationProviderSettings {
     let appKey = settings.appKey.replacingOccurrences(of: " ", with: "")
     if appKey.isEmpty { throw ExpoFpError.locationProviderError(message: Self.message(for: .missingAppKey)) }
 
-    let clientId = settings.token.replacingOccurrences(of: " ", with: "")
+    let clientId = settings.clientId.replacingOccurrences(of: " ", with: "")
     if clientId.isEmpty { throw ExpoFpError.locationProviderError(message: Self.message(for: .missingToken)) }
 
-    let clientSecret = settings.secret.replacingOccurrences(of: " ", with: "")
+    let clientSecret = settings.clientSecret.replacingOccurrences(of: " ", with: "")
     if clientSecret.isEmpty { throw ExpoFpError.locationProviderError(message: Self.message(for: .missingSecret)) }
 
     self.credentials = Credentials(appKey: appKey, clientId: clientId, clientSecret: clientSecret)

package/ios/ExpoFpLocationProvider/ExpoFpLocationSettings.swift

@@ -8,8 +8,8 @@
 
 struct ExpoFpLocationSettings: Codable {
   let appKey: String
-  let token: String
-  let secret: String
+  let clientId: String
+  let clientSecret: String
   let navigationType: ExpoFpCrowdConnectedNavigationType
   let isBackgroundUpdateEnabled: Bool
   let isBluetoothEnabled: Bool

package/ios/ExpoFpLocationProvider/ExpoFpSimulationDelegate.swift

@@ -0,0 +1,40 @@
+//
+//  ExpoFpSimulationDelegate.swift
+//  ExpofpCrowdconnected
+//
+//  Created by Nikita Kolesnikov on 09.07.2026.
+//
+
+import CrowdConnectedCore
+import Foundation
+
+/// Receives simulation lifecycle events from the CrowdConnected SDK.
+///
+/// The SDK invokes these callbacks on a background thread, so every event is
+/// marshalled onto the main actor before touching the (`@MainActor`) provider
+/// and emitting a React Native event.
+final class ExpoFpSimulationDelegate: SimulationCallback {
+
+  weak var provider: RCTCrowdConnectedLocationProvider?
+
+  func onSimulationConnected() {
+    Task { @MainActor in
+      guard let provider else { return }
+      provider.sendEvent(withName: provider.onSimulationConnectedName, body: nil)
+    }
+  }
+
+  func onSimulationDisconnected() {
+    Task { @MainActor in
+      guard let provider else { return }
+      provider.sendEvent(withName: provider.onSimulationDisconnectedName, body: nil)
+    }
+  }
+
+  func onSimulationError(reason: String) {
+    Task { @MainActor in
+      guard let provider else { return }
+      provider.sendEvent(withName: provider.onSimulationErrorName, body: reason)
+    }
+  }
+}

package/ios/Frameworks/CrowdConnectedCore.xcframework/ios-arm64/CrowdConnectedCore.framework/Headers/CrowdConnectedCore-Swift.h

@@ -631,6 +631,35 @@ SWIFT_CLASS_PROPERTY(@property (nonatomic, class, readonly, strong) CrowdConnect
 - (Configuration * _Nullable)getCurrentConfiguration SWIFT_WARN_UNUSED_RESULT;
 @end
 
+@protocol SimulationCallback;
+@interface CrowdConnected (SWIFT_EXTENSION(CrowdConnectedCore))
+/// Activates a simulation session using the provided JWT token.
+/// The SDK must already be started before calling this method.
+/// A second call replaces any existing session (the previous one is deactivated first).
+/// since:
+/// 3.1.0
+/// \param token A signed JWT containing the <code>sid</code> (session ID) and <code>exp</code> claims.
+///
+- (void)activateSimulationWithToken:(NSString * _Nonnull)token;
+/// Activates a simulation session with an optional callback for session events.
+/// The SDK must already be started before calling this method.
+/// A second call replaces any existing session (the previous one is deactivated first).
+/// All callbacks fire on a background thread — marshal to the main thread if you need to update UI.
+/// since:
+/// 3.1.0
+/// \param token A signed JWT containing the <code>sid</code> (session ID) and <code>exp</code> claims.
+///
+/// \param callback An optional object that receives connection, error, and disconnection events.
+///
+- (void)activateSimulationWithToken:(NSString * _Nonnull)token callback:(id <SimulationCallback> _Nullable)callback;
+/// Stops any active simulation session.
+/// Safe to call at any time, including when no session is active.
+/// <code>onSimulationDisconnected</code> is <em>not</em> called when you stop the session explicitly.
+/// since:
+/// 3.1.0
+- (void)deactivateSimulation;
+@end
+
 enum ErrorCode : NSInteger;
 /// A delegate protocol for receiving callbacks from the CrowdConnected SDK.
 /// Implement this protocol to receive location updates, success notifications, and error callbacks from the SDK.
@@ -753,6 +782,25 @@ typedef SWIFT_ENUM(NSInteger, Module, open) {
   ModuleCoreBluetooth = 2,
 };
 
+/// Receives lifecycle events from an active simulation session.
+/// All methods are called on a background thread.
+/// Marshal to the main thread if you need to update UI.
+/// since:
+/// 3.1.0
+SWIFT_PROTOCOL("_TtP18CrowdConnectedCore18SimulationCallback_")
+@protocol SimulationCallback
+/// The AppSync subscription is live and simulation events will begin flowing.
+- (void)onSimulationConnected;
+/// A connection or subscription problem occurred (network error, expired token, invalid session, etc.).
+/// \param reason A human-readable description of the failure.
+///
+- (void)onSimulationErrorWithReason:(NSString * _Nonnull)reason;
+/// The session ended — either the server sent <code>SESSION_ENDED</code>, the subscription completed,
+/// or the WebSocket closed unexpectedly.
+/// Not called when you explicitly call <code>deactivateSimulation()</code>.
+- (void)onSimulationDisconnected;
+@end
+
 #endif
 #if __has_attribute(external_source_symbol)
 # pragma clang attribute pop