Authorization¶

classAuthorization

Location permission management — request and monitor authorisation status.

Access via BGGeo.instance.authorization.

Members¶

getState¶

fun getState():ProviderChangeEvent

Retrieve the current location-services authorization state.

See also - onProviderChange to subscribe to future authorization changes.

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

val providerState = bgGeo.authorization.getState()
Log.d(TAG, "- Provider state: $providerState")

requestPermission¶

suspend fun requestPermission():PermissionStatussuspend fun requestPermission(permission:Permission):PermissionStatus

Requests location and motion permission — together, or each one separately.

With no argument, requests everything the current configuration requires: location per GeolocationConfig.locationAuthorizationRequest, then the motion permission — the same set start requests. Pass a Permission to request one permission at a time and control exactly when each system dialog appears:

Argument	Requests	Resolves with
(none)	Location per configuration, then motion	The location PermissionStatus; the motion outcome stays silent
`Permission.Location`	Location only — motion untouched	The location PermissionStatus
`Permission.Motion`	Motion only	PermissionStatus.Always when granted

The location forms resolve when either WhenInUse or Always is granted, regardless of the configured level, and resolve immediately when permission is already granted. Denial rejects with the bare PermissionStatus value.

The no-argument form skips the motion step when ActivityConfig.disableMotionActivityUpdates is true — and, on iOS, when NSMotionUsageDescription is absent from Info.plist (requesting motion without it would terminate the app).

Each call is independently awaitable: the returned promise settles only when its own request fully resolves, and the SDK serializes permission requests internally — await one call, then issue the next, and each dialog appears in order, never stacked.

Android¶

A motion denial rejects with PermissionStatus.Denied while a new request can still show the system dialog, and with PermissionStatus.DeniedAlways once Android permanently denies the permission (two user denials) — after that, only the device's app-settings screen can restore it.

iOS¶

The motion permission is one-shot — iOS never re-prompts. A user denial rejects with PermissionStatus.DeniedAlways: the state is permanent and only the Settings app can restore it (the motion form never rejects with plain PermissionStatus.Denied). The rejection can also carry PermissionStatus.Restricted (system-wide Fitness Tracking is off or the hardware is absent — not recoverable from the app's own Settings page) or PermissionStatus.NotDetermined (no dialog could be shown, e.g. the app was backgrounded). If the location dialog has already been shown and the current grant does not match the configured request, the SDK presents an alert offering to direct the user to the app's Settings page.

Note¶

The SDK automatically requests every required permission when you call start, startGeofences, or getCurrentPosition. Calling this method first resolves the dialogs ahead of time, so those methods find everything granted and show nothing.

Request each permission separately¶

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

val locationStatus = bgGeo.authorization.requestPermission(Permission.LOCATION)
Log.d(TAG, "[requestPermission] location: $locationStatus")

val motionStatus = bgGeo.authorization.requestPermission(Permission.MOTION)
if (motionStatus == PermissionStatus.DENIED_ALWAYS) {
    // Only the app-settings screen can restore the motion permission now.
}

Request everything at once¶

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

val status = bgGeo.authorization.requestPermission()
Log.d(TAG, "[requestPermission] status: $status")

requestTemporaryFullAccuracy¶

suspend fun requestTemporaryFullAccuracy(purpose: String):AccuracyAuthorization

Request temporary full-accuracy location authorization. [iOS 14+]

iOS 14 allows users to grant only reduced location accuracy. This method presents the system dialog (requestTemporaryFullAccuracyAuthorization) requesting full accuracy for the lifetime of the current app session.

Configuration — Info.plist¶

Add the Privacy - Location Temporary Usage Description Dictionary key to your Info.plist:

The dictionary keys (e.g. Delivery) are passed as purposeKey. The corresponding value is the message shown to the user explaining the purpose of your request.

The dialog fails to present if: - The Info.plist entry for purposeKey is missing. - The app is already authorized for full accuracy. - The app is in the background.

Note

On Android and iOS versions below 14, this method returns AccuracyAuthorization.Full immediately without presenting a dialog.

val bgGeo = BGGeo.instance

bgGeo.onProviderChange { event ->
    if (AccuracyAuthorization.fromValue(event.accuracyAuthorization) == AccuracyAuthorization.REDUCED) {
        try {
            val accuracyAuthorization = kotlinx.coroutines.runBlocking {
                bgGeo.authorization.requestTemporaryFullAccuracy("Delivery")
            }
            if (accuracyAuthorization == AccuracyAuthorization.FULL) {
                Log.d(TAG, "[requestTemporaryFullAccuracy] GRANTED: $accuracyAuthorization")
            } else {
                Log.d(TAG, "[requestTemporaryFullAccuracy] DENIED: $accuracyAuthorization")
            }
        } catch (e: Exception) {
            Log.w(TAG, "[requestTemporaryFullAccuracy] FAILED TO SHOW DIALOG: $e")
        }
    }
}