Permission Handling

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

The library requires at least the following permissions to access MOVE SDK services.

<uses-permission android:name="android.permission.INTERNET" />

Depending on the used services, different permissions are required. The following table gives an overview what's required:

Permission overview

		Required permissions	Optional permissions
Mode of Transport	Driving	ACCESS_FINE_LOCATION	ACTIVITY_RECOGNITION - improves trip recognition and classification considerably
	Bicycle	ACCESS_FINE_LOCATION, ACTIVITY_RECOGNITION
	Walking	ACTIVITY_RECOGNITION
Driving Services	Distraction-Free-Driving (DFD)	READ_PHONE_STATE, SYSTEM_ALERT_WINDOW
	Driving behaviour events (DBE)
Other services	Points of Interest	ACCESS_FINE_LOCATION

Background Location is not mandatory, but strongly recommended. Similarly for the optional Activity Recognition permission (Driving) - make sure to request this from the user, otherwise it will degrade the quality of the service.

More Information regarding the system permissions can be found here: https://developer.android.com/reference/android/Manifest.permission

The required permissions must be granted before the services can be used. If any single required permission is missing, the entire MOVE SDK stops working. In case of any permission error, the SDKState callback will be triggered with an error state: MoveSdkState.Error

If there are permissions missing, the state is an object of type MoveSdkState.Error. The error state contains an error reason which can be any of the following:

• Overlay (ErrorReason.PermissionMissing.Overlay)

• Location (ErrorReason.PermissionMissing.Location)

• Phone (ErrorReason.PermissionMissing.Phone)

• Activity (ErrorReason.PermissionMissing.Motion) (since Android 10 )

The PermissionMissing error reason contains a string pertaining to the relevant permission of the Android Manifest, e.g. Manifest.permission.READ_PHONE_STATE. This permission string can be used to request dangerous permission directly as shown in the code example below. For more information about dangerous visit the official developer page.

In fact the SDK is not aware of permission changes, the developer can tell the MOVE SDK that the error is resolved. This can be done for example in onRequestPermissionsResult().

override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>, grantResults: IntArray) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
 
    val sdkStatus = moveSdk.getSdkState()
    if (sdkStatus is MoveSdk.State.Error) {
        // Tell the SDK that we have fixed our issue
        sdkStatus.resolved()
    }
}

Runtime permissions

In Android there are some permissions which require a request during runtime. Keep in mind that those need to be defined in the manifest as well. Before init of the MOVE SDK, the proper permissions should have been already requested.

Display over other apps

The overlay permission (SYSTEM_ALERT_WINDOW) ,which is required for distraction free driving, needs to be requested in a specific way. The user is lead to the app settings where the permission needs to be enabled.

Starting with Android 11, the user will only be taken to the settings overview screen, and the user needs to select the specific app itself.

val intent = Intent(
    Settings.ACTION_MANAGE_OVERLAY_PERMISSION,
    Uri.parse("package:$packageName"))
startActivityForResult(intent, OVERLAY_REQUEST_CODE)

Android App Info - Display over other apps

Background location

Since Android 10 there is an additional background location which should be also requested when asking for location permission. In Android 11 the user must go to the location settings of the app to grant the "Allow all the time" permission.

if (reason is ErrorReason.PermissionMissing.Location) {
    val permissions = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        // On Android Q both (foreground & background) permissions should be requested
        arrayOf(Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_BACKGROUND_LOCATION)
    } else {
        arrayOf(Manifest.permission.ACCESS_FINE_LOCATION)
    }
    ActivityCompat.requestPermissions(this@MoveActivity, permissions, 0)
}

Full code example

The following shows an example which is used in our demo app.

val reason = errorState.reason
if (reason is ErrorReason.PermissionMissing) {
    if (reason is ErrorReason.PermissionMissing.Overlay) {
        requestOverlayPermission()
    } else if (reason is ErrorReason.PermissionMissing.Location) {
        val permissions = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
            // On Android Q both (foreground & background) permissions should be requested
            arrayOf(Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_BACKGROUND_LOCATION)
        } else {
            arrayOf(Manifest.permission.ACCESS_FINE_LOCATION)
        }
        ActivityCompat.requestPermissions(this@MoveActivity, permissions, 0)
    } else {
        val missingPermission = reason.permission
        ActivityCompat.requestPermissions(this@MoveActivity, arrayOf(missingPermission), 0)
    }
}
...
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
 
    if (requestCode == OVERLAY_REQUEST_CODE) {
        val moveSdk = yourApplication.getMoveSdk()
        val sdkStatus = moveSdk.getSdkState()
        if (sdkStatus is MoveSdkState.Error) {
            // Tell SDK that we have fixed our issue
            sdkStatus.resolved()
        }
    }
}