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.
Android
Section titled “Android”Android: dependency
Section titled “Android: dependency”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.
Android: permissions
Section titled “Android: permissions”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:
| Permission | Why |
|---|---|
ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION | Location. |
FOREGROUND_SERVICE, FOREGROUND_SERVICE_LOCATION | The tracking service. FOREGROUND_SERVICE_LOCATION is required from Android 14 (API 34). |
POST_NOTIFICATIONS | The service’s notification is visible only with this grant from Android 13 (API 33). |
ACTIVITY_RECOGNITION | Motion detection, when the config uses it. |
RECEIVE_BOOT_COMPLETED | Resuming after a reboot. |
INTERNET, ACCESS_NETWORK_STATE | Sync. |
Android: runtime permission flow
Section titled “Android: runtime permission flow”Android enforces this order:
- Foreground location:
ACCESS_FINE_LOCATIONandACCESS_COARSE_LOCATIONtogether, in one dialog. - 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. - Notifications:
POST_NOTIFICATIONSon 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: foreground-service notification
Section titled “Android: foreground-service notification”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: plain http in development
Section titled “Android: plain http in development”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 athttp://localhost:8080afteradb reverse tcp:8080 tcp:8080. - Cloud mode accepts http only for
localhost,127.0.0.1and::1.
Android: backup rules
Section titled “Android: backup rules”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.
iOS: add the package
Section titled “iOS: add the package”In Xcode, choose File → Add Package Dependencies… and enter:
https://github.com/beekonlabs/beekon-ios-binary.gitSelect version 0.6.0 and add BeekonKit to your app target.
iOS: Info.plist
Section titled “iOS: Info.plist”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>| Key | What it enables |
|---|---|
location background mode | Tracking in the background. |
fetch background mode and com.getbeekon.sdk.sync | The background task that uploads locations while the app is in the background (sync) and runs pauseWithCheckIns check-ins. |
NSMotionUsageDescription | Only when detectActivity is on: activity detection. See Activity detection. |
iOS: background tasks
Section titled “iOS: background tasks”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.
@mainstruct 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.
iOS: authorisation flow
Section titled “iOS: authorisation flow”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:
- Request When In Use. iOS never offers Always first.
- Later, once the user has used the feature, request Always. iOS shows this upgrade prompt at most once.
- 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.
iOS: App Attest capability
Section titled “iOS: App Attest capability”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.
Flutter
Section titled “Flutter”beekon_flutter calls the native Android and iOS SDKs, so background behaviour, the gate and persistence are as the Android and iOS sections describe.
Flutter: install
Section titled “Flutter: install”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 (the plugin needs iOS 17; native BeekonKit runs on iOS 15).
Flutter: OS configuration
Section titled “Flutter: OS configuration”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:
flutter config --enable-swift-package-managerReact Native
Section titled “React Native”@wayq/beekon-rn is a New Architecture TurboModule over the native SDKs. It has no location logic of its own.
React Native: install
Section titled “React Native: install”npm install @wayq/beekon-rn@0.6.0cd ios && pod installReact 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.
React Native: OS configuration
Section titled “React Native: OS configuration”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}Licence key (optional)
Section titled “Licence key (optional)”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.
Next steps
Section titled “Next steps”- Permissions: which permissions your config needs, and how to ask for them.
- Configuration: every field and enum.
- Background execution: what keeps tracking alive on each OS.