Skip to content

Platform setup

This page lists the OS declarations Beekon needs: what goes in the Android manifest, the iOS Info.plist and app launch code. Asking for the permissions at runtime is on Permissions, and the first-location walkthrough is the SDK quickstart.

Each platform has its own section: Android, iOS, Flutter and React Native. Flutter and React Native apps also need the Android and iOS declarations.

app/build.gradle.kts
android {
compileSdk = 36 // or higher: the library requires it
defaultConfig {
minSdk = 26 // Beekon's minimum: Android 8.0
}
}
dependencies {
implementation("io.github.beekonlabs:beekon:0.6.0")
}

Build with JDK 17 and compileSdk 36 or higher; with a lower compileSdk, the build stops at checkAarMetadata. The library is compiled with Kotlin 2.x and explicitApi(); your app can use another Kotlin 2 version.

Add ACCESS_BACKGROUND_LOCATION to app/src/main/AndroidManifest.xml. Beekon’s library manifest does not declare it, and a request for background location without it returns notAttempted with reason missing_manifest_entry.

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

These merge in from Beekon’s manifest at build time; you don’t declare them:

PermissionWhy
ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATIONLocation.
FOREGROUND_SERVICE, FOREGROUND_SERVICE_LOCATIONThe tracking service. FOREGROUND_SERVICE_LOCATION is required from Android 14 (API 34).
POST_NOTIFICATIONSThe service’s notification is visible only with this grant from Android 13 (API 33).
ACTIVITY_RECOGNITIONMotion detection, when the config uses it.
RECEIVE_BOOT_COMPLETEDResuming after a reboot.
INTERNET, ACCESS_NETWORK_STATESync.

Android enforces this order:

  1. Foreground location: ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION together, in one dialog.
  2. Background location: ACCESS_BACKGROUND_LOCATION, separately and only after step 1 (Android 10, API 29, and later). On Android 11 and later this opens a settings page instead of a dialog.
  3. Notifications: POST_NOTIFICATIONS on Android 13 (API 33) and later.

The SDK’s requestPermission follows this order and refuses a request the OS would drop silently. To write your own flow instead, use two RequestMultiplePermissions launchers, one per tier.

Android shows a notification while an app captures location in the background. Every BeekonConfig carries a NotificationConfig for it in its notification field. The title defaults to “Tracking location”; set your own title, text and icon as shown on Configuration. The channel id and notification id are fixed by the SDK.

Android 9 (API 28) and later block cleartext http by default. To test against a server on your computer over http, allow cleartext for that host in a debug-only network security config, and use https in release builds.

  • In Custom mode, the emulator reaches your computer at http://10.0.2.2:8080, or at http://localhost:8080 after adb reverse tcp:8080 tcp:8080.
  • Cloud mode accepts http only for localhost, 127.0.0.1 and ::1.

Nothing is required. Beekon’s manifest sets no backup attributes, so your app’s own android:fullBackupContent and android:dataExtractionRules merge as they are, with no tools:replace. For device integrity the SDK keeps its install id out of backups and device transfer by itself: the id lives in the no-backup files directory, and on the first start after a restore or a transfer the SDK clears its other state and starts as a new install.

Optionally, to keep the SDK’s preferences out of your app’s backup, add these lines to your rules, inside <full-backup-content>, and inside both <cloud-backup> and <device-transfer> of <data-extraction-rules>:

<exclude domain="sharedpref" path="beekon_prefs.xml" />
<exclude domain="sharedpref" path="beekon_secure_prefs.xml" />
<exclude domain="sharedpref" path="beekon_cloud_secure_prefs.xml" />
<exclude domain="sharedpref" path="beekon_headers_secure_prefs.xml" />

BeekonKit is a Swift package distributed as a signed binary .xcframework. It runs on iOS 15 and later. On iOS 17 and later it uses CLLocationUpdate.liveUpdates with a CLBackgroundActivitySession (plus CLServiceSession on iOS 18 and later); on iOS 15 and 16 it uses the classic Core Location and CLRegion engines.

In Xcode, choose File → Add Package Dependencies… and enter:

https://github.com/beekonlabs/beekon-ios-binary.git

Select version 0.6.0 and add BeekonKit to your app target.

Add the two location usage strings, the location and fetch background modes, and the background task identifier. The usage strings appear in the system dialogs, so write them in your app’s voice.

<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to show your live position in the app.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Used to keep tracking your trips when the app is in the background.</string>
<key>UIBackgroundModes</key>
<array>
<string>location</string>
<string>fetch</string>
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
<string>com.getbeekon.sdk.sync</string>
</array>
KeyWhat it enables
location background modeTracking in the background.
fetch background mode and com.getbeekon.sdk.syncThe background task that uploads locations while the app is in the background (sync) and runs pauseWithCheckIns check-ins.
NSMotionUsageDescriptionOnly when detectActivity is on: activity detection. See Activity detection.

Call Beekon.registerBackgroundTasks() once, synchronously, while the app launches: in App.init() for SwiftUI, or in application(_:didFinishLaunchingWithOptions:). iOS accepts background task handlers only before launch finishes, so a later call has no effect.

@main
struct MyApp: App {
init() { Beekon.registerBackgroundTasks() }
var body: some Scene { WindowGroup { ContentView() } }
}

Without it, background sync and check-ins never run, and start() logs a warning on the logs stream. The task is a BGAppRefreshTask, which iOS schedules at its own discretion: every 15 minutes or so for an app used often, hours apart or not at all for one used rarely. Tracking itself does not depend on it.

Tracking started in the foreground keeps running in the background with When In Use and the location background mode. Always adds resuming after a stationary pause, relaunching after iOS stops the app, and geofences; with When In Use only, Beekon skips the stationary pause and tracks at full power while the device is still (see Authorisation). iOS grants Always in two steps:

  1. Request When In Use. iOS never offers Always first.
  2. Later, once the user has used the feature, request Always. iOS shows this upgrade prompt at most once.
  3. Call Beekon.shared.start().

requestPermission(.backgroundLocation) performs the upgrade and reports requiresSettings once the one prompt is used up. To use Core Location directly instead, make the two calls below; wire them to two separate buttons:

private let manager = CLLocationManager()
func requestWhenInUse() { manager.requestWhenInUseAuthorization() }
func requestAlways() { manager.requestAlwaysAuthorization() }

To reach a server on your computer over plain http while developing, add NSAppTransportSecurity → NSAllowsLocalNetworking to a debug Info.plist.

For device integrity in Cloud mode, add the App Attest capability to the app target (Xcode → Signing & Capabilities → + Capability → App Attest), so the app’s .entitlements file contains:

<key>com.apple.developer.devicecheck.appattest-environment</key>
<string>production</string>

Use production for App Store, TestFlight, ad-hoc and Enterprise builds, and development only for development builds; the environment must match the app you register in the console. Without the capability the app still tracks and syncs, but its locations stay unverified. The location-push extension needs nothing.

beekon_flutter calls the native Android and iOS SDKs, so background behaviour, the gate and persistence are as the Android and iOS sections describe.

pubspec.yaml
dependencies:
beekon_flutter: ^0.6.0
Terminal window
flutter pub get

Flutter 3.35 or later (Dart 3.9). Android 8.0 (API 26) or later with compileSdk 36 or higher, iOS 17 or later (the plugin needs iOS 17; native BeekonKit runs on iOS 15).

Add the declarations from the Android and iOS sections: ACCESS_BACKGROUND_LOCATION in the Android manifest; the usage strings, the location and fetch background modes and BGTaskSchedulerPermittedIdentifiers in the iOS Info.plist. The plugin calls Beekon.registerBackgroundTasks() for you at launch.

For device integrity, add the App Attest capability to the Runner target. Android needs nothing (backup rules are optional).

The iOS side is distributed with Swift Package Manager only; there is no podspec. On Flutter older than 3.44, turn Swift Package Manager on once:

Terminal window
flutter config --enable-swift-package-manager

@wayq/beekon-rn is a New Architecture TurboModule over the native SDKs. It has no location logic of its own.

Terminal window
npm install @wayq/beekon-rn@0.6.0
cd ios && pod install

React Native 0.76 or later with the New Architecture, iOS 17 or later, Android 8.0 (API 26) or later with compileSdk 36 or higher. Android links automatically.

Add the declarations from the Android and iOS sections: ACCESS_BACKGROUND_LOCATION in the Android manifest; the usage strings, the location and fetch background modes and BGTaskSchedulerPermittedIdentifiers in the iOS Info.plist.

For device integrity, add the App Attest capability to the app target. Android needs nothing (backup rules are optional).

Then register the background task in AppDelegate.swift. Unlike Flutter, the React Native module does not do this for you:

import BeekonRn
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions:
[UIApplication.LaunchOptionsKey: Any]? = nil
) -> Bool {
BeekonRnImpl.registerBackgroundTasks()
// ...your existing setup...
return true
}

A licence key is optional and never blocks tracking. Without one, Beekon runs in evaluation mode with every feature. If you have a production key, pass it to configure and read its status as shown on Licensing.