Tracking lifecycle

Tracking has two flags you can read from getStatus():

• desired: you asked for tracking with startTracking() and have not called stopTracking(). It is persisted, so it survives process death and reboots.
• running: the native pipeline is collecting points right now.

Most of the time both are true or both are false. When desired is true but running is false, the tracker is waiting to recover, for example after the OS killed the process. It restarts on its own as soon as the platform allows.

Starting

LocationTracker.startTracking('https://api.example.com');

startTracking(serverUrl):

1. Persists serverUrl, so background restarts know where to send points.
2. Sets desired = true.
3. Starts location collection with the current tracking profile.
4. Arms the watchdog that revives tracking after process death, reboot or app update.

It returns immediately (void). Watch onSyncStatus or poll getStatus() to confirm that running became true. If location permission is missing, tracking does not start and message begins with [permission_denied].

Calling startTracking() again while tracking is safe. Use it to change the server URL.

While tracking

• Each accepted fix is saved on the device, then emitted through onLocationUpdate.
• On every sync tick (30 seconds, or 5 seconds in demo mode) pending points upload in batches. See Offline tracking and sync.
• Connectivity, queue and retry changes are emitted through onSyncStatus.
• You can change the profile live with setTrackingProfile(). No restart is needed.

Your JavaScript does not need to be running for tracking to work. When the app is in the background or killed, the native side keeps collecting and syncing. JS listeners just receive events whenever the JS runtime is alive.

Stopping

LocationTracker.stopTracking();

stopTracking():

1. Sets desired = false and cancels the watchdog, so nothing revives tracking.
2. Attempts a final flush of pending points.
3. Stops collection.

Points that could not be uploaded stay on the device. They are sent the next time you call startTracking(). Stopping never deletes data.

Recovery behavior

Event	What happens when desired is true
App backgrounded	Tracking continues.
App swiped away from recents	Tracking continues. Android keeps its foreground notification; iOS relaunches the app in the background on movement.
Process killed by the OS for memory	The watchdog revives tracking.
Device reboot	Tracking resumes after boot. iOS needs the user to unlock the device once and to have granted Always permission.
App updated from the store	Tracking resumes after the update.
User force-stops the app (Android)	Tracking stops and cannot restart until the user opens the app again. This is an Android rule. See limitations.
Location permission revoked	Tracking stops with [permission_denied]. Ask for permission again, then call startTracking().

Reading the lifecycle from JS

const s = LocationTracker.getStatus();

if (s.desired && !s.running) {
  // Recovering, or blocked. Check s.message and s.authorization.
}
if (!s.desired && s.pending > 0) {
  // Stopped with points still on the device. They upload on the next start.
}

On app launch, read getStatus().desired to restore your UI state rather than keeping your own flag. The native value is the source of truth.