# Configuration

> The reference for BeekonConfig and TrackingConfig: the time and distance gate, every field, the enums, Cloud mode, the Android notification, and changing values while tracking.

Source: https://docs.getbeekon.com/start/configuration/

`BeekonConfig` has three modes:

| Mode       | Who owns the config               | Uploads                                                |
| ---------- | --------------------------------- | ------------------------------------------------------ |
| **Local**  | Your app                          | None. Locations stay on the device.                    |
| **Custom** | Your app                          | To your own server, through the required `sync` field. |
| **Cloud**  | The server, through a project key | To [Beekon Cloud](https://docs.getbeekon.com/cloud/).                            |

Local and Custom carry the same `TrackingConfig`. This page is the reference for every field.

## The gate

Tracking is controlled by two numbers: a minimum **time** and a minimum **distance** between stored locations. A reading from the OS (a fix) becomes a location only when both have passed.

```plaintext
(now - lastAdmittedTime    >= minTimeBetweenLocationsSeconds) AND
(distance(lastAdmittedFix) >= minDistanceBetweenLocationsMeters)
```

The first fix after `start()` always passes. Set either field to `0` to turn that side of the gate off. Beekon applies no other filtering: no Kalman filter, no outlier rejection, no speed clamp. Coordinates and accuracy are what the OS provider (`FusedLocationProviderClient` on Android, Core Location on iOS) reported.

Why AND, not OR?

With time alone, a device standing still stores a location every interval. With distance alone, a fast-moving device stores locations as often as the OS delivers them. Requiring both keeps the history dense enough to draw a route and small enough to query.

## TrackingConfig fields

`TrackingConfig` has six fields:

| Field                               | Type    | Default    | Notes                                                                                                                                                                                 |
| ----------------------------------- | ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minTimeBetweenLocationsSeconds`    | seconds | `30`       | Min seconds between kept locations. `0` disables the time gate.                                                                                                                       |
| `minDistanceBetweenLocationsMeters` | metres  | `100`      | Min metres between kept locations. `0` disables the distance gate; AND-ed with time.                                                                                                  |
| `accuracyMode`                      | enum    | `balanced` | Battery against accuracy. See [Enums](#enums).                                                                                                                                        |
| `whenStationary`                    | enum    | `pause`    | What to do while the device is still. See [Enums](#enums).                                                                                                                            |
| `stationaryRadiusMeters`            | metres  | `5`        | Radius of the internal stationary geofence. Clamped to `5…1000` on the device, even when [remote config](https://docs.getbeekon.com/api/remote-config/#tracking) sends more (the server accepts up to `10000`). |
| `detectActivity`                    | boolean | `false`    | Adds the detected activity (walking, driving and so on) to each location. Needs a second OS permission; see [Activity detection](https://docs.getbeekon.com/guide/activity/).                                   |

In code: seconds are `Long` on Android, `TimeInterval` on iOS, `int` in Flutter and `number` in React Native; metres are `Double`, `Double`, `double` and `number`; the booleans are `Boolean`, `Bool`, `bool` and `boolean`. `accuracyMode` is an `AccuracyMode` and `whenStationary` a `StationaryMode`.

## Enums

Casing follows the platform

The tables give each value in lower camel case. Android uses PascalCase (`AccuracyMode.High`), iOS a case (`.high`), Flutter an enum value (`AccuracyMode.high`) and React Native a string literal (`'high'`). The values mean the same on every platform.

**`AccuracyMode`**: battery against accuracy.

| Value                  | Behaviour                                                               |
| ---------------------- | ----------------------------------------------------------------------- |
| `high`                 | Most accurate fixes, highest battery cost.                              |
| `balanced` *(default)* | City-block accuracy at moderate cost.                                   |
| `low`                  | Coarse, low-power fixes; the distance gate is raised to at least 500 m. |

**`StationaryMode`**: behaviour while the device is still.

| Value               | Behaviour                                                                                                                                                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keepTracking`      | Keep recording locations even while stationary. Highest battery cost.                                                                                                                                                         |
| `pause` *(default)* | Stop recording locations while stationary; resume silently on movement.                                                                                                                                                       |
| `pauseWithCheckIns` | Stop while stationary, but record a check-in location roughly every 15 minutes. On iOS a check-in runs only when the system runs the [background refresh task](https://docs.getbeekon.com/start/setup/#ios-background-tasks), so it can be hours apart. |

## Mode-specific fields

These fields sit on `BeekonConfig` itself, not on `TrackingConfig`:

| Field          | Modes               | Default                | Notes                                                                                                                                                                                                                                            |
| -------------- | ------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tracking`     | `Custom`, `Local`   | all defaults           | The `TrackingConfig` above. In Cloud mode the server owns these values.                                                                                                                                                                          |
| `sync`         | `Custom` (required) | —                      | Where and how to upload. See [Turn on sync](https://docs.getbeekon.com/guide/sync/). Local never uploads; Cloud derives its own endpoints.                                                                                                                                 |
| `notification` | all modes           | `NotificationConfig()` | The foreground-service notification. Android only. See [NotificationConfig](#notificationconfig).                                                                                                                                                |
| `licenseKey`   | `Custom`, `Local`   | `null`                 | A signed licence token. See [Licensing](https://docs.getbeekon.com/reference/licensing/). In Cloud mode the server delivers the key for the app ids registered under **Organisation › SDK licence** in the console ([In Cloud mode](https://docs.getbeekon.com/reference/licensing/#in-cloud-mode)). |
| `logLevel`     | all modes           | `info`                 | The diagnostic log threshold. See [Diagnostics](https://docs.getbeekon.com/guide/diagnostics/).                                                                                                                                                                            |

## Cloud mode

A Cloud config is built by a factory that checks its input when you build it, so a bad key fails at `configure` rather than later on the network.

* The project key names its region: `bkproj_<cell>_<secret>`, where `<cell>` is the Beekon Cloud region of your project, such as `in1`. Without an `endpoint`, the SDK derives `https://api.<cell>.getbeekon.com` from the key. There is no network call and no fallback host.
* `endpoint` overrides the derived host; Beekon Cloud apps leave it unset. It must be `https` (plain `http` only to `localhost`, `127.0.0.1` or `::1`), with no query or fragment and no `v1` path segment.
* Rejections carry a reason: `key_empty` for an empty key; `key_missing_cell` for a key with no `<cell>` segment and no `endpoint`; and an endpoint reason for an endpoint that breaks the rules above.

- Android

  ```kotlin
  // BeekonConfig.cloud throws BeekonException.InvalidConfiguration
  // on a bad key/endpoint
  Beekon.configure(
    BeekonConfig.cloud(
      projectKey = "bkproj_in1_...",
      // endpoint = "https://beekon.example.com", // overrides the derived host
      notification = NotificationConfig(title = "Tracking location"),
    ),
  )
  ```

- iOS

  ```swift
  // BeekonConfig.cloud throws BeekonError.invalidConfiguration(reason:)
  // on a bad key/endpoint
  try await Beekon.shared.configure(
    BeekonConfig.cloud(
      projectKey: "bkproj_in1_..."
      // endpoint: "https://beekon.example.com"  (overrides the derived host)
    )
  )
  ```

- Flutter

  ```dart
  // configure throws InvalidConfiguration on a bad key/endpoint
  await Beekon.instance.configure(
    const BeekonConfig.cloud(
      projectKey: 'bkproj_in1_...',
      // endpoint: 'https://beekon.example.com', // overrides the derived host
      notification: NotificationConfig(title: 'Tracking location'), // Android only
    ),
  );
  ```

- React Native

  ```ts
  // configure rejects with a BeekonError of kind 'invalidConfiguration'
  // on a bad key/endpoint
  await Beekon.configure({
    mode: 'cloud',
    projectKey: 'bkproj_in1_...',
    // endpoint: 'https://beekon.example.com', // overrides the derived host
    notification: { title: 'Tracking location' }, // Android only
  });
  ```

In React Native, `BeekonConfig.cloud(...)`, `BeekonConfig.custom(...)` and `BeekonConfig.local(...)` are optional helpers that fill in `mode`. Their result, like a literal `mode: 'cloud'` object, goes through the same native validation.

In Cloud mode the tracking values come from the server as a **remote config document** with the sections `tracking`, `sync`, `privacy`, `features` and `diagnostics`. The SDK caches it on the device and applies it as a whole: a fresh document wins over the cached one, which wins over the built-in defaults. Tracking never waits for configuration. A device that can’t reach the server runs its last good config, or the defaults if it has never connected.

Before it applies a remote value, the SDK clamps it to its own limits: floors and ceilings built into the SDK. No server value, including one from a compromised server, can push the device outside those ranges, redirect uploads or change how the device authenticates. [Remote config](https://docs.getbeekon.com/api/remote-config/) lists every value and the range the server accepts; the device may clamp further, as it does for `stationaryRadiusMeters`.

## NotificationConfig

Android shows a notification while an app captures location in the background. Set its content with `BeekonConfig.notification`; iOS ignores it. This is the notification of the tracking service, shown for as long as it runs. [Geofence notifications](https://docs.getbeekon.com/guide/geofencing/#per-geofence-notifications) are separate: they appear on enter or exit, on every platform.

| Field       | Type   | Default               | Notes                                                                                                   |
| ----------- | ------ | --------------------- | ------------------------------------------------------------------------------------------------------- |
| `title`     | string | `"Tracking location"` | Notification title.                                                                                     |
| `text`      | string | `null`                | Notification body. `null` shows the title only.                                                         |
| `smallIcon` | string | `null`                | The status-bar icon: the name of an Android drawable or mipmap resource. `null` uses the launcher icon. |

Use a monochrome icon

Android draws the status-bar icon from its alpha channel only, so a full-colour launcher icon shows as a white shape. Supply a monochrome silhouette on a transparent background. `smallIcon` takes a bare name (`"ic_stat_tracking"`, looked up in `drawable`, then `mipmap`) or a typed path (`"drawable/ic_stat_tracking"`).

## Live tuning

Call `configure(...)` again at any time, including while tracking. What happens next depends on the OS:

* **Android** (also Flutter and React Native on Android): `configure` restarts the location subscription with the new config, so every field applies at once, `accuracyMode` included.
* **iOS** (also Flutter and React Native on iOS): the gate thresholds, `whenStationary`, `stationaryRadiusMeters`, `detectActivity` and `sync` apply to the next location, without restarting the location subscription. `accuracyMode` is fixed for a session: the OS location request keeps the accuracy it started with, and a changed value applies on the next `start()`.

The examples below change only the gate.

* Android

  ```kotlin
  // Store locations more often, mid-session
  Beekon.configure(
    BeekonConfig.Local(
      tracking = TrackingConfig(
        minTimeBetweenLocationsSeconds = 5,
        minDistanceBetweenLocationsMeters = 25.0,
        accuracyMode = AccuracyMode.Balanced,
        whenStationary = StationaryMode.Pause,
      ),
      notification = NotificationConfig(title = "Tracking location"),
    ),
  )
  ```

* iOS

  ```swift
  try await Beekon.shared.configure(
    BeekonConfig.local(
      tracking: TrackingConfig(
        minTimeBetweenLocationsSeconds: 5,
        minDistanceBetweenLocationsMeters: 25,
        accuracyMode: .balanced,
        whenStationary: .pause
      )
    )
  )
  ```

* Flutter

  ```dart
  await Beekon.instance.configure(
    BeekonConfig.local(
      tracking: const TrackingConfig(
        minTimeBetweenLocationsSeconds: 5,
        minDistanceBetweenLocationsMeters: 25,
        accuracyMode: AccuracyMode.balanced,
        whenStationary: StationaryMode.pause,
      ),
    ),
  );
  ```

* React Native

  ```ts
  await Beekon.configure({
    mode: 'local',
    tracking: {
      minTimeBetweenLocationsSeconds: 5,
      minDistanceBetweenLocationsMeters: 25,
      accuracyMode: 'balanced',
      whenStationary: 'pause',
    },
  });
  ```

## Picking values

The defaults (30 s, 100 m, balanced, pause) suit general tracking. Starting points for other uses, with time as `minTimeBetweenLocationsSeconds` and distance as `minDistanceBetweenLocationsMeters`:

| Scenario                                  | Time (s) | Distance (m) | `accuracyMode` | Notes                                                                                 |
| ----------------------------------------- | -------- | ------------ | -------------- | ------------------------------------------------------------------------------------- |
| Passive background (“where did I go?”)    | `60`     | `500`        | `low`          | A coarse trail at low battery cost. `low` raises the distance gate to at least 500 m. |
| General tracking *(default)*              | `30`     | `100`        | `balanced`     | Driving, cycling, long walks.                                                         |
| Active foreground (turn-by-turn, fitness) | `5`–`10` | `25`–`50`    | `high`         | High battery use in the background.                                                   |
| Stationary monitoring (geofence-like)     | `0`      | `100`        | `balanced`     | Stores a location on movement only, not on a timer.                                   |

Check them against your own data.
