# Platform setup

> The OS configuration Beekon needs on each platform: the Android dependency and manifest, iOS Info.plist keys, background modes and tasks, and Flutter and React Native specifics.

Source: https://docs.getbeekon.com/start/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](https://docs.getbeekon.com/start/permissions/), and the first-location walkthrough is the [SDK quickstart](https://docs.getbeekon.com/start/).

Each platform has its own section: [Android](#android), [iOS](#ios), [Flutter](#flutter) and [React Native](#react-native). Flutter and React Native apps also need the Android and iOS declarations.

## Android

### Android: dependency

app/build.gradle.kts

```kotlin
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

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`.

```xml
<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

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`](https://docs.getbeekon.com/start/permissions/#requesting-permissions) 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

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](https://docs.getbeekon.com/start/configuration/#notificationconfig). The channel id and notification id are fixed by the SDK.

### 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 at `http://localhost:8080` after `adb reverse tcp:8080 tcp:8080`.
* Cloud mode accepts http only for `localhost`, `127.0.0.1` and `::1`.

### 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](https://docs.getbeekon.com/guide/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>`:

```xml
<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" />
```

## iOS

`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

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

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

Select version `0.6.0` and add `BeekonKit` to your app target.

Embed & Sign

The framework is dynamic. Set **General → Frameworks, Libraries, and Embedded Content → BeekonKit** to **Embed & Sign** on your app target, or the framework is not copied into your `.app`.

### 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.

```xml
<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](https://docs.getbeekon.com/guide/activity/).                            |

### 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.

```swift
@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](https://docs.getbeekon.com/guide/diagnostics/#the-log-surface). 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

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](https://docs.getbeekon.com/guide/background/#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)`](https://docs.getbeekon.com/start/permissions/#requesting-permissions) 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:

```swift
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

For [device integrity](https://docs.getbeekon.com/guide/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:

```xml
<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

`beekon_flutter` calls the native Android and iOS SDKs, so background behaviour, the gate and persistence are as the [Android](#android) and [iOS](#ios) sections describe.

### Flutter: install

pubspec.yaml

```yaml
dependencies:
  beekon_flutter: ^0.6.0
```

```sh
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).

### Flutter: OS configuration

Add the declarations from the [Android](#android-permissions) and [iOS](#ios-infoplist) 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](https://docs.getbeekon.com/guide/integrity/), add the [App Attest capability](#ios-app-attest-capability) to the `Runner` target. Android needs nothing ([backup rules](#android-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:

```sh
flutter config --enable-swift-package-manager
```

detectActivity needs one more permission

With `detectActivity: true`, add `NSMotionUsageDescription` on iOS (required). On Android, `ACTIVITY_RECOGNITION` merges in from Beekon’s manifest but still needs a runtime grant. Without the grant, `Location.activity` is `null`. See [Activity detection](https://docs.getbeekon.com/guide/activity/).

## 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

```sh
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.

### React Native: OS configuration

Add the declarations from the [Android](#android-permissions) and [iOS](#ios-infoplist) 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](https://docs.getbeekon.com/guide/integrity/), add the [App Attest capability](#ios-app-attest-capability) to the app target. Android needs nothing ([backup rules](#android-backup-rules) are optional).

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

```swift
import BeekonRn


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

detectActivity needs one more permission

With `detectActivity: true`, add `NSMotionUsageDescription` on iOS (required). On Android, `ACTIVITY_RECOGNITION` merges in from Beekon’s manifest but still needs a runtime grant. Without the grant, `location.activity` is `null`.

## 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](https://docs.getbeekon.com/reference/licensing/).

## Next steps

* [Permissions](https://docs.getbeekon.com/start/permissions/): which permissions your config needs, and how to ask for them.
* [Configuration](https://docs.getbeekon.com/start/configuration/): every field and enum.
* [Background execution](https://docs.getbeekon.com/guide/background/): what keeps tracking alive on each OS.
