Configuration

BeekonConfig has two arms: SelfManaged (you set the gate locally — these docs) and Cloud (server-owned config via a project key — see Beekon Cloud). This page is the single, authoritative reference for the SelfManaged fields. The Quickstart shows the minimal set; everything else is here.

The gate

SelfManaged tracking is built around two scalars — a minimum time interval and a minimum distance between emitted fixes. They form an AND-gate: a position is emitted only when both pass.

(now - lastAdmittedTime    >= intervalSeconds) AND
(distance(lastAdmittedFix) >= distanceMeters)

The first fix after start() always passes. Set either field to 0 to disable that side of the gate. That’s the entire signal-processing surface in v1 — no Kalman filter, no outlier rejection, no speed clamp. The OS provider (FusedLocationProviderClient / Core Location) is the source of truth; Beekon forwards it faithfully.

Why AND, not OR?

An OR-gate leaks: interval-only fires on a stationary device every interval; distance-only fires constantly while moving regardless of trail density. AND hits a useful equilibrium for trail rendering and history queries.

SelfManaged fields

Field	Type	Default	Notes
minTimeBetweenLocationsSeconds	Long / Int / int / number	30	Min seconds between kept fixes. 0 disables the time gate.
minDistanceBetweenLocationsMeters	Double / Double / double / number	100	Min metres between kept fixes. 0 disables the distance gate; AND-ed with time.
accuracyMode	AccuracyMode	balanced	Battery-vs-accuracy preset — see enums.
whenStationary	StationaryMode	pause	What to do while the device is still — see enums. New in 0.1.1.
stationaryRadiusMeters	Double / Double / double / number	5	Radius of the internal stationary geofence. Clamped to 5…1000.
detectActivity	Boolean / Bool / bool / boolean	false	Classify physical motion onto each fix. Needs a second OS permission — see Locations & history.
sync	SyncConfig?	null	Server upload config. Omit for local-only.
notification	NotificationConfig	—	Foreground-service notification. Android only. See below.
licenseKey	String?	null	Signed license token — see Licensing.
logLevel	LogLevel	info	Diagnostic log threshold — see Diagnostics.

Type columns read Android / iOS / Flutter / React Native.

Enums

Casing follows the platform

Enum naming differs per platform — Android is PascalCase, iOS/Flutter lowercase, React Native string literals. The values mean the same thing everywhere.

AccuracyMode — battery vs. accuracy:

Value	Android	iOS / Flutter	React Native	Behaviour
High	AccuracyMode.High	.high / AccuracyMode.high	'high'	Most accurate fixes, highest battery cost
Balanced (default)	AccuracyMode.Balanced	.balanced / AccuracyMode.balanced	'balanced'	City-block accuracy at moderate cost
Low	AccuracyMode.Low	.low / AccuracyMode.low	'low'	Coarse, low-power fixes; distance gate floored to 500 m

StationaryMode — behaviour while the device is still:

Value	Android	iOS / Flutter	React Native	Behaviour
Keep tracking	StationaryMode.KeepTracking	.keepTracking / StationaryMode.keepTracking	'keepTracking'	Keep admitting fixes even while stationary. Highest battery cost.
Pause (default)	StationaryMode.Pause	.pause / StationaryMode.pause	'pause'	Stop admitting fixes while stationary; resume silently on movement.
Pause with check-ins	StationaryMode.PauseWithCheckIns	.pauseWithCheckIns / StationaryMode.pauseWithCheckIns	'pauseWithCheckIns'	Stop while stationary, but record a check-in fix roughly every 15 minutes.

NotificationConfig

Android requires a visible foreground-service notification while location is captured in the background. Set it via BeekonConfig.notification — it’s ignored on iOS.

Field	Type	Default	Notes
title	string	"Tracking location"	Notification title.
text	string	null	Notification body. null shows the title only.
smallIcon	string	null	Status-bar icon — an Android drawable/mipmap resource name. null falls back to the launcher icon.

Use a monochrome icon

Android renders the status-bar icon from its alpha channel only, so supply a monochrome silhouette on a transparent background — a full-colour launcher icon shows as a white blob. smallIcon accepts a bare name ("ic_stat_tracking", resolved against drawable then mipmap) or a typed path ("drawable/ic_stat_tracking").

Live tuning

Call configure(...) again at any time — including while tracking — to update the gate. New values take effect on the next admitted fix without restarting the underlying location subscription.

Android

// Tighten cadence mid-session
Beekon.configure(
  BeekonConfig.SelfManaged(
    minTimeBetweenLocationsSeconds = 5,
    minDistanceBetweenLocationsMeters = 25.0,
    accuracyMode = AccuracyMode.High,
    whenStationary = StationaryMode.Pause,
    notification = notification,
  ),
)

iOS

try await Beekon.shared.configure(
  BeekonConfig.selfManaged(
    minTimeBetweenLocationsSeconds: 5,
    minDistanceBetweenLocationsMeters: 25,
    accuracyMode: .high,
    whenStationary: .pause
  )
)

Flutter

await Beekon.instance.configure(
  const BeekonConfig.selfManaged(
    minTimeBetweenLocationsSeconds: 5,
    minDistanceBetweenLocationsMeters: 25,
    accuracyMode: AccuracyMode.high,
    whenStationary: StationaryMode.pause,
  ),
);

React Native

await Beekon.configure({
  mode: 'selfManaged',
  minTimeBetweenLocationsSeconds: 5,
  minDistanceBetweenLocationsMeters: 25,
  accuracyMode: 'high',
  whenStationary: 'pause',
});

Picking values

The defaults (30 s / 100 m, balanced, pause) are a good general-purpose starting point. Adjust per scenario:

Scenario	intervalSeconds	distanceMeters	accuracyMode	Notes
Passive background (“where did I go?”)	60	150	low	Coarse trail; cheaper on battery
General tracking (default)	30	100	balanced	Driving, cycling, multi-hour walks
Active foreground (turn-by-turn, fitness)	5–10	25–50	high	Users feel the battery hit in background
Stationary monitoring (geofence-like)	0	100	balanced	Emit only on movement, not on cadence

These are starting points, not presets — calibrate against your own data.