This page takes you from an empty app to your first locations in five steps: install, configure, request permissions, start, subscribe. Pick your platform once; the tabs stay in sync across the site.
1. Install
Section titled “1. Install”dependencies { implementation("io.github.beekonlabs:beekon:0.6.0")}Android 8.0 (API 26) or later, compileSdk = 36 or higher, JDK 17, Kotlin 2.x. The package is on Maven Central, which Gradle includes by default.
In Xcode, choose File → Add Package Dependencies… and enter:
https://github.com/beekonlabs/beekon-ios-binary.gitSelect version 0.6.0, add BeekonKit to your app target and set it to Embed & Sign. iOS 15 or later; on iOS 17 and later the SDK uses the CLLocationUpdate stack automatically.
dependencies: beekon_flutter: ^0.6.0flutter pub getFlutter 3.35 or later (Dart 3.9). Android 8.0 (API 26) or later with compileSdk 36 or higher, iOS 17 or later.
npm install @wayq/beekon-rn@0.6.0cd ios && pod installReact Native 0.76 or later with the New Architecture. Android 8.0 (API 26) or later with compileSdk 36 or higher, iOS 17 or later. Android links automatically.
2. Configure
Section titled “2. Configure”configure sets the gate: the minimum time and distance between stored locations. It is optional. Without it, Beekon uses 30 s and 100 m, balanced accuracy, and pauses while the device is still. Every field is on Configuration.
The SDK initialises itself through AndroidX Startup. Call configure once in Application.onCreate, and register the class with android:name=".App" on the <application> element of your manifest.
import android.app.Applicationimport com.getbeekon.sdk.AccuracyModeimport com.getbeekon.sdk.Beekonimport com.getbeekon.sdk.BeekonConfigimport com.getbeekon.sdk.NotificationConfigimport com.getbeekon.sdk.StationaryModeimport com.getbeekon.sdk.TrackingConfigimport kotlinx.coroutines.MainScopeimport kotlinx.coroutines.launch
class App : Application() { override fun onCreate() { super.onCreate() Beekon.configure( BeekonConfig.Local( tracking = TrackingConfig( minTimeBetweenLocationsSeconds = 30, minDistanceBetweenLocationsMeters = 100.0, accuracyMode = AccuracyMode.Balanced, whenStationary = StationaryMode.Pause, ), notification = NotificationConfig( title = "Tracking location", text = "Capturing your trip", ), ), ) // Resumes a session that was running when Android killed the process. MainScope().launch { Beekon.resumeIfNeeded() } // suspend; never throws }}NotificationConfig is the text of the foreground-service notification Android shows while tracking. Its title defaults to “Tracking location”. resumeIfNeeded() does nothing unless a session was running when the process died; see Cold-launch resume.
Beekon.shared is an actor and needs no initialisation. Two things happen at launch:
Beekon.registerBackgroundTasks(), once and synchronously, before launch finishes. It registers the background task that runs sync and check-ins. iOS ignores a registration made later.configure, which isasync throws. Await it before you callstart().
import BeekonKitimport SwiftUI
@mainstruct MyApp: App { init() { Beekon.registerBackgroundTasks() // synchronous; must run during launch }
var body: some Scene { WindowGroup { ContentView() .task { do { try await Beekon.shared.configure( BeekonConfig.local( tracking: TrackingConfig( minTimeBetweenLocationsSeconds: 30, minDistanceBetweenLocationsMeters: 100, accuracyMode: .balanced, whenStationary: .pause ) ) ) } catch { print("Beekon configure failed: \(error)") } } } }}If your app uses a UIApplicationDelegate instead of the SwiftUI App lifecycle, call both from application(_:didFinishLaunchingWithOptions:): registerBackgroundTasks() directly, configure inside a Task. The SDK resumes an interrupted session by itself on iOS.
The native SDKs initialise themselves, and the plugin registers the iOS background task for you. configure is async.
import 'package:beekon_flutter/beekon_flutter.dart';import 'package:flutter/widgets.dart';
Future<void> main() async { WidgetsFlutterBinding.ensureInitialized(); // platform channels before runApp await Beekon.instance.configure( BeekonConfig.local( tracking: const TrackingConfig( minTimeBetweenLocationsSeconds: 30, minDistanceBetweenLocationsMeters: 100, accuracyMode: AccuracyMode.balanced, whenStationary: StationaryMode.pause, ), ), ); await Beekon.instance.resumeIfNeeded(); // resumes a session the OS killed runApp(const MyApp());}resumeIfNeeded() does nothing unless a session was running when the app was killed. See Cold-launch resume.
The native SDKs initialise themselves. configure is async. The React Native samples on this site use top-level await for brevity; run them inside an async function such as your startup code.
import { Beekon } from '@wayq/beekon-rn';
await Beekon.configure({ mode: 'local', tracking: { minTimeBetweenLocationsSeconds: 30, minDistanceBetweenLocationsMeters: 100, accuracyMode: 'balanced', whenStationary: 'pause', },});await Beekon.resumeIfNeeded(); // resumes a session the OS killedOn iOS, also register the background task in AppDelegate.swift, inside application(_:didFinishLaunchingWithOptions:):
import BeekonRn
BeekonRnImpl.registerBackgroundTasks()3. Request permissions
Section titled “3. Request permissions”Add the OS declarations from Platform setup first. On Android that is ACCESS_BACKGROUND_LOCATION in your manifest; on iOS it is the two location usage strings, the location and fetch background modes and the background task identifier.
Then ask at runtime, in two steps:
- Foreground location.
requestNextNeededPermission()asks for the first missing required permission, one OS prompt per call, and returns null (nil on iOS) when none is left. For a typical config the only required permission is foreground location. - Background location. Ask for it yourself with
requestPermission(backgroundLocation)after foreground location is granted: it is recommended, not required, sorequestNextNeededPermission()never asks for it. It lets tracking resume after the OS stops your app and powers geofences. Without it, tracking you start in the foreground still runs in the background but doesn’t come back once the OS stops your app; the details are on Permissions.
Call each from a button in your onboarding, after your own explanation of why the app needs it.
import com.getbeekon.sdk.BeekonPermission
// In an Activity; both calls need the Activity in the foreground.lifecycleScope.launch { // 1. Foreground location (null when nothing required is missing). Beekon.requestNextNeededPermission(this@MainActivity)
// 2. Background location, on a later screen. On Android 11 and later // this opens the system page where the user picks "Allow all the time". Beekon.requestPermission(this@MainActivity, BeekonPermission.BackgroundLocation)}// 1. Foreground location: the When In Use prompt// (nil when nothing required is missing)._ = await Beekon.shared.requestNextNeededPermission()
// 2. Background location, on a later screen: the one-time upgrade to Always._ = await Beekon.shared.requestPermission(.backgroundLocation)// 1. Foreground location (null when nothing required is missing).await Beekon.instance.requestNextNeededPermission();
// 2. Background location, on a later screen.await Beekon.instance.requestPermission(BeekonPermission.backgroundLocation);// 1. Foreground location (null when nothing required is missing).await Beekon.requestNextNeededPermission();
// 2. Background location, on a later screen.await Beekon.requestPermission('backgroundLocation');Each call returns a result whose outcome says what happened. When it is requiresSettings, the OS will not prompt again: call openSettings(...) to send the user to the app’s settings. Every outcome, and the other recommended permissions (activity recognition, notifications), are on Permissions.
4. Start tracking
Section titled “4. Start tracking”start() brings up the platform’s background machinery: a foreground service on Android, a CLBackgroundActivitySession on iOS. It never throws. A missing permission or a refusal from the OS shows up as Stopped(reason) on the state stream.
lifecycleScope.launch { Beekon.start() // suspend; never throws}await Beekon.shared.start() // never throwsawait Beekon.instance.start(); // never throwsawait Beekon.start(); // never throws5. Subscribe to locations
Section titled “5. Subscribe to locations”The locations stream delivers each location that passes the gate. The state stream tells you when tracking stops and why.
import android.util.Logimport androidx.lifecycle.lifecycleScopeimport com.getbeekon.sdk.Beekonimport com.getbeekon.sdk.BeekonStateimport com.getbeekon.sdk.StopReasonimport kotlinx.coroutines.launch
// In an Activity. collect never returns, so each stream gets its own coroutine.// locations is a SharedFlow: no replay, a 64-item buffer, oldest dropped first.lifecycleScope.launch { Beekon.locations.collect { loc -> Log.d( "beekon", "${loc.latitude}, ${loc.longitude} acc=${loc.accuracy ?: "?"} m", ) }}
lifecycleScope.launch { Beekon.state.collect { s -> if (s is BeekonState.Stopped) when (s.reason) { StopReason.PermissionDenied -> { /* ask for location, then start() again */ } StopReason.LocationServicesDisabled -> { /* Location is off in system settings */ } else -> {} } }}Task { for await loc in await Beekon.shared.locations { let acc = loc.accuracy.map { "\($0)" } ?? "?" print("\(loc.latitude), \(loc.longitude) acc=\(acc) m") }}
Task { for await s in await Beekon.shared.state { if case let .stopped(reason) = s { switch reason { case .permissionDenied: break // ask for location, then start() again case .locationServicesDisabled: break // Location Services are off default: break } } }}// Each stream is a Dart Stream. Call cancel() on the subscription to stop// listening.final locationSub = Beekon.instance.locations.listen((loc) { print('${loc.latitude}, ${loc.longitude}');});
final stateSub = Beekon.instance.state.listen((state) { if (state is Stopped && state.reason == StopReason.permissionDenied) { // Ask for location, then start() again. }});// Each subscription returns a function that unsubscribes.const offLocation = Beekon.onLocation((loc) => { console.log(loc.latitude, loc.longitude);});
const offState = Beekon.onState((state) => { if (state.kind === 'stopped' && state.reason === 'permissionDenied') { // Ask for location, then start() again. }});Every location is also written to an on-device SQLite history that survives process death. Read a time range with getLocations(from, to); see Locations & history.
Next steps
Section titled “Next steps”- Send locations to a backend: your own server with Turn on sync, or Beekon Cloud with Cloud mode.
- Finish the OS declarations on Platform setup, so tracking keeps running in the background.
- Tune the gate and accuracy on Configuration.
- Learn the state machine behind
stateon Lifecycle & states.
A licence key is optional; if you have one, see Licensing.