ActivityConfig¶

classActivityConfig

Activity recognition configuration for the background geolocation SDK.

ActivityConfig controls how the SDK interprets transitions between moving and stationary states using platform motion APIs (Android Activity Recognition and iOS Core Motion).

Contents¶

Overview
Stop detection
Motion trigger

Overview¶

Category	Properties	Notes
Recognition cadence	`activityRecognitionInterval`, `minimumActivityRecognitionConfidence`	How often and how confidently the SDK polls platform motion APIs.
Stop detection	`disableStopDetection`, `stopOnStationary`, `stopDetectionDelay`	Controls when the SDK transitions to stationary and stops tracking. `stopDetectionDelay` is iOS only.
Motion trigger	`motionTriggerDelay`, `triggerActivities`	Controls which activities start tracking and how quickly. `motionTriggerDelay` is Android only.
Permission	`disableMotionActivityUpdates`	Opt out of Motion & Fitness / Physical Activity permission requests.

import com.transistorsoft.locationmanager.kotlin.BGGeo

// Within a coroutine scope
val bgGeo = BGGeo.instance
bgGeo.ready {
    // Android: poll activity recognition every 10s
    activity.activityRecognitionInterval = 10000.0

    // Android: require >=75% confidence before changing activity
    activity.minimumActivityRecognitionConfidence = 75

    // Cross-platform: enable/disable automatic stop detection
    activity.disableStopDetection = false

    // Cross-platform: automatically stop when stationary
    activity.stopOnStationary = true

    // Android: delay motion-trigger transitions by 30s
    activity.motionTriggerDelay = 30000

    // Android & iOS: disable platform motion activity APIs
    activity.disableMotionActivityUpdates = false

    // iOS: delay stop-detection by 10s
    // stopDetectionDelay — iOS only — not applicable on Android
}

Stop detection¶

The SDK uses platform motion APIs to detect when the device has stopped moving and transitions to the stationary state. In that state, location services are paused to conserve battery.

ActivityConfig.disableStopDetection disables this mechanism entirely. With it off, location services run continuously.
ActivityConfig.stopOnStationary takes it a step further — the SDK calls stop() on itself when the GeolocationConfig.stopTimeout elapses, ending all tracking.
ActivityConfig.stopDetectionDelay (iOS only) adds a grace period before the stop-detection system engages, preventing false stops at traffic lights or brief pauses.

Motion trigger¶

When in the stationary state, the SDK waits for a motion event before re-engaging location tracking:

ActivityConfig.triggerActivities limits which activity types can trigger the transition to moving. By default all moving activities trigger.
ActivityConfig.motionTriggerDelay (Android only) adds a delay before committing to the moving state. If the device returns to still before the delay expires, the transition is cancelled.

See also - Config.activity

// Within a coroutine scope
val bgGeo = BGGeo.instance
bgGeo.ready {
    activity.activityRecognitionInterval = 10000.0
    activity.disableStopDetection = true
    activity.stopOnStationary = true
}

// Within a coroutine scope
val bgGeo = BGGeo.instance
bgGeo.ready {
    activity.activityRecognitionInterval = 10000.0
    activity.disableStopDetection = true
    activity.stopOnStationary = true
}

Members¶

activityRecognitionInterval¶

var activityRecognitionInterval: Double

Interval in milliseconds between motion-activity polls. Defaults to 10000 ms (10 seconds).

Lower values increase responsiveness to state changes at the cost of additional battery use. The minimum supported value is 500 ms.

disableMotionActivityUpdates¶

var disableMotionActivityUpdates: Boolean

Disables the SDK's request for Motion & Fitness (iOS) or Physical Activity (Android 10+) permission. Defaults to false.

Set to true to suppress the permission request. The SDK remains functional but without motion data it relies on less efficient fallback mechanisms to detect moving/stationary transitions.

iOS¶

The SDK is highly optimized around motion-activity updates. Disabling them increases battery consumption. Provide an NSMotionUsageDescription in your Info.plist to explain the benefit to users — for example:

"Motion activity detection increases battery efficiency by intelligently toggling location tracking off when your device is stationary."

Android¶

Android 10+ requires runtime permission for Physical Activity. Without it, the SDK falls back to a stationary geofence mechanism — the device must move 200–500 m before tracking re-engages, compared to just a few meters when the Motion API is authorized.

// Within a coroutine scope
val bgGeo = BGGeo.instance
bgGeo.ready {
    activity.disableMotionActivityUpdates = true
}

disableStopDetection¶

var disableStopDetection: Boolean

Disables the motion-activity-based stop-detection system. Defaults to false.

iOS¶

Disables the accelerometer-based stop-detection system. When disabled, the SDK falls back to the default iOS behaviour of automatically turning off location services after the device has been stationary for exactly 15 minutes. GeolocationConfig.stopTimeout has no effect in this state.

To prevent iOS from ever turning off location services automatically, also set GeolocationConfig.pausesLocationUpdatesAutomatically to false.

// Within a coroutine scope
val bgGeo = BGGeo.instance
bgGeo.ready {
    activity.disableStopDetection = true
    // pausesLocationUpdatesAutomatically — iOS only — not applicable on Android
}

Warning

With the above configuration, iOS location services will never turn off and the battery will drain rapidly. Use this only when you have explicit start/stop controls in your app (for example, a workout app with Start / Stop buttons calling BGGeo.changePace).

Android¶

Location services will never turn off while disableStopDetection is true. The only way to stop tracking is to call BGGeo.changePace false or BGGeo.stop explicitly.

minimumActivityRecognitionConfidence¶

var minimumActivityRecognitionConfidence: Int

Minimum confidence level (0–100) required before a detected activity triggers a moving/stationary state change.

Defaults to 70 on iOS and 75 on Android. Higher values reduce false-positive transitions but may cause the SDK to react more slowly to genuine activity changes.

motionTriggerDelay¶

var motionTriggerDelay: Int

Android only Adds a delay in milliseconds before the SDK commits to the moving state when the Motion API reports movement. Defaults to 0 (no delay).

When the Motion API reports a moving activity (e.g. on_foot, in_vehicle), the SDK waits motionTriggerDelay milliseconds before transitioning to moving and starting location tracking. If the Motion API returns to still before the delay expires, the transition is cancelled. This prevents false-positive triggers when briefly moving around a stationary location (for example, walking around a home).

The following log shows a device detecting on_foot but returning to still before the delay expires, cancelling the transition:

 04-08 10:58:03.419 TSLocationManager: ╔═════════════════════════════════════════════
 04-08 10:58:03.419 TSLocationManager: ║ Motion Transition Result
 04-08 10:58:03.419 TSLocationManager: ╠═════════════════════════════════════════════
 04-08 10:58:03.419 TSLocationManager: ╟─ 🔴  EXIT: still
 04-08 10:58:03.419 TSLocationManager: ╟─ 🎾  ENTER: on_foot
 04-08 10:58:03.419 TSLocationManager: ╚═════════════════════════════════════════════
 04-08 10:58:03.416 TSLocationManager:   ⏰ Scheduled OneShot: MOTION_TRIGGER_DELAY in 30000ms
 .
 . <motionTriggerDelay timer started>
 .
 04-08 10:58:19.385 TSLocationManager: ╔═════════════════════════════════════════════
 04-08 10:58:19.385 TSLocationManager: ║ Motion Transition Result
 04-08 10:58:19.385 TSLocationManager: ╠═════════════════════════════════════════════
 04-08 10:58:19.385 TSLocationManager: ╟─ 🔴  EXIT: on_foot
 04-08 10:58:19.385 TSLocationManager: ╟─ 🎾  ENTER: still
 04-08 10:58:19.385 TSLocationManager: ╚═════════════════════════════════════════════
 04-08 10:58:19.381 TSLocationManager: [c.t.l.s.TSScheduleManager cancelOneShot]
 04-08 10:58:19.381 TSLocationManager:   ⏰ Cancel OneShot: MOTION_TRIGGER_DELAY <-- timer cancelled

// Delay Android motion-triggering by 30000ms
// Within a coroutine scope
val bgGeo = BGGeo.instance
bgGeo.ready {
    activity.motionTriggerDelay = 30000
}

stopOnStationary¶

var stopOnStationary: Boolean

Automatically calls BGGeo.stop when the GeolocationConfig.stopTimeout elapses. Defaults to false.

When the SDK transitions to the stationary state and the stopTimeout timer expires, the SDK calls stop() on itself — ending all tracking. The next tracking session must be started manually.

Warning

stopOnStationary fires only when the GeolocationConfig.stopTimeout timer elapses naturally. It does not fire when BGGeo.changePace false is called manually.

// Within a coroutine scope
val bgGeo = BGGeo.instance
bgGeo.ready {
    activity.stopOnStationary = true
}
bgGeo.start()

triggerActivities¶

var triggerActivities: String

Restricts which detected activities can trigger a transition from the stationary state to the moving state.

By default the SDK triggers on any moving activity: in_vehicle, on_bicycle, on_foot, running, or walking. Configure this to limit tracking to specific use cases — for example, vehicles only.

See TriggerActivity for all valid activity names.

Warning

Using triggerActivities requires the user to grant the Motion & Fitness (iOS) or Physical Activity (Android 10+) permission.

val bgGeo = BGGeo.instance
// Only trigger tracking for vehicles
// Within a coroutine scope
bgGeo.ready {
    activity.triggerActivities = "in_vehicle"
}

// Only trigger tracking for on_foot, walking and running
bgGeo.ready {
    activity.triggerActivities = "on_foot, walking, running"
}