Config¶

classConfig

Root configuration object passed to BGGeo.ready and BGGeo.setConfig.

Config groups all SDK options into typed sub-interfaces. Each key maps to a dedicated configuration area — set only the keys relevant to your use case.

Contents¶

Overview
Examples

Overview¶

Key	Type	Description
`geolocation`	GeolocationConfig	Accuracy, sampling, elasticity, stop-detection, permissions, and geofencing.
`activity`	ActivityConfig	Motion recognition, stop-detection triggers, and motion-trigger delay.
`http`	HttpConfig	Upload URL, sync cadence, batching, headers, and params.
`persistence`	PersistenceConfig	SQLite storage, TTL, record limits, and custom extras.
`app`	AppConfig	App lifecycle — background operation, boot behaviour, headless mode, and foreground notification.
`logger`	LoggerConfig	Debug logging, log level, and log retention.
`authorization`	AuthorizationConfig	JWT and SAS token management with automatic refresh.

The SDK persists its configuration across app launches. Call BGGeo.ready once at startup — subsequent launches load the persisted config automatically. Use BGGeo.setConfig to update individual keys at runtime without restarting.

Examples¶

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.ready {
    geolocation.desiredAccuracy = DesiredAccuracy.HIGH
    geolocation.distanceFilter = 20f
    geolocation.stopTimeout = 5
    geolocation.stationaryRadius = 150

    activity.disableStopDetection = false
    activity.motionTriggerDelay = 30000

    http.url = "https://my.server.com/api/locations"
    http.method = HttpMethod.POST
    http.autoSync = true
    http.headers = mapOf("Authorization" to "Bearer secret-token")
    http.params = mapOf("user_id" to 123)

    persistence.persistMode = PersistMode.ALL
    persistence.maxDaysToPersist = 14
    persistence.extras = mapOf("appVersion" to "1.0.0")

    app.stopOnTerminate = false
    app.startOnBoot = true
    app.enableHeadless = true

    logger.debug = true
    logger.logLevel = LogLevel.VERBOSE
    logger.logMaxDays = 3
}

Log.d(TAG, "[ready] BackgroundGeolocation is configured and ready to use")

if (!bgGeo.enabled) {
    bgGeo.start()
}

// To modify configuration after initialization, use config.edit.
bgGeo.config.edit {
    http.headers = mapOf("Authorization" to "Bearer new-token")
    logger.logLevel = LogLevel.INFO
}

bgGeo.store.sync()

Minimal configuration¶

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.ready {
    geolocation.desiredAccuracy = DesiredAccuracy.HIGH
    geolocation.distanceFilter = 20f
    http.url = "https://my.server.com/api/locations"
    http.autoSync = true
    app.stopOnTerminate = false
    app.startOnBoot = true
}

Full configuration¶

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.ready {
    geolocation.desiredAccuracy = DesiredAccuracy.HIGH
    geolocation.distanceFilter = 20f
    geolocation.stopTimeout = 5
    geolocation.stationaryRadius = 150

    activity.disableStopDetection = false
    activity.motionTriggerDelay = 30000

    http.url = "https://my.server.com/api/locations"
    http.method = HttpMethod.POST
    http.autoSync = true
    http.headers = mapOf("Authorization" to "Bearer secret-token")
    http.params = mapOf("user_id" to 123)

    persistence.persistMode = PersistMode.ALL
    persistence.maxDaysToPersist = 14
    persistence.extras = mapOf("appVersion" to "1.0.0")

    app.stopOnTerminate = false
    app.startOnBoot = true
    app.enableHeadless = true

    logger.debug = true
    logger.logLevel = LogLevel.VERBOSE
    logger.logMaxDays = 3
}

if (!bgGeo.enabled) {
    bgGeo.start()
}

// Update a subset of config at runtime.
bgGeo.config.edit {
    http.headers = mapOf("Authorization" to "Bearer new-token")
    logger.logLevel = LogLevel.INFO
}

Members¶

activity¶

val activity

Motion recognition, stop-detection triggers, and motion-trigger delay. Access via BGGeo.instance.config.activity. See ActivityConfig.

app¶

val app

App lifecycle, background operation, boot behaviour, headless mode, and foreground notification. Access via BGGeo.instance.app. See AppConfig.

authorization¶

val authorization

JWT and SAS token management with automatic refresh. Access via BGGeo.instance.authorization. See AuthorizationConfig.

geolocation¶

val geolocation

Accuracy, sampling, elasticity, stop-detection, permissions, and geofencing. Access via BGGeo.instance.config.geolocation. See GeolocationConfig.

http¶

val http

Upload URL, HTTP method, sync cadence, batching, headers, and params. Access via BGGeo.instance.config.http. See HttpConfig.

logger¶

val logger

Debug logging, log level, and log retention. Access via BGGeo.instance.config.logger. See LoggerConfig.

persistence¶

val persistence

SQLite storage, TTL, record limits, and custom extras. Access via BGGeo.instance.config.persistence. See PersistenceConfig.

reset¶

fun reset()

Controls whether the SDK resets to factory defaults before applying this configuration. Defaults to true.

When true (the default), every call to BGGeo.ready applies the supplied Config on top of fresh defaults. When false, the SDK applies the supplied Config only on the first install. On subsequent launches it ignores the Config argument entirely — the only way to change settings is via BGGeo.setConfig.

Warning

During development, always leave reset: true (or omit it). Setting reset: false causes the SDK to ignore your Config after the first launch, so configuration changes made between development builds will not take effect.