ActivityConfig¶

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

let bgGeo = BGGeo.shared
bgGeo.ready { config in
    // Android: poll activity recognition every 10s
    config.activity.activityRecognitionInterval = 10000.0

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

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

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

    // motionTriggerDelay — Android only — not applicable on iOS

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

    // iOS: delay stop-detection by 10s
    config.activity.stopDetectionDelay = 10000
}

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

let bgGeo = BGGeo.shared
bgGeo.ready { config in
    config.activity.activityRecognitionInterval = 10000.0
    config.activity.disableStopDetection = true
    config.activity.stopOnStationary = true
}

let bgGeo = BGGeo.shared
bgGeo.ready { config in
    config.activity.activityRecognitionInterval = 10000.0
    config.activity.disableStopDetection = true
    config.activity.stopOnStationary = true
}

Members¶

activityRecognitionInterval¶

public var activityRecognitionInterval: TimeInterval

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¶

public var disableMotionActivityUpdates: Bool

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.

let bgGeo = BGGeo.shared
bgGeo.ready { config in
    config.activity.disableMotionActivityUpdates = true
}

disableStopDetection¶

public var disableStopDetection: Bool

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.

let bgGeo = BGGeo.shared
bgGeo.ready { config in
    config.activity.disableStopDetection = true
    config.geolocation.pausesLocationUpdatesAutomatically = false
}

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¶

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

stopDetectionDelay¶

public var stopDetectionDelay: TimeInterval

iOS only Delays the iOS stop-detection system from engaging after the device becomes stationary. Defaults to 0 (engage immediately). When the stop-detection system engages, location services are temporarily turned off and only the accelerometer is monitored. The delay timer starts when the device is detected as stationary and is cancelled if any movement is detected before it expires. Setting stopDetectionDelay to a non-zero value helps avoid false stops at traffic lights or brief pauses.

Enable LoggerConfig.debug to observe stop-detection in action — the SDK emits a sound effect and local notifications when location services toggle on and off.

stopOnStationary¶

public var stopOnStationary: Bool

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.

let bgGeo = BGGeo.shared
bgGeo.ready { config in
    config.activity.stopOnStationary = true
}
Task {
    do {
        try await bgGeo.start()
    } catch {
        print("Error: \(error)")
    }
}

triggerActivities¶

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

let bgGeo = BGGeo.shared
// Only trigger tracking for vehicles
bgGeo.ready { config in
    config.activity.triggerActivities = "in_vehicle"
}

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