Skip to content

SDK quickstart

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.

app/build.gradle.kts
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.

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.Application
import com.getbeekon.sdk.AccuracyMode
import com.getbeekon.sdk.Beekon
import com.getbeekon.sdk.BeekonConfig
import com.getbeekon.sdk.NotificationConfig
import com.getbeekon.sdk.StationaryMode
import com.getbeekon.sdk.TrackingConfig
import kotlinx.coroutines.MainScope
import 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.

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:

  1. 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.
  2. Background location. Ask for it yourself with requestPermission(backgroundLocation) after foreground location is granted: it is recommended, not required, so requestNextNeededPermission() 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)
}

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.

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
}

The locations stream delivers each location that passes the gate. The state stream tells you when tracking stops and why.

import android.util.Log
import androidx.lifecycle.lifecycleScope
import com.getbeekon.sdk.Beekon
import com.getbeekon.sdk.BeekonState
import com.getbeekon.sdk.StopReason
import 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 -> {}
}
}
}

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.

  1. Send locations to a backend: your own server with Turn on sync, or Beekon Cloud with Cloud mode.
  2. Finish the OS declarations on Platform setup, so tracking keeps running in the background.
  3. Tune the gate and accuracy on Configuration.
  4. Learn the state machine behind state on Lifecycle & states.

A licence key is optional; if you have one, see Licensing.