Skip to content

Philosophy of Operation

The SDK is motion-driven, not interval-based. It does not fire location updates on a fixed schedule. Instead it watches the device's motion state and requests GPS only when the device is actually moving. This is the central design decision that makes continuous background tracking viable on a battery-powered device.

Two States

The SDK operates in exactly two states at any given time:

Stationary — The device is not moving. The SDK holds a reference position and monitors for motion using the accelerometer and activity-recognition API. No GPS is requested. Power consumption is negligible.

Moving — Motion has been confirmed. The SDK requests location updates from the OS according to your distanceFilter and desiredAccuracy settings. Locations are recorded and uploaded continuously.

Transitions between the two states are automatic. You do not manage them manually.

Entering Moving State

When the device is stationary, the SDK listens to the platform's activity-recognition API (Core Motion on iOS, the Activity Recognition API on Android). When significant motion is detected — walking, running, cycling, in a vehicle — the SDK confirms it against the motionTriggerDelay window and transitions to moving state.

On iOS, a supplementary mechanism is active while the app is terminated: the OS places a stationary geofence of stationaryRadius metres (default 150 m) around the last known position. When the device exits that geofence (~200 m of movement), iOS silently relaunches the app in the background and tracking resumes. This is an OS-level capability that requires no extra configuration beyond stopOnTerminate: false.

Entering Stationary State

While moving, the SDK evaluates whether the device has stopped. A stop is confirmed only after the device has been stationary for stopTimeout minutes (default 5). This grace period prevents false stops at traffic lights, short pauses, or slow-speed crawl. Once confirmed, the SDK releases GPS, records the stop position, and returns to stationary monitoring.

The activity.stopDetectionDelay setting adds an additional delay before stop-detection even begins evaluating, which is useful for vehicle tracking where brief parking should not be treated as a trip end.

Distance Filter & Elasticity

While moving, a new location is recorded only after the device has displaced at least distanceFilter metres from the last recorded position. This prevents redundant back-to-back samples when the device is moving slowly.

At higher speeds the SDK automatically scales distanceFilter upward in proportion to speed — the faster the vehicle, the farther it must travel before another sample is taken. This elasticity keeps the sample rate approximately constant in time rather than exploding at highway speeds. Disable it with geolocation.disableElasticity: true if you need a fixed spatial resolution regardless of speed.

Persist First, Upload Second

Every location is written to an on-device SQLite database before any upload attempt. The HTTP service then reads from that queue and posts to your configured http.url. If the network is unavailable, records accumulate locally and are retried automatically when connectivity is restored. No location is ever lost to a network failure.

This architecture was designed for disaster-response deployments where cellular coverage is assumed unreliable.

What the SDK Does Not Do

  • It does not poll on a fixed timer.
  • It does not use CLLocationManager.startUpdatingLocation continuously in the background (iOS).
  • It does not keep a wakelock permanently held (Android).
  • It does not require the screen to be on.
  • It does not bypass the OS's power-management policies — it works with them.