Skip to content
Beekon

Android setup

The Beekon .aar declares the permissions it needs in its own manifest, and they merge into your app at build time. You still need to request the dangerous permissions at runtime and provide a NotificationConfig for the foreground service.

Dependency

Section titled “Dependency”
app/build.gradle.kts
android {
  defaultConfig {
    minSdk = 26       // Beekon's minimum
  }
}


dependencies {
  implementation("io.github.wayqteam:beekon:0.0.3")
}

The module requires JDK 17 to build and ships with explicitApi() enforced — your consuming app’s Kotlin version doesn’t have to match, but Kotlin 2.x is recommended.

Permissions

Section titled “Permissions”

These are in Beekon’s manifest already; if you want to see them in your merged manifest, add them to app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

FOREGROUND_SERVICE_LOCATION is required from Android 14 (API 34). POST_NOTIFICATIONS is required from Android 13 (API 33) for the foreground-service notification to be visible.

Runtime permission flow

Section titled “Runtime permission flow”

Android forces a three-step prompt sequence — you cannot ask for background location without first having foreground location, and notifications need their own grant on Android 13+.

  1. Request ACCESS_FINE_LOCATION + ACCESS_COARSE_LOCATION together (single dialog).
  2. On API 29+, request ACCESS_BACKGROUND_LOCATION separately. This always opens Settings on API 30+.
  3. On API 33+, request POST_NOTIFICATIONS.

The Compose sample at beekon-android/sample ships a LocationPermissions composable that walks through this exact sequence — copy from there if you don’t already have a permissions helper.

Foreground service notification

Section titled “Foreground service notification”

BeekonConfig.notification is required — Android requires a visible foreground-service notification while location is being captured in the background.

NotificationConfig(
  channelId = "beekon-tracking",
  channelName = "Tracking",          // shown in Settings → Notifications
  notificationId = 7411,             // any non-zero int unique to your app
  title = "Beekon",                  // notification title
  text = "Tracking your location",   // notification body
  smallIcon = R.drawable.ic_stat_beekon, // monochrome white-on-transparent
)

Beekon creates the NotificationChannel for you on Android 8+. Pick a channelId that’s specific to this notification — users can disable individual channels in Settings.

Initialise once

Section titled “Initialise once”
class App : Application() {
  override fun onCreate() {
    super.onCreate()
    Beekon.initialize(this)
    Beekon.configure(
      BeekonConfig(
        intervalSeconds = 30,
        distanceMeters = 100.0,
        notification = BeekonConfig.Notification(
          title = "Beekon",
          text = "Tracking your location",
          smallIcon = R.drawable.ic_stat_beekon,
        ),
      ),
    )
  }
}

initialize is idempotent — calling it twice is harmless. configure can be called again at any time, including while tracking, to change the gate values; it takes effect on the next admitted fix without restarting the location subscription.

All Notification fields are optional. Leave them null to inherit the host app’s label and launcher icon. Channel id and notification id are SDK-internal constants — hosts don’t customise them.

When start() will fail

Section titled “When start() will fail”

Beekon.start() is suspend and throws typed errors:

ThrowsWhen
BeekonError.PermissionDeniedACCESS_FINE_LOCATION not granted
BeekonError.LocationServicesDisabledsystem location services off, or Google Play Services missing/out of date
BeekonError.StorageFailure(cause)SQLite/filesystem failure reading or writing history

See Errors for what to do about each.

Background reliability

Section titled “Background reliability”

Once start() returns, Beekon runs a foreground service with FOREGROUND_SERVICE_LOCATION type and consumes FusedLocationProviderClient updates. Cold-launch resume after process death is host-driven — Android 15+ blocks BOOT_COMPLETED from launching a foreground service, so if you want background tracking to survive process death, call Beekon.start() from your Application.onCreate. The SDK rehydrates the last BeekonConfig from SharedPreferences and re-arms the gate.

Be aware that aggressive OEM battery managers (Xiaomi, Huawei, Samsung, OPPO, Vivo) can still kill the service. The dontkillmyapp.com matrix lists the per-OEM workarounds you may need to surface to users.

Next

Section titled “Next”