Configuration

BeekonConfig has three arms: Local (app-owned config, no upload), Custom (app-owned config + your own backend via a required sync), and Cloud (server-owned config via a project key — see Beekon Cloud). The Local and Custom arms both carry the same TrackingConfig; this page is the single, authoritative reference for its fields. The Quickstart shows the minimal set; everything else is here.

The gate

App-owned 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.

TrackingConfig fields

TrackingConfig carries exactly six knobs — the tracking gate and nothing else:

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.
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.

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

Arm-level fields

Everything that isn’t a tracking knob lives on the BeekonConfig arm, not on TrackingConfig:

Field	On arms	Default	Notes
tracking	Custom, Local	all defaults	The TrackingConfig above. In Cloud mode the server owns these knobs.
sync	Custom (required)	—	Your upload config — see Sync & your backend. Local never uploads; Cloud derives its own endpoints.
notification	all arms	—	Foreground-service notification. Android only. See below.
licenseKey	Custom, Local	null	Signed license token — see Licensing. Cloud delivers the license from the server.
logLevel	all arms	info	Diagnostic log threshold — see Diagnostics.

The Cloud arm

Cloud is built by a validating factory — it throws/errors at configure time rather than failing later on the network:

• The project key is cell-aware: bkproj_<cell>_<secret> (the cell names the Beekon Cloud region your project lives in, e.g. in1). With no explicit endpoint, the SDK derives https://api.<cell>.getbeekon.com from the key — zero network calls, no global fallback host.
• Typed rejections: an empty key is key_empty; a key without a parseable cell and no explicit endpoint is key_missing_cell; an explicit endpoint must be a clean https base URL (no query, no fragment).
• An explicit endpoint (self-hosted Beekon) always overrides derivation.

// Android — throws BeekonException.InvalidConfiguration on a bad key/endpoint
Beekon.configure(
  BeekonConfig.cloud(
    projectKey = "bkproj_in1_...",
    notification = notification,
  ),
)

// iOS — throws on a bad key/endpoint
try await Beekon.shared.configure(
  BeekonConfig.cloud(projectKey: "bkproj_in1_...")
)

In cloud mode the tracking knobs arrive from the server as a remote config document — sectioned (tracking / sync / privacy / features / diagnostics), cached on-device, applied whole-document with fresh > cache > defaults precedence. Tracking never blocks on configuration: a device that can’t reach the server runs its last-good config, or compiled defaults if it has never connected.

The SDK is the final authority on battery safety. Every remote knob passes a device-enforced clamp table (floors and ceilings baked into the SDK) before it is applied — no server value, including a compromised one, can push the device outside safe ranges, redirect uploads, or change the auth recipe. The full knob inventory and clamp bounds are normative in the cloud-mode spec.

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. This is the persistent service notification that keeps the background process alive; it’s distinct from the per-crossing geofence notifications, which fire on enter/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	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.Local(
    tracking = TrackingConfig(
      minTimeBetweenLocationsSeconds = 5,
      minDistanceBetweenLocationsMeters = 25.0,
      accuracyMode = AccuracyMode.High,
      whenStationary = StationaryMode.Pause,
    ),
    notification = notification,
  ),
)

iOS

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

Flutter

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

React Native

await Beekon.configure({
  mode: 'local',
  tracking: {
    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.