# Activity detection

> Turn on detectActivity to label each location with the device's physical activity. The six values, the extra OS permission, and examples per platform.

Source: https://docs.getbeekon.com/guide/activity/

Activity detection fills the `activity` field of each location. For the rest of the `Location` type, see [Locations & history](https://docs.getbeekon.com/guide/locations/).

By default, `activity` is `null`. Set `detectActivity = true` in your config and Beekon labels each location with the device’s physical activity. It is off by default because it costs battery and needs a second OS permission.

When on, `activity` carries one of six values: `Stationary`, `Walking`, `Running`, `Cycling`, `Automotive`, `Unknown`. It stays `null` whenever detection can’t run: it is off, the permission isn’t granted, or (on Android) the device has no Google Mobile Services.

detectActivity needs a second permission

Activity detection needs its own permission. Beekon never prompts by itself: your app asks when it chooses, with [`requestPermission(activityRecognition)`](https://docs.getbeekon.com/start/permissions/#requesting-permissions) or its own code. Each platform needs:

* Android: `com.google.android.gms.permission.ACTIVITY_RECOGNITION` (on API 29+, `android.permission.ACTIVITY_RECOGNITION`) and a device with Google Mobile Services.
* iOS: the `NSMotionUsageDescription` key in Info.plist. Core Motion crashes an app that uses it without the key, so the SDK checks for the key first. Without it, Beekon skips activity detection and `activity` stays `null`. A denied grant also leaves it `null`.

To know what to request, call [`getRequiredPermissions()`](https://docs.getbeekon.com/start/permissions/#the-permission-doctor) after `configure()`. It returns the permissions the active config needs, activity recognition included, each marked `satisfied`. `start()` also logs a `warn` for each one that is missing. The [permission doctor](https://docs.getbeekon.com/start/permissions/#the-permission-doctor) section has the full `PermissionRequirement` shape.

* Android

  ```kotlin
  Beekon.configure(
    BeekonConfig.Local(tracking = TrackingConfig(detectActivity = true))
  )


  Beekon.locations.collect { loc ->
    Log.d("beekon", "moving as ${loc.activity ?: "—"}")
  }
  ```

* iOS

  ```swift
  try await Beekon.shared.configure(
    BeekonConfig.local(tracking: TrackingConfig(detectActivity: true))
  )


  for await loc in await Beekon.shared.locations {
    print("moving as \(loc.activity.map { "\($0)" } ?? "—")")
  }
  ```

* Flutter

  ```dart
  await Beekon.instance.configure(
    BeekonConfig.local(tracking: const TrackingConfig(detectActivity: true)),
  );


  Beekon.instance.locations.listen((loc) {
    print('moving as ${loc.activity ?? "—"}');
  });
  ```

* React Native

  ```ts
  await Beekon.configure({ mode: 'local', tracking: { detectActivity: true } });


  Beekon.onLocation((loc) => console.log('moving as', loc.activity ?? '—'));
  ```

`activity` is also sent in the [upload payload](https://docs.getbeekon.com/guide/payload/#the-upload-payload), on each `locations[]` entry. It is left out when detection is off.
