The Beekon SDK, in detail

A native background-location library for Android and iOS, with Flutter and React Native wrappers over the same two libraries. It records where the phone goes after the app is swiped away, keeps a week of points on the device, and sends them where you choose: nowhere, your server, or Beekon Cloud.

Android
Kotlin, Android 8 and up
iOS
Swift, iOS 13 and up
Wrappers
Flutter and React Native

What ships in the library

Every feature, geofencing included, on every licence. Without a licence key the SDK runs in evaluation mode and logs one notice.

The API: configure, start, listen

One config object, one start call and a stream of locations. The names follow each language: a Flow in Kotlin, an AsyncStream in Swift, a Stream in Dart, an event subscription in TypeScript.

Configure is optional. The defaults are a 100 m or 30 s gate, Balanced accuracy, and a pause while the phone is still.

Every configuration option
MainActivity.ktMaven Central · io.github.beekonlabs:beekon

Background tracking, per operating system. Native code on each, because the rules differ.

Android

The SDK runs a foreground service with its own notification, which the system keeps alive under battery savers and the aggressive settings some phone makers add. After a restart it resumes on its own. Location comes from the fused provider; the SDK applies only your distance and time gates.

iOS

The SDK uses the platform's background location mode, and the system wake-up that fires when the user moves a meaningful distance brings the app back after iOS has suspended it. You ask for permission with your own screens; the SDK only needs the result.

The SDK does not smooth or filter locations. The phone's location service already combines GPS, Wi-Fi and motion; you get the fixes it reports, kept or dropped by your distance and time gates.

Accuracy modes and what they cost in battery

Measured on real phones, per hour of tracking. One setting, changeable at run time.

Swipe sideways to see every column.

ModeDistance floorIntervalBattery an hourUse it for
Low500 m60 s3–8%Always-on apps where battery matters more than precision
Balanced100 m30 s5–10%The default: trips, check-ins, commute logging
High30 m10 s15–25%Live tracking and route recording while the app is in front

Stationary pause

With whenStationary = Pause the SDK stops asking for fixes while the phone does not move, and starts again on the first movement. Most of the battery saving on a parked van comes from here.

Distance and time gates

A fix is kept when it is at least the distance floor from the last one, or the interval has passed. Nothing is averaged or snapped.

Offline history on the phone

Every kept fix goes into a database inside the SDK first. With no network the points wait there and upload in order when it returns, so a tunnel or a dead zone loses nothing.

Your app can read the last seven days at any time, online or not. Older points are pruned automatically; the window is a setting.

How history and upload work

Van 12, 11:46 to 12:04

Nine minutes in a tunnel: nine points saved on the phone, nine uploaded at 12:01, none lost.

Three destinations, one line of config

On the phone

Nothing leaves the device. History stays in the SDK's database and your app is the only reader.

BeekonConfig.local()

Your own server

The SDK uploads a documented, byte-exact envelope to an endpoint you run. Write your own receiver, or self-host the Beekon Cloud stack. Your data never touches our servers.

BeekonConfig.custom(sync:)

Beekon Cloud

Fully managed. The server holds the tracking config and the geofences, meters usage and gives you a console, webhooks and a REST API.

BeekonConfig.cloud(projectKey:)

Beekon Cloud: the console and servers behind the SDK. Switch it on with one line of config.

The console

Every device with its last fix, each trail with the events the SDK recorded, geofences drawn on a map, usage by project and day, webhooks and their deliveries, keys and billing.

See the console

Server-side geofences

Draw a fence once in the console or the API; it is evaluated on our side for every device in the project. Enter, exit and dwell events reach your app and your webhooks.

Geofences in the docs

Webhooks and the REST API

Events and points by HTTPS to your endpoint, signed, with retries you can see. The same data by REST for your dispatch screen or your warehouse.

The API reference

Data where you choose

Each project is stored in one region, India or the United States, and device data never leaves it. Erase one user or export a project from the console; retention is a plan setting you can see.

Device attestation

Beekon Cloud accepts points only from installs of your app that pass hardware-backed attestation on Android and iOS.

Load tested

389,520 devices in one load test, with no point lost.

Evaluation, then a licence key

Without a key the SDK runs fully, with a notice in your logs. During early access, licence keys go to teams on the waitlist.

How licensing works

Individual

One person building their own apps, declared at sign-up. Every feature, with a year of updates you renew free.

Organisation

A team or company buys the licence once and keeps it for life. Yearly maintenance keeps newer versions coming; stop renewing and your current versions keep working.

With Beekon Cloud

Paid Beekon Cloud plans will carry the organisation licence for every app on the account.