# Permissions Handling

## Required Permissions

On SDK initialization, the host app passes a [MoveConfig](/move-platform/move-sdk-1.x/sdk/models/moveconfig.md) 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.&#x20;

{% hint style="info" %}
&#x20;From a usability perspective, Apple provides some guidelines about [Requesting Permissions](https://developer.apple.com/design/human-interface-guidelines/ios/app-architecture/requesting-permission/) as part of their Human Interface Guidelines.
{% endhint %}

\
The table below shows each of the [MoveConfig](/move-platform/move-sdk-1.x/sdk/models/moveconfig.md) options and the corresponding required and optional permissions or sensors.

| Service                  |                                | Required permissions                               | Optional permissions                             |
| ------------------------ | ------------------------------ | -------------------------------------------------- | ------------------------------------------------ |
| TimelineDetectionService |                                |                                                    |                                                  |
|                          | Driving                        | Location Permission                                | Motion Permission Background Location Permission |
|                          | Bicycle                        | <p>Location Permission</p><p>Motion Permission</p> | Background Location Permission                   |
|                          | Walking                        | Motion Permission                                  | Background Location Permission                   |
| Driving Services         |                                |                                                    |                                                  |
|                          | Distraction-Free-Driving (DFD) | Gyroscope and Accelerometer availability           |                                                  |
|                          | Driving behavior events (DBE)  | Gyroscope and Accelerometer availability           |                                                  |
| Other Services           |                                |                                                    |                                                  |
|                          | Points of Interest (POI)       | Location Permission                                | Background Location Permission                   |

{% hint style="danger" %}
&#x20;If a required permission is missing during or after initialization, the SDK services will stop working and [SDKMoveState](/move-platform/move-sdk-1.x/sdk/models/movestate.md) will transit to`.permissionMissing`error state.
{% endhint %}

## **Location Permission**

### **Authorization**

{% hint style="info" %}
This section considers the iOS13 system location permissions changes.&#x20;

Please check [Location Permission Pre iOS13](broken://pages/-MZIkV28bRzHsM5mY2tW) for more information about handling the permission prior to iOS13
{% endhint %}

Starting iOS 13, system location is split into 2 layers: [`CLAuthorizationStatus`](https://developer.apple.com/documentation/corelocation/clauthorizationstatus) and [`CLAccuracyAuthorization`](https://developer.apple.com/documentation/corelocation/claccuracyauthorization)

#### [`CLAuthorizationStatus`](https://developer.apple.com/documentation/corelocation/clauthorizationstatus):

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

* [`CLAuthorizationStatus.authorizedAlways`](https://developer.apple.com/documentation/corelocation/clauthorizationstatus/authorizedalways): The user authorized the app to start and access location services at any time. Can be requested by calling [requestWhenInUseAuthorization()](https://developer.apple.com/documentation/corelocation/cllocationmanager/1620562-requestwheninuseauthorization).
* [`CLAuthorizationStatus.authorizedWhenInUse`](https://developer.apple.com/documentation/corelocation/clauthorizationstatus/authorizedwheninuse): The user authorized the app to start location services only while the app is in use. Can be requested by calling [requestAlwaysAuthorization()](https://developer.apple.com/documentation/corelocation/cllocationmanager/1620551-requestalwaysauthorization).

Starting iOS13, when an app requests[`.authorizedAlways`](https://developer.apple.com/documentation/corelocation/clauthorizationstatus/authorizedalways)the system prevents apps from directly receiving the[`.authorizedAlways`](https://developer.apple.com/documentation/corelocation/clauthorizationstatus/authorizedalways)access level, but instead, the system breaks the access into 2 steps. First, it shows the user the permission prompt for[`.authorizedWhenInUse`](https://developer.apple.com/documentation/corelocation/clauthorizationstatus/authorizedwheninuse)and later on, shows the[`.authorizedAlways`](https://developer.apple.com/documentation/corelocation/clauthorizationstatus/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](https://developer.apple.com/videos/play/wwdc2019/705/) and [apple documentation](https://developer.apple.com/documentation/corelocation/cllocationmanager/1620551-requestalwaysauthorization) for further information about the iOS13 authorization status changes.

{% hint style="danger" %}

#### 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 permission[`authorizationAlways`](https://developer.apple.com/documentation/corelocation/clauthorizationstatus/authorizedalways)is granted. Otherwise the services will only work when the host app is in the foreground.
{% endhint %}

#### [`CLAccuracyAuthorization`](https://developer.apple.com/documentation/corelocation/claccuracyauthorization):

Starting iOS13, Apple introduced 2 levels of accuracy access:

* [`.fullAccuracy`](https://developer.apple.com/documentation/corelocation/claccuracyauthorization/fullaccuracy): The user authorized the app to access location data with full accuracy.
* [`.reducedAccuracy`](https://developer.apple.com/documentation/corelocation/claccuracyauthorization/reducedaccuracy): The user authorized the app to access location data with reduced accuracy.

{% hint style="warning" %}
The MOVE SDK **requires** full accuracy access to precisely detect trips and deliver high-quality service.
{% endhint %}

### **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`](https://developer.apple.com/documentation/bundleresources/information_property_list/nslocationwheninuseusagedescription)                   | Your app requests When In Use authorization or Always authorization.    |
| [`NSLocationAlwaysAndWhenInUseUsageDescription`](https://developer.apple.com/documentation/bundleresources/information_property_list/nslocationalwaysandwheninuseusagedescription) | Your app requests Always authorization.                                 |
| [`NSLocationAlwaysUsageDescription`](https://developer.apple.com/documentation/bundleresources/information_property_list/nslocationalwaysusagedescription)                         | Your app supports iOS 10 and earlier and requests Always authorization. |

### **Background Mode**

Moreover, for background location access, Location updates 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](/files/-MaWrFoEnyiReo8XoJL3)

{% hint style="info" %}
For more details about how to request location permissions, check out this Apple [document](https://developer.apple.com/documentation/corelocation/requesting_authorization_for_location_services).
{% endhint %}

### Sample Code

Requesting[`.authorizedAlways`](https://developer.apple.com/documentation/corelocation/clauthorizationstatus/authorizedalways)location authorization looks something like this:

```swift
import CoreLocation
 
class Permission {
    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](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW21) with its corresponding purpose string in the app's `Info.plist` file.

### **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:

```swift
import CoreMotion
 
func requestCoreMotionPermission(){
    let manager = CMMotionActivityManager()
    let now = NSDate()
 
    manager.queryActivityStartingFromDate(now, toDate: now, toQueue: NSOperationQueue.mainQueue(),
        withHandler: { (activities: [CMMotionActivity]?, error: NSError?) -> Void in
          if let error = error where error.code == Int(CMErrorMotionActivityNotAuthorized.rawValue){
            // "NotAuthorized"
         }else {
            // "Authorized"
         }
    })
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.movesdk.com/move-platform/move-sdk-1.x/sdk/appendix/ios/permission-handling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.