App Permissions

Learn how to request the permissions the Sentiance SDK needs at runtime, and what happens to detections when one is missing.

The Sentiance SDK requires a set of permissions to function and perform detections correctly. Some permissions are mandatory, while others are optional or automatically granted by the system.

Declaring a permission is not the same as holding it. The SDK does not request permissions on your behalf, so your app must ask the user for them at runtime. For the manifest and Info.plist declarations, and for the full list of permissions, check out the requirements page for Android and iOS.

---

Overview

Permission	Platform	Required	Without it
Background location "Always" on iOS, "Allow all the time" on Android	iOS, Android	Mandatory	Detections will not run. The detection status stays "enabled but blocked".
Precise location	iOS, Android	Mandatory	Detections will not run. Approximate location is not sufficient.
Motion & Fitness / Activity Recognition	iOS, Android	Optional	Detections run, with reduced quality.
Notifications	Android 13+	Optional	Detections run, but the foreground service notification is not shown.

---

Requesting Location Access

Both platforms grant background location in two stages. Your app must request foreground access first, and only then request background access.

On Android, requesting both at once does not work

If you request background location together with foreground location, Android silently drops the background part. The dialog appears, the user accepts, and your app is left with foreground access only, with no error to indicate it. Detections will not run.

iOS

Call requestWhenInUseAuthorization() first, and call requestAlwaysAuthorization() only once the "When In Use" authorization has been granted. iOS then asks the user whether to allow location access always.

import CoreLocation

class PermissionHandler: NSObject, CLLocationManagerDelegate {
    private let locationManager = CLLocationManager()

    func requestLocationPermission() {
        locationManager.delegate = self
        locationManager.requestWhenInUseAuthorization()
    }

    func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
        switch manager.authorizationStatus {
        case .authorizedWhenInUse:
            // Ask to extend the authorization to the background
            manager.requestAlwaysAuthorization()
        case .authorizedAlways:
            // Precise Location must also be enabled
            if manager.accuracyAuthorization == .fullAccuracy {
                NSLog("Location permission granted")
            } else {
                NSLog("Precise Location is off, detections will not run")
            }
        default:
            NSLog("Location permission not granted")
        }
    }
}

Handle the outcome in locationManagerDidChangeAuthorization(_:) rather than at the call site, since the user can change the authorization at any time from the Settings app.

Do not request "Always" directly

Calling requestAlwaysAuthorization() before "When In Use" has been granted gives your app a provisional "Always" authorization. When iOS turns it into a permanent one is unpredictable.

Android

From Android 11 (API level 30), ACCESS_BACKGROUND_LOCATION cannot be requested in the same call as foreground location. Request ACCESS_FINE_LOCATION first, and request background access in a separate call once it has been granted.

On Android 11 and above, the system does not show a dialog for the second request. It opens your app's location settings screen instead, where the user selects Allow all the time. This is enforced by Android.

import android.Manifest
import android.os.Build
import androidx.activity.result.contract.ActivityResultContracts

private val foregroundLocation = registerForActivityResult(
    ActivityResultContracts.RequestPermission()
) { isGranted ->
    if (isGranted && Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        // Only now can background access be requested
        backgroundLocation.launch(Manifest.permission.ACCESS_BACKGROUND_LOCATION)
    } else {
        Log.e(TAG, "Location permission not granted")
    }
}

private val backgroundLocation = registerForActivityResult(
    ActivityResultContracts.RequestPermission()
) { isGranted ->
    // On Android 11+, the user returns here from the settings screen
    if (isGranted) {
        Log.d(TAG, "Location permission granted")
    } else {
        Log.e(TAG, "Background location not granted, detections will not run")
    }
}

fun requestLocationPermission() {
    foregroundLocation.launch(Manifest.permission.ACCESS_FINE_LOCATION)
}

React Native

Request the two Android permissions in sequence. On iOS, location permissions are requested through the native layer, so follow the iOS instructions above.

import { PermissionsAndroid, Platform } from "react-native";

async function requestLocationPermission(): Promise<boolean> {
  const foreground = await PermissionsAndroid.request(
    PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION
  );

  if (foreground !== PermissionsAndroid.RESULTS.GRANTED) {
    console.log("Location permission not granted");
    return false;
  }

  if (Platform.Version >= 29) {
    // A separate request, and only after foreground access is granted
    const background = await PermissionsAndroid.request(
      PermissionsAndroid.PERMISSIONS.ACCESS_BACKGROUND_LOCATION
    );
    return background === PermissionsAndroid.RESULTS.GRANTED;
  }

  return true;
}

Flutter

Use a permission plugin such as permission_handler, and request the two permissions in sequence.

import 'package:permission_handler/permission_handler.dart';

Future<bool> requestLocationPermission() async {
  final whenInUse = await Permission.locationWhenInUse.request();
  if (!whenInUse.isGranted) {
    print('Location permission not granted');
    return false;
  }

  // A separate request, and only after foreground access is granted
  final always = await Permission.locationAlways.request();
  return always.isGranted;
}

Prepare the user before the second request

On both platforms the second request asks the user to extend access to the background, and on Android it takes the user out of your app. A short explanation of why the SDK needs location in the background, shown before the request, improves the chance that the user grants it.

Android also limits how often a permission dialog may be shown. After two denials, the system treats the permission as permanently denied and returns immediately without prompting, leaving your app's settings screen as the only route.

Precise Location

A user can grant background access while leaving precise location off, in which case detections will not run.

On iOS, check that accuracyAuthorization is .fullAccuracy. A temporary grant through requestTemporaryFullAccuracyAuthorization(withPurposeKey:) is not sufficient for the SDK, since the SDK requires precise location in the background. The user must enable Precise Location for your app in the Settings app.

On Android, requesting ACCESS_FINE_LOCATION gives the user the choice between Precise and Approximate in the same dialog. If they choose approximate, request the permission again to prompt for an upgrade.

---

Requesting Motion Access

This permission is optional. When granted, it helps improve the quality of the detections. Therefore, it is highly recommended to ask the user to grant this permission.

iOS

The Motion & Fitness permission is requested by iOS the first time your app queries CMMotionActivityManager. There is no separate request method.

Make sure NSMotionUsageDescription is set in your Info.plist, otherwise your app will be terminated when the permission is requested. This is enforced by iOS.

Android

On Android 10 (API level 29) and above, request the ACTIVITY_RECOGNITION permission. This is a standard runtime request with a dialog.

private val activityRecognition = registerForActivityResult(
    ActivityResultContracts.RequestPermission()
) { isGranted ->
    Log.d(TAG, "Activity recognition granted: $isGranted")
}

fun requestActivityRecognition() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        activityRecognition.launch(Manifest.permission.ACTIVITY_RECOGNITION)
    }
}

React Native

import { PermissionsAndroid, Platform } from "react-native";

async function requestActivityRecognition(): Promise<boolean> {
  if (Platform.OS !== "android" || Platform.Version < 29) return true;

  const result = await PermissionsAndroid.request(
    PermissionsAndroid.PERMISSIONS.ACTIVITY_RECOGNITION
  );
  return result === PermissionsAndroid.RESULTS.GRANTED;
}

Flutter

import 'package:permission_handler/permission_handler.dart';

Future<bool> requestActivityRecognition() async {
  final status = await Permission.activityRecognition.request();
  return status.isGranted;
}

---

Requesting Notification Access

On Android 13 (API level 33) and above, the POST_NOTIFICATIONS permission decides whether the SDK's foreground service notification is visible to the user.

Detections are not affected by this permission. The foreground service still runs, but its notification is suppressed until the permission is granted. If you have customized this notification, this is the permission that determines whether anyone sees it.

private val postNotifications = registerForActivityResult(
    ActivityResultContracts.RequestPermission()
) { isGranted ->
    Log.d(TAG, "Notification permission granted: $isGranted")
}

fun requestNotificationPermission() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        postNotifications.launch(Manifest.permission.POST_NOTIFICATIONS)
    }
}

For more about the foreground service and its notification, check out this page.

---

Verifying the Result

Do not rely on the result of your permission requests alone. The user can revoke a permission at any time from the system settings, and a granted permission does not always mean the SDK can detect. Read the effective state back from the SDK instead.

SDK Status field	What to check
locationPermission	Must be ALWAYS. ONLY_WHILE_IN_USE means the second request did not complete.
isPreciseLocationAuthorizationGranted	False when the user granted approximate location only.
isActivityRecognitionPermGranted	Motion & Fitness on iOS, Activity Recognition on Android.
detectionStatus	ENABLED_BUT_BLOCKED while any mandatory permission is missing.

For the full list of SDK status fields and what each one means, check out this page. To be notified when a permission changes while your app is running, subscribe for SDK status updates.

---

For the complete overview of platform-specific requirements, check out the following pages:

iOSAndroid