Permissions Handling

Description of required permissions, how to request and manage them.

Required Permissions

On SDK initialization, the host app passes a MoveConfig object to configure which of the SDK services should be activated. Some of those services require system permissions to be granted, or other features to be available.

From a usability perspective, Apple provides some guidelines about Requesting Permissions as part of their Human Interface Guidelines.

The table below shows each of the MoveConfig options and the corresponding required and optional permissions or sensors.

Service		Required permissions	Optional permissions[*]
Driving	Driving	Location Permission Precise Location	Motion Permission Background Location Permission
	Distraction-Free-Driving	Gyroscope and Accelerometer availability
	Driving Behavior events	Gyroscope and Accelerometer availability
	Device Detection		Bluetooth Permission
Cycling	Bicycle	Location Permission Motion Permission Precise Location	Background Location Permission
Walking	Walking	Motion Permission	Background Location Permission
	Location	LocationPermission Precise Location	Background Location Permission
Places	Places	LocationPermission Precise Location
Points of Interest	Points of Interest	Location Permission Precise Location	Background Location Permission
Public Transport	Public Transport stops	Location Permission Precise Location	Background Location Permission
Impact Detection	Impact Detection	Location Permission Precise Location Gyroscope and Accelerometer availability	Motion Permission Background Location Permission
Assistance Call	Assistance Call	Location Permission Precise Location (required permission deprecated with v2.4.0+)	Location Permission Precise Location

[*] Optional permissions can be set to required on setup by passing a MoveOptions object with the flags motionPermissionMandatory and backgroundLocationPermissionMandatory to true.

Location Permission

Authorization

This section considers the iOS 13 system location permissions changes.

Starting iOS 13, system location is split into 2 layers: CLAuthorizationStatus and CLAccuracyAuthorization

CLAuthorizationStatus:

can be granted with one of the multiple access levels. Focusing only on the MOVE SDK relevant ones:

• CLAuthorizationStatus.authorizedAlways: The user authorized the app to start and access location services at any time. Can be requested by calling requestWhenInUseAuthorization().
• CLAuthorizationStatus.authorizedWhenInUse: The user authorized the app to start location services only while the app is in use. Can be requested by calling requestAlwaysAuthorization().

Starting with iOS 13, when an app requests.authorizedAlwaysthe system prevents apps from directly receiving the.authorizedAlwaysaccess level. Instead, the operating system breaks the access into 2 steps.

• First, the operating system shows the user the permission prompt for .authorizedWhenInUse
• Later on, the operating system shows the .authorizedAlways permission prompt when the app (in our case the MOVE SDK embedded in your app) fetches the location in the background for the first time.

Check this WWDC19 session and apple documentation for further information about the iOS 13 authorization status changes.

Automatic Detection

The MOVE SDK can automatically wake up the app and activate its services (like trip detection, etc..) fully in the background and without any user interaction. Even if the app was killed by the user.

None of the SDK automatic detection services will work except if background location permissionauthorizationAlwaysis granted. Otherwise, the services will only work when the host app is in the foreground.

CLAccuracyAuthorization:

Starting iOS 13, Apple introduced 2 levels of accuracy access:

• .fullAccuracy: The user authorized the app to access location data with full accuracy.
• .reducedAccuracy: The user authorized the app to access location data with reduced accuracy.

The MOVE SDK requires full accuracy access to precisely detect trips and deliver high-quality service.

Plist

Apple requires apps requesting any system permission to provide reasoning for granting the permission. This reasoning is known as "purpose string" and is defined in the app's Info.plist file. Those purpose strings are displayed as an explanation of why the app needs those access types, in the alert shown by the system to ask the user for permission.

In the case of location permission, each access level requires including one or more corresponding keys with purpose strings.

Key	Required if
NSLocationWhenInUseUsageDescription	Your app requests "When In Use" authorization or "Always" authorization.
NSLocationAlwaysAndWhenInUseUsageDescription	Your app requests "Always" authorization.
NSLocationAlwaysUsageDescription	Your app supports iOS 10 and earlier and requests "Always" authorization.

Background Mode

Moreover, for background location access, Location update Background Modes must be enabled:

1. Go to the Capabilities tab of your target settings

2. Turn on Background Modes and enable Location updates

Location updates background mode capability

For more details about how to request location permissions, check out this Apple document.

Sample Code

Requesting.authorizedAlwayslocation authorization looks something like this:

import CoreLocation
 
class Permission: NSObject {
    let locationManager = CLLocationManager()
 
    func requestLocationPermission() {
        locationManager.delegate = self
        locationManager.requestAlwaysAuthorization()
    }  
}
 
extension Permission: CLLocationManagerDelegate {
    public func locationManager(_: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {
        // status
    }
}

Motion Permission

.plist

Same as with Location permission, Motion permission requires including the NSMotionUsageDescription with its corresponding purpose string in the app's Info.plist file.

// Example .plist for permissions.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>NSBluetoothPeripheralUsageDescription</key>
	<string></string>
	<key>NSBluetoothAlwaysUsageDescription</key>
	<string></string>
	<key>CMMotionActivity</key>
	<string>We need your motion..</string>
	<key>CLAccuracyAuthorization</key>
	<string>We need your location...</string>
	<key>NSMotionUsageDescription</key>
	<string>We need your motion...</string>
	<key>NSLocationAlwaysUsageDescription</key>
	<string>We need your location..</string>
	<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
	<string>We need your location..</string>
	<key>NSLocationWhenInUseUsageDescription</key>
	<string>We need your location..</string>
	
...

Permission

There is no direct way to request Motion Activities access permission like with Locations. Instead, the permission prompts the first time the Motions API is called.

Requesting the motion permission will look something like this:

import CoreMotion
 
func requestCoreMotionPermission() {
    let manager = CMMotionActivityManager()
    let now = Date()
    
    switch CMMotionActivityManager.authorizationStatus() {
    case .restricted, .denied:
	// "NotAuthorized
    case .authorized:
	// "Authorized"
    case .notDetermined:
        manager.queryActivityStarting(from: now, to: now, to: .main) { activities, error in
        if let error = error as? NSError, error.code == Int(CMErrorMotionActivityNotAuthorized.rawValue) {
	    // "NotAuthorized"
	    } else {
	    // "Authorized"
	    }
        }
    }   
}

Bluetooth Permission

When using the Device Detection feature it's possible to get warnings for the Bluetooth permission and power status from the SDK.

These checks will only be performed when the App itself has requested Bluetooth permission from the user, specifically ifCBCentralManager.authorization is anything other than .notDetermined.

Requesting the Bluetooth permission is done by creating an instance of the CBCentralManager type. This is entirely optional, and it's still possible to use the Device Detection service without this.

Due to Apple's static code analysis, additional strings must be configured in the Info.plist to pass validation when uploading to the AppStoreandTestflight even when this feature is not used.

Plist

Key	Required if
NSBluetoothAlwaysUsageDescription	Submitting an App to Testflight or AppStore.
NSBluetoothPeripheralUsageDescription	Required only your application is built for iOS 13.0 or below.