API reference
The same shape on every platform: 12 core methods, plus diagnostics, license, and permissions, and one stream per feature. Method names are identical across Android, iOS, Flutter, and React Native — only the language syntax (and each platform’s stream idiom) differs.
Methods
Section titled “Methods”| Method | What it does |
|---|---|
configure(config) | Apply settings (optional; may be called while tracking to live-tune). The Cloud arm is built via the validating BeekonConfig.cloud(...) factory — see Configuration. |
start() | Begin tracking. Never throws — observe state. |
stop() | Stop tracking. |
getCurrentLocation(timeout?, accuracy?) | One immediate fix, independent of tracking. null on timeout. |
getLocations(from, to) | Read stored history in a range. With sync enabled this is also the upload outbox: rows leave it once the server acknowledges them. |
deleteLocations(before?) | Delete history (all if omitted); returns rows removed. |
sync() | Force an immediate upload. |
setExtras(extras) | Custom, opaque string → string fields sent with every upload. |
setUserId(userId) | Stable per-user id, bound to fixes at record time — an offline account switch attributes queued points to the right user. Trimmed; blank/null clears. Throws on control characters or > 256 UTF-8 bytes. Drives MTU metering. |
pendingUploadCount() | Locations not yet uploaded. |
addGeofences(geofences) | Register regions. Throws GeofencesManagedByServer in cloud mode. |
removeGeofences(ids) | Unregister by id. Also throws GeofencesManagedByServer in cloud mode. |
listGeofences() | The current geofence set (in cloud mode: the server-delivered slice the device is operating on). |
getPermissionStatus() | Current location-permission grant. Read-only; never prompts. |
getRequiredPermissions() | The permissions the active config needs, each marked satisfied. The config-aware companion to getPermissionStatus() — reports activity-recognition (and, on Android, notifications) too. Read-only. |
requestPermission(permission) | Explicitly request one permission; resolves to a PermissionRequestResult. The app-initiated ask — Beekon still never prompts implicitly. Android takes a foreground Activity. See Requesting permissions. |
requestNextNeededPermission() | Request the first unsatisfied required permission from the doctor list; returns the result, or null/nil when nothing is needed. The idiomatic one call per onboarding screen (one step at a time). Android takes an Activity. |
openSettings(for permission) | Open the closest reachable OS settings screen — the path for the requiresSettings outcome. Android takes an Activity/Context. |
getLog / exportLog / clearLog / setLogLevel / log | Diagnostics & troubleshooting. |
resumeIfNeeded() | Resume a session active before the process was killed (wrappers; native resumes automatically). |
On iOS, the fire-and-forget setters — setUserId, setExtras, sync(), setLogLevel, log —
are nonisolated: no await needed.
Each Location carries the position fields plus three optional record-time battery fields —
batteryPercent, isCharging, powerSaveMode (null/nil = unknown) — sampled when the fix was
recorded, never at upload time.
Streams
Section titled “Streams”One observable per feature — subscribe the way that’s idiomatic (Android Flow/StateFlow, iOS AsyncStream, wrappers on* subscriptions):
| Stream | Delivers |
|---|---|
state | Idle → Tracking → Stopped(reason) transitions. |
locations | Each admitted fix, live. |
geofenceEvents | Enter / exit crossings. |
syncStatus | Upload progress and outcomes. |
authChanges | Token rotations from native refresh. |
logs | Diagnostic log entries, live. |
License status is observational and platform-idiomatic: Android exposes
licenseStatus: StateFlow<LicenseStatus> (current value + updates in one handle); iOS exposes
licenseStatus (the current value) plus a licenseStatusUpdates stream. The wrappers surface a
getter + subscription. See Licensing.
Host-facing enums (StopReason, ActivityType, SyncFailure, LocationQuality, …) may gain
new values in minor releases — always switch with an else/default branch. StopReason
includes backgroundStartDenied (Android: a background-woken resume was denied a foreground
service start; the session stays resumable and a later start()/resumeIfNeeded() recovers it).
Permission requests
Section titled “Permission requests”requestPermission(...) and requestNextNeededPermission() resolve to a flat PermissionRequestResult:
| Field | Type | Present when |
|---|---|---|
outcome | PermissionRequestOutcome | always |
prerequisite | BeekonPermission? | outcome == blocked — request this permission first |
reason | String? | outcome == notAttempted — missing_manifest_entry · missing_plist_key · unsupported · not_foreground |
status | PermissionStatus | always — a refreshed grant snapshot |
PermissionRequestOutcome — granted · denied · requiresSettings · alreadySatisfied · blocked · notAttempted. It’s a host-facing enum (may gain values in a minor release — switch with an else/default); the wrappers surface it as string literals. Casing follows each platform (Android Granted/RequiresSettings; iOS/Flutter .granted/.requiresSettings; RN 'granted'/'requiresSettings'). Meanings and the full onboarding flow are on Requesting permissions.
On iOS, requestNotificationAuthorization() is deprecated in favor of requestPermission(.notifications) and will be removed before 1.0.
Generated per-platform reference
Section titled “Generated per-platform reference”Full, generated API docs with every type and signature: