Skip to content

Lifecycle & states

Beekon has three states. They are the same on every platform; only the casing follows the language (Tracking in Kotlin, tracking in Swift).

Idle → Tracking → Stopped(reason)

You observe it on the state stream. The stream is hot and replays the latest value, so a new subscriber sees the current state at once.

StateMeaningLive emissions?
IdleInitial state. configure may or may not have happened; start has not.No
TrackingLive updates flowing from the OS provider through the gate.Yes
Stopped(reason)Tracking ended. The reason indicates whether it was user-initiated or forced. Re-enter via start().No

There is no Starting state: start() suspends, and its completion is the move to Tracking. There is no Paused state either. A precondition that fails while tracking (permission revoked, location services turned off, the foreground service killed on Android) ends in Stopped(reason), and your app calls start() again once the condition is fixed.

ReasonWhen it fires
UserThe host app called Beekon.stop().
PermissionDeniedLocation permission was revoked or never granted.
LocationServicesDisabledSystem-wide location services are turned off. The user can fix it in Settings.
LocationUnavailableThe device has no usable location provider. On Android, Google Play Services is missing or out of date. The user can’t fix it.
SystemThe OS stopped tracking and it couldn’t be resumed. On Android, a foreground-service kill (memory pressure, force-stop); on iOS, an unrecoverable internal error such as the on-device database failing to open.
BackgroundStartDeniedAndroid 12+ only in practice. A start or resume from the background was refused a foreground-service start. The session can still be resumed: see Transitions. Flutter and React Native emit it on Android too. iOS declares it for parity and never emits it.

All six reasons exist on every platform, with the casing of the host language (PermissionDenied on Kotlin, .permissionDenied on Swift and Dart, 'permissionDenied' on React Native).

// state is a StateFlow: hot, replays the latest value
val state by Beekon.state.collectAsStateWithLifecycle()
when (val s = state) {
is BeekonState.Idle -> Text("Not started")
is BeekonState.Tracking -> Text("Live")
is BeekonState.Stopped -> Text("Stopped: ${s.reason}")
}
start() stop() / OS-revocation / system kill
Idle ────────> Tracking ──────────────────────────────> Stopped(reason)
▲ │
└────────────── start() ─────────────────────┘
  • Idle → Tracking: start() succeeds. The first location can arrive immediately.
  • Tracking → Stopped(User): the host called stop().
  • Tracking → Stopped(PermissionDenied): authorisation was revoked while tracking.
  • Tracking → Stopped(LocationServicesDisabled): system location services were turned off.
  • Stopped(LocationUnavailable): no usable location provider. On Android, Google Play Services is missing or out of date.
  • Stopped(System): on Android, the OS killed the foreground service; on iOS, the SDK hit an unrecoverable internal error (the on-device database could not open).
  • Stopped(BackgroundStartDenied): Android only in practice. A resume from the background was refused a foreground-service start (an Android 12+ rule). The saved session is kept, and the next start() or resumeIfNeeded() recovers it, usually from your Application.onCreate when the user next opens the app.
  • Stopped → Tracking: requires a fresh start(). Beekon does not auto-resume when a condition recovers.

StopReason may gain values in a minor release. Give every when or switch an else or default branch.