Tracking lifecycle

Once start() is called, the SDK is always in exactly one of two motion states — MOVING or STATIONARY — and almost everything else in the SDK (GPS power draw, fix density, which native services stay armed) is a consequence of that one bit. This is the core mental model for the whole tracker: most “why is battery draining” or “why did I get no points for 10 minutes” questions are really “which state was the device in, and what wakes it out of stationary.”

The split exists because full-rate GPS and battery life are directly opposed:

• MOVING — GPS runs at full rate, spaced by the (speed-elastic) distanceFilter at desiredAccuracy. This is expensive but necessary: a route is only useful if it’s dense enough to reconstruct.
• STATIONARY — GPS is, for practical purposes, asleep. A low-power keep-alive stream (see stationaryKeepAlive) and a stationary geofence around the last stopped fix are what’s left running. There is no reason to keep drawing moving-grade power for a device that hasn’t moved.

The state machine

stateDiagram-v2
    [*] --> STATIONARY
    STATIONARY --> MOVING: activity recognition
    STATIONARY --> MOVING: speed threshold
    STATIONARY --> MOVING: stationaryRadius exit
    STATIONARY --> MOVING: changePace(true)
    MOVING --> STATIONARY: still + stopTimeout → stop record

A tracking session starts in STATIONARY (there’s no fix yet to prove movement). Four independent signals can trigger STATIONARY → MOVING, and any one of them is sufficient:

• Activity recognition says a moving-type activity (in_vehicle, on_bicycle, on_foot, running, walking by default — see triggerActivities) is happening, at or above the platform’s confidence bar.
• Speed threshold — a raw fix implies real ground speed, independent of activity recognition. This is also the fallback path when activity recognition is disabled (disableMotionActivityUpdates) or has gone stale.
• Stationary-geofence exit — a raw fix whose distance from the stop anchor clears stationaryRadius wakes tracking immediately, without waiting on activity recognition at all.
• changePace(true) — an explicit app-driven override of the automatic machine.

The reverse transition, MOVING → STATIONARY, has exactly one path: a confident still verdict has to be sustained for stopTimeout before the machine commits. Committing writes a stop record (an isMoving: false onMotionChange event), re-arms the stationary geofence around the stop point, and drops GPS to the stationary power profile.

Stop detection

Getting to STATIONARY is deliberately harder than getting to MOVING, because a false stop costs GPS density on a genuinely still-moving route, while a missed stop only costs a few extra minutes of moving-power draw. The mechanics:

• Countdown, not a snapshot. A confident still verdict arms a stopTimeout countdown rather than stopping immediately. If the countdown is already armed, a fresh still verdict does not restart it — only the original arm time matters, so the timer can’t be indefinitely postponed by repeated still updates.
• Two vetoes can cancel a pending stop, both independent of activity recognition: a raw displacement of more than 50 m from the point where the countdown was armed cancels it outright (the device evidently never actually stopped), and — once the device is parked — a raw fix whose distance from the stop anchor clears stationaryRadius wakes tracking again. That second check runs ahead of the normal accuracy filter, because the stationary keep-alive stream is intentionally coarse.
• Motion classification is tri-state, not boolean. Only a confident still verdict is allowed to arm a stop; low-confidence walking/unknown readings are treated as genuinely uncertain rather than rounded to “not moving.” A gap in raw fixes triggers recovery logic, never a stationary decision by itself — the machine never infers “stopped” from silence alone.

Wake sources

While STATIONARY, GPS is asleep but the platform is not idle — a small set of native services stays armed specifically to detect departure without full-rate GPS.

Source	Role
Foreground service	Always running while tracking is enabled; restarts itself via onTaskRemoved if the task is swiped away.
Play activity recognition	Drives the moving-activity trigger above; falls back to speed-based detection if it goes stale.
Stationary geofence	A stationaryRadius-sized region around the stop anchor; its exit is the departure trigger that does not wait on activity recognition.
Boot receiver	Restarts the service on BOOT_COMPLETED/LOCKED_BOOT_COMPLETED when startOnBoot is set and tracking was enabled.

onMotionChange fires at every transition

onMotionChange is the one event that fires at both edges of the state machine — isMoving: true on STATIONARY → MOVING, isMoving: false on MOVING → STATIONARY (including changePace()-forced transitions). Watch for the very first motionchange of a tracking session: it fires from the initial moving-probe ahead of any fix, so location can be null — don’t assume it’s always populated.

Kill, force-quit, and reboot

The wake sources above double as the SDK’s resilience against the app being killed. The foreground service, onTaskRemoved and startOnBoot restart tracking deterministically after most kill paths and after a reboot.

A native app needs no headless registration to benefit from this — unlike the React Native and Flutter SDKs, where the JS context and the Dart isolate die with the app. Android restarts your process and calls Application.onCreate, so attach() there is the whole mechanism: your listeners are alive again before the event is delivered.

What survives which kill path, and how long a restart takes, is in Boot & killed-app behaviour.

Stationary heartbeat

While STATIONARY (or MOVING), a heartbeatInterval timer keeps firing regardless of motion state, carrying the last known location. It’s not a wake source by itself, but each firing also nudges the stop-timeout bookkeeping — see the heartbeat event for the payload shape.