Skip to content

Configuration

BeekonConfig has three modes:

ModeWho owns the configUploads
LocalYour appNone. Locations stay on the device.
CustomYour appTo your own server, through the required sync field.
CloudThe server, through a project keyTo Beekon Cloud.

Local and Custom carry the same TrackingConfig. This page is the reference for every field.

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 has six fields:

FieldTypeDefaultNotes
minTimeBetweenLocationsSecondsseconds30Min seconds between kept locations. 0 disables the time gate.
minDistanceBetweenLocationsMetersmetres100Min metres between kept locations. 0 disables the distance gate; AND-ed with time.
accuracyModeenumbalancedBattery against accuracy. See Enums.
whenStationaryenumpauseWhat to do while the device is still. See Enums.
stationaryRadiusMetersmetres5Radius of the internal stationary geofence. Clamped to 5…1000 on the device, even when remote config sends more (the server accepts up to 10000).
detectActivitybooleanfalseAdds 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.

ValueBehaviour
highMost accurate fixes, highest battery cost.
balanced (default)City-block accuracy at moderate cost.
lowCoarse, low-power fixes; the distance gate is raised to at least 500 m.

StationaryMode: behaviour while the device is still.

ValueBehaviour
keepTrackingKeep recording locations even while stationary. Highest battery cost.
pause (default)Stop recording locations while stationary; resume silently on movement.
pauseWithCheckInsStop 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.

These fields sit on BeekonConfig itself, not on TrackingConfig:

FieldModesDefaultNotes
trackingCustom, Localall defaultsThe TrackingConfig above. In Cloud mode the server owns these values.
syncCustom (required)—Where and how to upload. See Turn on sync. Local never uploads; Cloud derives its own endpoints.
notificationall modesNotificationConfig()The foreground-service notification. Android only. See NotificationConfig.
licenseKeyCustom, LocalnullA 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).
logLevelall modesinfoThe diagnostic log threshold. See Diagnostics.

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 as in1. Without an endpoint, the SDK derives https://api.<cell>.getbeekon.com from the key. There is no network call and no fallback host.
  • endpoint overrides the derived host; Beekon Cloud apps leave it unset. It must be https (plain http only to localhost, 127.0.0.1 or ::1), with no query or fragment and no v1 path segment.
  • Rejections carry a reason: key_empty for an empty key; key_missing_cell for a key with no <cell> segment and no endpoint; and an endpoint reason for an endpoint that breaks the rules above.
// BeekonConfig.cloud throws BeekonException.InvalidConfiguration
// on a bad key/endpoint
Beekon.configure(
BeekonConfig.cloud(
projectKey = "bkproj_in1_...",
// endpoint = "https://beekon.example.com", // overrides the derived host
notification = NotificationConfig(title = "Tracking location"),
),
)

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.

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.

FieldTypeDefaultNotes
titlestring"Tracking location"Notification title.
textstringnullNotification body. null shows the title only.
smallIconstringnullThe status-bar icon: the name of an Android drawable or mipmap resource. null uses the launcher icon.

Call configure(...) again at any time, including while tracking. What happens next depends on the OS:

  • Android (also Flutter and React Native on Android): configure restarts the location subscription with the new config, so every field applies at once, accuracyMode included.
  • iOS (also Flutter and React Native on iOS): the gate thresholds, whenStationary, stationaryRadiusMeters, detectActivity and sync apply to the next location, without restarting the location subscription. accuracyMode is fixed for a session: the OS location request keeps the accuracy it started with, and a changed value applies on the next start().

The examples below change only the gate.

// Store locations more often, mid-session
Beekon.configure(
BeekonConfig.Local(
tracking = TrackingConfig(
minTimeBetweenLocationsSeconds = 5,
minDistanceBetweenLocationsMeters = 25.0,
accuracyMode = AccuracyMode.Balanced,
whenStationary = StationaryMode.Pause,
),
notification = NotificationConfig(title = "Tracking location"),
),
)

The defaults (30 s, 100 m, balanced, pause) suit general tracking. Starting points for other uses, with time as minTimeBetweenLocationsSeconds and distance as minDistanceBetweenLocationsMeters:

ScenarioTime (s)Distance (m)accuracyModeNotes
Passive background (“where did I go?”)60500lowA coarse trail at low battery cost. low raises the distance gate to at least 500 m.
General tracking (default)30100balancedDriving, cycling, long walks.
Active foreground (turn-by-turn, fitness)5–1025–50highHigh battery use in the background.
Stationary monitoring (geofence-like)0100balancedStores a location on movement only, not on a timer.

Check them against your own data.