The four SDKs share one API: the same method names on Android, iOS, Flutter and React Native, and one stream per feature. Only the language and each platform’s way of exposing a stream differ.
Methods
Section titled “Methods”| Method | What it does |
|---|---|
configure(config) | Apply settings. Optional; can be called again while tracking (what applies when). Cloud mode is built with the BeekonConfig.cloud(...) factory; see Configuration. |
start() | Begin tracking. Never throws; watch state for the result. |
stop() | Stop tracking. |
getCurrentLocation(timeout?, accuracy?) | One location now, whether or not tracking is on. null on timeout. The timeout is timeoutMs (milliseconds) on Android and React Native, timeout in seconds on iOS, and a Duration in Flutter; it defaults to 15 s. On iOS 15 and 16 both parameters are ignored (One-shot fix). |
getLocations(from, to) | Read stored history in a time range. With sync on, the history is also the upload queue: locations leave it once the server accepts them. |
deleteLocations(before?) | Delete history recorded strictly before before (all of it if omitted). Returns how many locations it deleted. |
sync() | Force an immediate upload. |
setExtras(extras) | Your own string → string fields, sent with every upload. |
setUserId(userId) | A stable per-user id, bound to each location when it is recorded, so an account switch while offline still attributes queued locations correctly. Trimmed; blank or null clears it. Throws on control characters or more than 256 UTF-8 bytes (so on iOS, call it with try). Counts towards MAU. Send an opaque id, never an email or phone number: see Choosing a user id. |
pendingUploadCount() | Locations not yet uploaded. |
addGeofences(geofences) | Register geofences. Throws GeofencesManagedByServer in cloud mode. |
removeGeofences(ids) | Unregister by id. Also throws GeofencesManagedByServer in cloud mode. |
listGeofences() | The current geofences. In Cloud mode, the ones the server delivered to this device. |
getPermissionStatus() | The current location-permission grant, as a PermissionStatus. Never prompts. |
getRequiredPermissions() | The permissions the active config needs, each marked required or recommended and satisfied or not. Includes activity recognition and, on Android 13 and later, notifications. Never prompts. |
requestPermission(permission) | Ask for one permission; returns a PermissionRequestResult. Android takes a foreground Activity. See Requesting permissions. |
requestNextNeededPermission() | Ask for the first unsatisfied required permission; returns its result, or null (nil on iOS) when none is missing. Never asks for recommended permissions such as background location. Android takes an Activity. |
openSettings(for permission) | Open the closest OS settings screen, for the requiresSettings outcome. Android takes an Activity; on iOS it is a static method. |
getLog / exportLog / clearLog / setLogLevel / log | Diagnostics & troubleshooting. |
resumeIfNeeded() | Resume a session that was tracking when the process was killed; does nothing if the user stopped or never started. Android: call it from Application.onCreate (a boot receiver covers reboots and app updates). iOS: the SDK calls it at launch and on foreground. Flutter and React Native: call it early in startup. See Cold-launch resume. |
licenseStatus | The licence status. See Licensing. |
On iOS, setUserId, setExtras, sync(), setLogLevel, log and getPermissionStatus()
are nonisolated, so they need no await. iOS also has static methods on Beekon:
| iOS static method | What it does |
|---|---|
Beekon.registerBackgroundTasks() | Registers the background task for sync and check-ins. Call it once, synchronously, at launch. See iOS: background tasks. Flutter’s plugin calls it for you; React Native apps call BeekonRnImpl.registerBackgroundTasks(). |
Beekon.openSettings(for:) | See the table above. |
Beekon.bootstrap() | Starts the SDK early. It runs by itself at process launch, so apps rarely call it. |
Beekon.requestNotificationAuthorization() | Deprecated; use requestPermission(.notifications). |
Two platforms have methods for the push probe (Cloud mode, SDK 0.6.0 and later). Flutter and React Native have no API for it: call the native methods from the host app. The probe is switched off in Beekon Cloud today, so these change nothing until it is turned on. The SDK 0.6.0 changelog has an integration example.
| Platform method | What it does |
|---|---|
Android Beekon.setPushToken(token) | Hands Beekon your app’s FCM token. Call it from onNewToken and once at launch. null or empty clears it. Never logged. |
Android Beekon.handlePushMessage(data) | Call it first from onMessageReceived with remoteMessage.data. Returns true for Beekon’s message, which your app then ignores, and false for yours. Never throws. |
iOS startMonitoringLocationPushes(appGroup:) | Call it at every launch after configure with the cloud arm. Reports the location-push token and shares what the extension needs through the App Group. Needs the location-push entitlement and Always authorisation. |
iOS BeekonLocationPush(appGroup:) | A separate package product for your Location Push Service Extension. handle(_:completion:) answers Beekon’s push and returns false for any other. |
Each Location carries the coordinates and motion fields, plus three optional battery fields
sampled when it was recorded: batteryPercent, isCharging and powerSaveMode (null when
unknown).
Streams
Section titled “Streams”One stream per feature. Android exposes a Flow or StateFlow, iOS an AsyncStream, Flutter a Dart Stream (listen returns a StreamSubscription). React Native has on* methods that each return an unsubscribe function: onState, onLocation, onGeofenceEvent, onSyncStatus, onAuthTokens, onLicenseStatus and onLog.
| Stream | Delivers |
|---|---|
state | Idle → Tracking → Stopped(reason) transitions. |
locations | Each location that passes the gate, as it is recorded. |
geofenceEvents | Geofence crossings. |
syncStatus | Idle, Pending or Failed(Auth | Rejected). See Turn on sync. |
authChanges | New tokens after a refresh (onAuthTokens in React Native). |
logs | Diagnostic log entries as they are written. |
The licence status is reported, never enforced. Android has licenseStatus: StateFlow<LicenseStatus>
(the current value and its changes in one handle). iOS and Flutter have licenseStatus plus a
licenseStatusUpdates stream; React Native has licenseStatus() and onLicenseStatus. See
Licensing.
Enums your app reads (StopReason, ActivityType, SyncFailure, LocationQuality and others)
may gain values in a minor release, so give every switch an else or default branch.
StopReason includes backgroundStartDenied on every platform, but only Android emits it (Flutter and React Native included): a
resume started in the background was refused a foreground service. The session stays
resumable, and a later start() or resumeIfNeeded() recovers it. See
Stop reasons.
Permission status
Section titled “Permission status”getPermissionStatus() and the status of every permission request return a PermissionStatus. It is a snapshot: once tracking runs, a lost permission arrives on state as Stopped(PermissionDenied), so watch state rather than polling this.
| Field | Type | Meaning |
|---|---|---|
level | PermissionStatus.Level (Flutter PermissionLevel, React Native PermissionLevel) | How far the location grant reaches (below). |
accuracy | PermissionStatus.Accuracy? (Flutter PermissionAccuracy?, React Native PermissionAccuracy | null) | full (precise) or reduced (approximate); null when location is not granted. |
isAuthorized | boolean | true when level is foreground or background. |
canTrackInBackground | boolean | true when level is background. |
level | Meaning |
|---|---|
notDetermined | No location permission. On Android this also covers a permission the user denied: without an Activity, Android can’t tell the two apart. |
denied | The user denied location. iOS only; they can change it in Settings. |
restricted | A policy the user can’t change blocks location (for example a device-management profile or Screen Time). iOS only. |
foreground | Granted while the app is in use. On Android, without ACCESS_BACKGROUND_LOCATION. |
background | Granted at all times. On Android before 10 (API 29), any grant is background. |
Casing follows the platform: Android Level.NotDetermined and Accuracy.Full, iOS .notDetermined and .full, Flutter PermissionLevel.notDetermined and PermissionAccuracy.full, React Native 'notDetermined' and 'full'. level may gain values in a minor release.
Permission requests
Section titled “Permission requests”requestPermission(...) and requestNextNeededPermission() return a PermissionRequestResult:
| Field | Type | Present when |
|---|---|---|
outcome | PermissionRequestOutcome | always |
prerequisite | BeekonPermission? | outcome == blocked: ask for this permission first |
reason | String? | outcome == notAttempted: missing_manifest_entry, missing_plist_key, unsupported or not_foreground |
status | PermissionStatus | always: the grant after the request |
PermissionRequestOutcome is one of granted, denied, requiresSettings, alreadySatisfied, blocked and notAttempted, and may gain values in a minor release. Casing follows the platform: Android Granted, iOS .granted, Flutter PermissionRequestOutcome.granted, React Native 'granted'. What each means is on Requesting permissions.
On iOS, requestNotificationAuthorization() is deprecated in favour of requestPermission(.notifications) and will be removed before 1.0.
Per-platform reference
Section titled “Per-platform reference”Every type and signature is in each SDK’s package and its docs: