Skip to content

Permissions

The manifest entries and Info.plist keys are on Platform setup. This page covers asking for the permissions at runtime.

PermissionImportanceWhat it powersWithout it
locationRequiredAll tracking. Any foreground grant satisfies it.start() ends in Stopped(PermissionDenied).
backgroundLocationRecommendedResuming tracking without your app on screen: after a stationary pause, after the OS stops the app, and (Android) after a reboot. Geofences. Android “Allow all the time”, iOS Always.Tracking started in the foreground still runs in the background, but doesn’t come back once the OS stops it, and geofences don’t fire. Details below.
activityRecognitionRequired when detectActivity is on; otherwise recommended or absent, depending on the configMotion-based stationary detection, its battery savings, and Location.activity.Motion detection is off and activity is null.
notificationsRecommended, Android 13 and laterThe foreground-service notification and per-geofence notifications.The service runs, but its notification is hidden; geofence notifications don’t show.

requestNextNeededPermission() asks only for required permissions. Ask for the recommended ones yourself with requestPermission(...), in particular backgroundLocation: the SDK quickstart shows both steps.

Tracking you start while the app is in the foreground keeps running in the background. Without the background grant:

  • it doesn’t resume once the OS stops the app, on either platform;
  • on Android, it doesn’t resume after a stationary pause;
  • on iOS, Beekon skips the stationary pause instead, so tracking runs at full power while the device is still;
  • geofences don’t fire.

getRequiredPermissions() returns the permissions the current config needs, each tagged required or recommended and marked as satisfied or not by the live OS grant. It is read-only and never prompts.

Call it after configure(...). Before that, and in Cloud mode (where the server owns the config and the SDK doesn’t know it before start()), it returns a conservative list. Each entry is a PermissionRequirement:

FieldTypeMeaning
permissionenumlocation, backgroundLocation, activityRecognition or notifications: Beekon’s names, not the raw OS constants.
importanceenumrequired: tracking can’t start, or a feature you turned on doesn’t work, without it. recommended: a feature degrades and tracking continues.
satisfiedboolWhether the live OS grant already covers it.
rationalestringA sentence on why it’s needed and what degrades without it. In SDK 0.5.0 the backgroundLocation sentence wrongly says tracking is foreground-only without it; SDK 0.6.0 corrects it to match the table above.

location and backgroundLocation are always listed. activityRecognition is listed when the config can use motion detection. notifications is listed on Android 13 and later, always. The iOS doctor never lists notifications, but per-geofence notifications on iOS still need notification authorisation: ask with requestPermission(.notifications).

On Android, satisfied is the runtime grant. iOS has no runtime motion-permission query, so there activityRecognition is satisfied when NSMotionUsageDescription is in the Info.plist and the device has a motion coprocessor.

// Synchronous; call after configure().
Beekon.getRequiredPermissions().forEach { r ->
Log.d(
"beekon",
"${r.permission} (${r.importance}) satisfied=${r.satisfied}: ${r.rationale}",
)
}
// r.permission: BeekonPermission.Location / .BackgroundLocation /
// .ActivityRecognition / .Notifications
// r.importance: PermissionImportance.Required / .Recommended

Beekon never prompts on its own: nothing in configure(...), start() or initialisation shows a dialog, and no call chains one prompt into the next. Each prompt is one your code triggers, after your own explanation. The request API performs the OS ask correctly on each platform. Permission libraries (permission_handler, react-native-permissions and others) work too; drive them from getRequiredPermissions().

MethodWhat it does
requestPermission(permission)Asks for one permission and returns a PermissionRequestResult. Never fires a prompt the OS would drop silently.
requestNextNeededPermission()Asks for the first unsatisfied required permission in the doctor’s order and returns its result, or null (nil on iOS) when no required permission is missing. Recommended permissions are skipped.
openSettings(permission)Opens the closest OS settings screen. The only way forward once an outcome is requiresSettings.

Render the doctor list to show what’s needed and why. On each onboarding screen, call requestNextNeededPermission() from a button. When it returns null, ask for backgroundLocation (and any other recommended permission you want) with requestPermission(...), then call start().

// suspend; needs a foreground Activity.
when (val r = Beekon.requestNextNeededPermission(activity)) {
null -> {
// No required permission missing. Ask for background location on its own
// screen.
Beekon.requestPermission(activity, BeekonPermission.BackgroundLocation)
Beekon.start()
}
else -> when (r.outcome) {
PermissionRequestOutcome.RequiresSettings ->
Beekon.openSettings(activity, BeekonPermission.Location)
else -> { /* show your explanation again; ask on the next tap */ }
}
}
// A result also carries r.prerequisite (when Blocked), r.reason
// (when NotAttempted) and r.status.

Every request returns a PermissionRequestResult with four fields: outcome; prerequisite, the permission to ask for first (set only when outcome is blocked); reason (set only when outcome is notAttempted); and status, a fresh PermissionStatus.

outcomeMeaning
grantedThe grant now covers the request. Includes iOS provisional Always and one-time grants; neither OS says whether a grant will last.
deniedThe prompt ran and the grant is still missing. The OS may allow another prompt later.
requiresSettingsThe OS will not prompt again. openSettings(...) is the only way forward.
alreadySatisfiedNothing to do; the grant already covered it.
blockedA precondition failed; prerequisite names the permission to ask for first (for example foreground location before background).
notAttemptedThe SDK did not fire a prompt that could not succeed. reason is missing_manifest_entry, missing_plist_key, unsupported or not_foreground.

PermissionRequestOutcome may gain values in a minor release, so give every switch an else or default branch.

  • Requests need a foreground Activity. Without one the result is notAttempted with reason not_foreground.
  • The permission must be in the merged manifest, or the result is notAttempted with missing_manifest_entry. ACCESS_BACKGROUND_LOCATION is not in Beekon’s manifest; add it yourself (Platform setup).
  • A location request asks for FINE and COARSE together.
  • Background comes after foreground. Asking for background location while foreground location is missing returns blocked with prerequisite = location, because Android 11 and later deny a combined request without showing anything.
  • notifications can be requested only on Android 13 (API 33) and later, with a target SDK of 33 or higher; otherwise the result is notAttempted with unsupported.