BeekonConfig has three modes:
| Mode | Who owns the config | Uploads |
|---|---|---|
| Local | Your app | None. Locations stay on the device. |
| Custom | Your app | To your own server, through the required sync field. |
| Cloud | The server, through a project key | To Beekon Cloud. |
Local and Custom carry the same TrackingConfig. This page is the reference for every field.
The gate
Section titled “The gate”Tracking is controlled by two numbers: a minimum time and a minimum distance between stored locations. A reading from the OS (a fix) becomes a location only when both have passed.
(now - lastAdmittedTime >= minTimeBetweenLocationsSeconds) AND(distance(lastAdmittedFix) >= minDistanceBetweenLocationsMeters)The first fix after start() always passes. Set either field to 0 to turn that side of the gate off. Beekon applies no other filtering: no Kalman filter, no outlier rejection, no speed clamp. Coordinates and accuracy are what the OS provider (FusedLocationProviderClient on Android, Core Location on iOS) reported.
TrackingConfig fields
Section titled “TrackingConfig fields”TrackingConfig has six fields:
| Field | Type | Default | Notes |
|---|---|---|---|
minTimeBetweenLocationsSeconds | seconds | 30 | Min seconds between kept locations. 0 disables the time gate. |
minDistanceBetweenLocationsMeters | metres | 100 | Min metres between kept locations. 0 disables the distance gate; AND-ed with time. |
accuracyMode | enum | balanced | Battery against accuracy. See Enums. |
whenStationary | enum | pause | What to do while the device is still. See Enums. |
stationaryRadiusMeters | metres | 5 | Radius of the internal stationary geofence. Clamped to 5…1000 on the device, even when remote config sends more (the server accepts up to 10000). |
detectActivity | boolean | false | Adds the detected activity (walking, driving and so on) to each location. Needs a second OS permission; see Activity detection. |
In code: seconds are Long on Android, TimeInterval on iOS, int in Flutter and number in React Native; metres are Double, Double, double and number; the booleans are Boolean, Bool, bool and boolean. accuracyMode is an AccuracyMode and whenStationary a StationaryMode.
AccuracyMode: battery against accuracy.
| Value | Behaviour |
|---|---|
high | Most accurate fixes, highest battery cost. |
balanced (default) | City-block accuracy at moderate cost. |
low | Coarse, low-power fixes; the distance gate is raised to at least 500 m. |
StationaryMode: behaviour while the device is still.
| Value | Behaviour |
|---|---|
keepTracking | Keep recording locations even while stationary. Highest battery cost. |
pause (default) | Stop recording locations while stationary; resume silently on movement. |
pauseWithCheckIns | Stop while stationary, but record a check-in location roughly every 15 minutes. On iOS a check-in runs only when the system runs the background refresh task, so it can be hours apart. |
Mode-specific fields
Section titled “Mode-specific fields”These fields sit on BeekonConfig itself, not on TrackingConfig:
| Field | Modes | Default | Notes |
|---|---|---|---|
tracking | Custom, Local | all defaults | The TrackingConfig above. In Cloud mode the server owns these values. |
sync | Custom (required) | — | Where and how to upload. See Turn on sync. Local never uploads; Cloud derives its own endpoints. |
notification | all modes | NotificationConfig() | The foreground-service notification. Android only. See NotificationConfig. |
licenseKey | Custom, Local | null | A signed licence token. See Licensing. In Cloud mode the server delivers the key for the app ids registered under Organisation › SDK licence in the console (In Cloud mode). |
logLevel | all modes | info | The diagnostic log threshold. See Diagnostics. |
Cloud mode
Section titled “Cloud mode”A Cloud config is built by a factory that checks its input when you build it, so a bad key fails at configure rather than later on the network.
- The project key names its region:
bkproj_<cell>_<secret>, where<cell>is the Beekon Cloud region of your project, such asin1. Without anendpoint, the SDK deriveshttps://api.<cell>.getbeekon.comfrom the key. There is no network call and no fallback host. endpointoverrides the derived host; Beekon Cloud apps leave it unset. It must behttps(plainhttponly tolocalhost,127.0.0.1or::1), with no query or fragment and nov1path segment.- Rejections carry a reason:
key_emptyfor an empty key;key_missing_cellfor a key with no<cell>segment and noendpoint; and an endpoint reason for an endpoint that breaks the rules above.
// BeekonConfig.cloud throws BeekonException.InvalidConfiguration// on a bad key/endpointBeekon.configure( BeekonConfig.cloud( projectKey = "bkproj_in1_...", // endpoint = "https://beekon.example.com", // overrides the derived host notification = NotificationConfig(title = "Tracking location"), ),)// BeekonConfig.cloud throws BeekonError.invalidConfiguration(reason:)// on a bad key/endpointtry await Beekon.shared.configure( BeekonConfig.cloud( projectKey: "bkproj_in1_..." // endpoint: "https://beekon.example.com" (overrides the derived host) ))// configure throws InvalidConfiguration on a bad key/endpointawait Beekon.instance.configure( const BeekonConfig.cloud( projectKey: 'bkproj_in1_...', // endpoint: 'https://beekon.example.com', // overrides the derived host notification: NotificationConfig(title: 'Tracking location'), // Android only ),);// configure rejects with a BeekonError of kind 'invalidConfiguration'// on a bad key/endpointawait Beekon.configure({ mode: 'cloud', projectKey: 'bkproj_in1_...', // endpoint: 'https://beekon.example.com', // overrides the derived host notification: { title: 'Tracking location' }, // Android only});In React Native, BeekonConfig.cloud(...), BeekonConfig.custom(...) and BeekonConfig.local(...) are optional helpers that fill in mode. Their result, like a literal mode: 'cloud' object, goes through the same native validation.
In Cloud mode the tracking values come from the server as a remote config document with the sections tracking, sync, privacy, features and diagnostics. The SDK caches it on the device and applies it as a whole: a fresh document wins over the cached one, which wins over the built-in defaults. Tracking never waits for configuration. A device that can’t reach the server runs its last good config, or the defaults if it has never connected.
Before it applies a remote value, the SDK clamps it to its own limits: floors and ceilings built into the SDK. No server value, including one from a compromised server, can push the device outside those ranges, redirect uploads or change how the device authenticates. Remote config lists every value and the range the server accepts; the device may clamp further, as it does for stationaryRadiusMeters.
NotificationConfig
Section titled “NotificationConfig”Android shows a notification while an app captures location in the background. Set its content with BeekonConfig.notification; iOS ignores it. This is the notification of the tracking service, shown for as long as it runs. Geofence notifications are separate: they appear on enter or exit, on every platform.
| Field | Type | Default | Notes |
|---|---|---|---|
title | string | "Tracking location" | Notification title. |
text | string | null | Notification body. null shows the title only. |
smallIcon | string | null | The status-bar icon: the name of an Android drawable or mipmap resource. null uses the launcher icon. |
Live tuning
Section titled “Live tuning”Call configure(...) again at any time, including while tracking. What happens next depends on the OS:
- Android (also Flutter and React Native on Android):
configurerestarts the location subscription with the new config, so every field applies at once,accuracyModeincluded. - iOS (also Flutter and React Native on iOS): the gate thresholds,
whenStationary,stationaryRadiusMeters,detectActivityandsyncapply to the next location, without restarting the location subscription.accuracyModeis fixed for a session: the OS location request keeps the accuracy it started with, and a changed value applies on the nextstart().
The examples below change only the gate.
// Store locations more often, mid-sessionBeekon.configure( BeekonConfig.Local( tracking = TrackingConfig( minTimeBetweenLocationsSeconds = 5, minDistanceBetweenLocationsMeters = 25.0, accuracyMode = AccuracyMode.Balanced, whenStationary = StationaryMode.Pause, ), notification = NotificationConfig(title = "Tracking location"), ),)try await Beekon.shared.configure( BeekonConfig.local( tracking: TrackingConfig( minTimeBetweenLocationsSeconds: 5, minDistanceBetweenLocationsMeters: 25, accuracyMode: .balanced, whenStationary: .pause ) ))await Beekon.instance.configure( BeekonConfig.local( tracking: const TrackingConfig( minTimeBetweenLocationsSeconds: 5, minDistanceBetweenLocationsMeters: 25, accuracyMode: AccuracyMode.balanced, whenStationary: StationaryMode.pause, ), ),);await Beekon.configure({ mode: 'local', tracking: { minTimeBetweenLocationsSeconds: 5, minDistanceBetweenLocationsMeters: 25, accuracyMode: 'balanced', whenStationary: 'pause', },});Picking values
Section titled “Picking values”The defaults (30 s, 100 m, balanced, pause) suit general tracking. Starting points for other uses, with time as minTimeBetweenLocationsSeconds and distance as minDistanceBetweenLocationsMeters:
| Scenario | Time (s) | Distance (m) | accuracyMode | Notes |
|---|---|---|---|---|
| Passive background (“where did I go?”) | 60 | 500 | low | A coarse trail at low battery cost. low raises the distance gate to at least 500 m. |
| General tracking (default) | 30 | 100 | balanced | Driving, cycling, long walks. |
| Active foreground (turn-by-turn, fitness) | 5–10 | 25–50 | high | High battery use in the background. |
| Stationary monitoring (geofence-like) | 0 | 100 | balanced | Stores a location on movement only, not on a timer. |
Check them against your own data.