# SDK API reference

> Every SDK method and stream on one page, with links to each platform's package and docs.

Source: https://docs.getbeekon.com/reference/api/

The four SDKs share one API: the same method names on Android, iOS, Flutter and React Native, and one stream per feature. Only the language and each platform’s way of exposing a stream differ.

## Methods

| Method                                                      | What it does                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `configure(config)`                                         | Apply settings. Optional; can be called again while tracking ([what applies when](https://docs.getbeekon.com/start/configuration/#live-tuning)). Cloud mode is built with the `BeekonConfig.cloud(...)` factory; see [Configuration](https://docs.getbeekon.com/start/configuration/#cloud-mode).                                                                                                                                                                        |
| `start()`                                                   | Begin tracking. Never throws; watch `state` for the result.                                                                                                                                                                                                                                                                                                                                                          |
| `stop()`                                                    | Stop tracking.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `getCurrentLocation(timeout?, accuracy?)`                   | One location now, whether or not tracking is on. `null` on timeout. The timeout is `timeoutMs` (milliseconds) on Android and React Native, `timeout` in seconds on iOS, and a `Duration` in Flutter; it defaults to 15 s. On iOS 15 and 16 both parameters are ignored ([One-shot fix](https://docs.getbeekon.com/guide/locations/#one-shot-fix)).                                                                                             |
| `getLocations(from, to)`                                    | Read stored history in a time range. With sync on, the history is also the upload queue: locations leave it once the server accepts them.                                                                                                                                                                                                                                                                            |
| `deleteLocations(before?)`                                  | Delete history recorded strictly before `before` (all of it if omitted). Returns how many locations it deleted.                                                                                                                                                                                                                                                                                                      |
| `sync()`                                                    | Force an immediate upload.                                                                                                                                                                                                                                                                                                                                                                                           |
| `setExtras(extras)`                                         | Your own `string → string` fields, sent with every upload.                                                                                                                                                                                                                                                                                                                                                           |
| `setUserId(userId)`                                         | A stable per-user id, bound to each location when it is recorded, so an account switch while offline still attributes queued locations correctly. Trimmed; blank or null clears it. Throws on control characters or more than 256 UTF-8 bytes (so on iOS, call it with `try`). Counts towards MAU. Send an opaque id, never an email or phone number: see [Choosing a user id](https://docs.getbeekon.com/start/concepts/#choosing-a-user-id). |
| `pendingUploadCount()`                                      | Locations not yet uploaded.                                                                                                                                                                                                                                                                                                                                                                                          |
| `addGeofences(geofences)`                                   | Register geofences. Throws `GeofencesManagedByServer` in cloud mode.                                                                                                                                                                                                                                                                                                                                                 |
| `removeGeofences(ids)`                                      | Unregister by id. Also throws `GeofencesManagedByServer` in cloud mode.                                                                                                                                                                                                                                                                                                                                              |
| `listGeofences()`                                           | The current geofences. In Cloud mode, the ones the server delivered to this device.                                                                                                                                                                                                                                                                                                                                  |
| `getPermissionStatus()`                                     | The current location-permission grant, as a [`PermissionStatus`](#permission-status). Never prompts.                                                                                                                                                                                                                                                                                                                 |
| `getRequiredPermissions()`                                  | The permissions the active config needs, each marked required or recommended and satisfied or not. Includes activity recognition and, on Android 13 and later, notifications. Never prompts.                                                                                                                                                                                                                         |
| `requestPermission(permission)`                             | Ask for one permission; returns a [`PermissionRequestResult`](#permission-requests). Android takes a foreground `Activity`. See [Requesting permissions](https://docs.getbeekon.com/start/permissions/#requesting-permissions).                                                                                                                                                                                                                |
| `requestNextNeededPermission()`                             | Ask for the first unsatisfied **required** permission; returns its result, or null (nil on iOS) when none is missing. Never asks for recommended permissions such as background location. Android takes an `Activity`.                                                                                                                                                                                               |
| `openSettings(for permission)`                              | Open the closest OS settings screen, for the `requiresSettings` outcome. Android takes an `Activity`; on iOS it is a static method.                                                                                                                                                                                                                                                                                  |
| `getLog` / `exportLog` / `clearLog` / `setLogLevel` / `log` | [Diagnostics & troubleshooting](https://docs.getbeekon.com/guide/diagnostics/).                                                                                                                                                                                                                                                                                                                                                                |
| `resumeIfNeeded()`                                          | Resume a session that was tracking when the process was killed; does nothing if the user stopped or never started. Android: call it from `Application.onCreate` (a boot receiver covers reboots and app updates). iOS: the SDK calls it at launch and on foreground. Flutter and React Native: call it early in startup. See [Cold-launch resume](https://docs.getbeekon.com/guide/background/#cold-launch-resume).                            |
| `licenseStatus`                                             | The licence status. See [Licensing](https://docs.getbeekon.com/reference/licensing/).                                                                                                                                                                                                                                                                                                                                                          |

On iOS, `setUserId`, `setExtras`, `sync()`, `setLogLevel`, `log` and `getPermissionStatus()` are `nonisolated`, so they need no `await`. iOS also has static methods on `Beekon`:

| iOS static method                           | What it does                                                                                                                                                                                                                                                       |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Beekon.registerBackgroundTasks()`          | Registers the background task for sync and check-ins. Call it once, synchronously, at launch. See [iOS: background tasks](https://docs.getbeekon.com/start/setup/#ios-background-tasks). Flutter’s plugin calls it for you; React Native apps call `BeekonRnImpl.registerBackgroundTasks()`. |
| `Beekon.openSettings(for:)`                 | See the table above.                                                                                                                                                                                                                                               |
| `Beekon.bootstrap()`                        | Starts the SDK early. It runs by itself at process launch, so apps rarely call it.                                                                                                                                                                                 |
| `Beekon.requestNotificationAuthorization()` | Deprecated; use `requestPermission(.notifications)`.                                                                                                                                                                                                               |

Two platforms have methods for the [push probe](https://docs.getbeekon.com/api/events/#the-push-probe) (Cloud mode, SDK 0.6.0 and later). Flutter and React Native have no API for it: call the native methods from the host app. The probe is switched off in Beekon Cloud today, so these change nothing until it is turned on. The [SDK 0.6.0 changelog](https://docs.getbeekon.com/api/changelog/#sdk-060) has an integration example.

| Platform method                                | What it does                                                                                                                                                                                                               |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Android `Beekon.setPushToken(token)`           | Hands Beekon your app’s FCM token. Call it from `onNewToken` and once at launch. `null` or empty clears it. Never logged.                                                                                                  |
| Android `Beekon.handlePushMessage(data)`       | Call it first from `onMessageReceived` with `remoteMessage.data`. Returns `true` for Beekon’s message, which your app then ignores, and `false` for yours. Never throws.                                                   |
| iOS `startMonitoringLocationPushes(appGroup:)` | Call it at every launch after `configure` with the cloud arm. Reports the location-push token and shares what the extension needs through the App Group. Needs the location-push entitlement and **Always** authorisation. |
| iOS `BeekonLocationPush(appGroup:)`            | A separate package product for your Location Push Service Extension. `handle(_:completion:)` answers Beekon’s push and returns `false` for any other.                                                                      |

Each `Location` carries the coordinates and motion fields, plus three optional battery fields sampled when it was recorded: `batteryPercent`, `isCharging` and `powerSaveMode` (null when unknown).

## Streams

One stream per feature. Android exposes a `Flow` or `StateFlow`, iOS an `AsyncStream`, Flutter a Dart `Stream` (`listen` returns a `StreamSubscription`). React Native has `on*` methods that each return an unsubscribe function: `onState`, `onLocation`, `onGeofenceEvent`, `onSyncStatus`, `onAuthTokens`, `onLicenseStatus` and `onLog`.

| Stream           | Delivers                                                                           |
| ---------------- | ---------------------------------------------------------------------------------- |
| `state`          | `Idle` → `Tracking` → `Stopped(reason)` transitions.                               |
| `locations`      | Each location that passes the gate, as it is recorded.                             |
| `geofenceEvents` | Geofence crossings.                                                                |
| `syncStatus`     | `Idle`, `Pending` or `Failed(Auth \| Rejected)`. See [Turn on sync](https://docs.getbeekon.com/guide/sync/). |
| `authChanges`    | New tokens after a refresh (`onAuthTokens` in React Native).                       |
| `logs`           | Diagnostic log entries as they are written.                                        |

The licence status is reported, never enforced. Android has `licenseStatus: StateFlow<LicenseStatus>` (the current value and its changes in one handle). iOS and Flutter have `licenseStatus` plus a `licenseStatusUpdates` stream; React Native has `licenseStatus()` and `onLicenseStatus`. See [Licensing](https://docs.getbeekon.com/reference/licensing/).

Enums your app reads (`StopReason`, `ActivityType`, `SyncFailure`, `LocationQuality` and others) may gain values in a minor release, so give every `switch` an `else` or `default` branch. `StopReason` includes `backgroundStartDenied` on every platform, but only Android emits it (Flutter and React Native included): a resume started in the background was refused a foreground service. The session stays resumable, and a later `start()` or `resumeIfNeeded()` recovers it. See [Stop reasons](https://docs.getbeekon.com/guide/lifecycle/#stop-reasons).

## Permission status

`getPermissionStatus()` and the `status` of every [permission request](#permission-requests) return a `PermissionStatus`. It is a snapshot: once tracking runs, a lost permission arrives on `state` as `Stopped(PermissionDenied)`, so watch `state` rather than polling this.

| Field                  | Type                                                                                                    | Meaning                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `level`                | `PermissionStatus.Level` (Flutter `PermissionLevel`, React Native `PermissionLevel`)                    | How far the location grant reaches (below).                                       |
| `accuracy`             | `PermissionStatus.Accuracy?` (Flutter `PermissionAccuracy?`, React Native `PermissionAccuracy \| null`) | `full` (precise) or `reduced` (approximate); `null` when location is not granted. |
| `isAuthorized`         | boolean                                                                                                 | `true` when `level` is `foreground` or `background`.                              |
| `canTrackInBackground` | boolean                                                                                                 | `true` when `level` is `background`.                                              |

| `level`         | Meaning                                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `notDetermined` | No location permission. On Android this also covers a permission the user denied: without an `Activity`, Android can’t tell the two apart. |
| `denied`        | The user denied location. iOS only; they can change it in Settings.                                                                        |
| `restricted`    | A policy the user can’t change blocks location (for example a device-management profile or Screen Time). iOS only.                         |
| `foreground`    | Granted while the app is in use. On Android, without `ACCESS_BACKGROUND_LOCATION`.                                                         |
| `background`    | Granted at all times. On Android before 10 (API 29), any grant is `background`.                                                            |

Casing follows the platform: Android `Level.NotDetermined` and `Accuracy.Full`, iOS `.notDetermined` and `.full`, Flutter `PermissionLevel.notDetermined` and `PermissionAccuracy.full`, React Native `'notDetermined'` and `'full'`. `level` may gain values in a minor release.

## Permission requests

`requestPermission(...)` and `requestNextNeededPermission()` return a `PermissionRequestResult`:

| Field          | Type                       | Present when                                                                                                |
| -------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `outcome`      | `PermissionRequestOutcome` | always                                                                                                      |
| `prerequisite` | `BeekonPermission?`        | `outcome == blocked`: ask for this permission first                                                         |
| `reason`       | `String?`                  | `outcome == notAttempted`: `missing_manifest_entry`, `missing_plist_key`, `unsupported` or `not_foreground` |
| `status`       | `PermissionStatus`         | always: the grant after the request                                                                         |

`PermissionRequestOutcome` is one of `granted`, `denied`, `requiresSettings`, `alreadySatisfied`, `blocked` and `notAttempted`, and may gain values in a minor release. Casing follows the platform: Android `Granted`, iOS `.granted`, Flutter `PermissionRequestOutcome.granted`, React Native `'granted'`. What each means is on [Requesting permissions](https://docs.getbeekon.com/start/permissions/#requesting-permissions).

On iOS, `requestNotificationAuthorization()` is deprecated in favour of `requestPermission(.notifications)` and will be removed before 1.0.

## Per-platform reference

Every type and signature is in each SDK’s package and its docs:

[Android on Maven Central ](https://central.sonatype.com/artifact/io.github.beekonlabs/beekon)io.github.beekonlabs:beekon.

[iOS binary package ](https://github.com/beekonlabs/beekon-ios-binary)BeekonKit for Swift Package Manager, on GitHub.

[Flutter on pub.dev ](https://pub.dev/documentation/beekon_flutter/latest/)Dartdoc for beekon\_flutter.

[React Native on npm ](https://www.npmjs.com/package/@wayq/beekon-rn)@wayq/beekon-rn, fully typed.
