Beekon is a background location SDK for Android, iOS, Flutter and React Native. It records the device’s location while your app is open, in the background and after the OS stops the app, keeps every location in an on-device history, and uploads them to your own server or to Beekon Cloud.
From install to your first webhook
Section titled “From install to your first webhook”- Get a first location on the device. The SDK quickstart installs the SDK, asks for permission and starts tracking.
- Send locations to a backend. To your own server: turn on sync and build the ingest endpoint. To Beekon Cloud, in early access: configure Cloud mode with your SDK key.
- Receive a geofence event. On Beekon Cloud, create a geofence and a webhook and watch the
event arrive: your first geofence event. On your
own server, crossings arrive in each upload’s
geofence_events.
SDK quickstart Install the SDK, ask for permissions and receive your first location. One page for all four platforms.
Send locations to your server Turn on sync, read the upload format, and build the endpoint that receives it.
Beekon Cloud and the console The hosted server: watch devices, trips and events, draw geofences and change config remotely.
Server API Read locations, trips and events and manage geofences, config and webhooks from your backend.
Start tracking in a few lines
Section titled “Start tracking in a few lines”// In Application.onCreateBeekon.configure(BeekonConfig.Local())
// In an Activity, from a button in your onboardinglifecycleScope.launch { Beekon.requestNextNeededPermission(this@MainActivity) // foreground location // Later, on its own screen: background location Beekon.requestPermission(this@MainActivity, BeekonPermission.BackgroundLocation) Beekon.start() Beekon.locations.collect { loc -> Log.d("beekon", "${loc.latitude}, ${loc.longitude}") }}// Also call Beekon.registerBackgroundTasks() in App.init()try await Beekon.shared.configure(BeekonConfig.local())
_ = await Beekon.shared.requestNextNeededPermission() // When In Use// Later, on its own screen: the one-time upgrade to Always_ = await Beekon.shared.requestPermission(.backgroundLocation)await Beekon.shared.start()
for await loc in await Beekon.shared.locations { print(loc.latitude, loc.longitude)}await Beekon.instance.configure(BeekonConfig.local());
await Beekon.instance.requestNextNeededPermission(); // foreground location// Later, on its own screen: background locationawait Beekon.instance.requestPermission(BeekonPermission.backgroundLocation);await Beekon.instance.start();
Beekon.instance.locations.listen((loc) { print('${loc.latitude}, ${loc.longitude}');});await Beekon.configure({ mode: 'local' });
await Beekon.requestNextNeededPermission(); // foreground location// Later, on its own screen: background locationawait Beekon.requestPermission('backgroundLocation');await Beekon.start();
const off = Beekon.onLocation((loc) => { console.log(loc.latitude, loc.longitude);});The SDK quickstart adds the OS declarations, error handling and resuming after the OS stops your app.
How Beekon works
Section titled “How Beekon works”- The SDK records. It keeps a location when both a minimum time and a minimum distance have passed since the last one (30 s and 100 m by default), and writes it to a local SQLite history. It applies no other filtering: the coordinates are what the OS reported.
- The SDK uploads, if you ask it to. In Custom mode it uploads batches to your server, with retries and token refresh. In Local mode nothing leaves the device. In Cloud mode it uploads to Beekon Cloud, which also sends the device its settings.
- Your backend uses the data. Your own endpoint receives a small, fixed JSON format, or Beekon Cloud stores the locations, cuts them into trips, detects geofence crossings and sends you webhooks.
Platforms
Section titled “Platforms”All four SDKs are at version 0.6.0 and share one API. Android and iOS are native libraries, written in Kotlin and Swift; Flutter and React Native call them, so tracking behaves the same on every platform.
| SDK | Package | Android | iOS |
|---|---|---|---|
| Android | io.github.beekonlabs:beekon (Maven Central) | 8.0 (API 26) or later | |
| iOS | BeekonKit (Swift Package Manager) | 15 or later | |
| Flutter | beekon_flutter (pub.dev) | 8.0 (API 26) or later | 17 or later |
| React Native | @wayq/beekon-rn (npm), New Architecture, RN 0.76 or later | 8.0 (API 26) or later | 17 or later |
On Android, every SDK needs the app to compile with compileSdk 36 or higher.