Capture User Permissions

After verifying the user’s information, the IQL Reference Application requests for certain permissions in order to track trips. The following sections describe the user permissions required on Android devices:

1.0. Capture Location Permissions

This section discusses the user permissions that need to be enabled on Android devices so that IQL can track trips. The user needs to enable the Always allow location permission so that IQL can automatically detect trips in the background.

1.1. Update Android Manifest File

To obtain location permission, you need to first add permissions to the AndroidManifest file, followed by a two-step process, as described in the following sections.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:tools="http://schemas.android.com/tools"
   xmlns:android="http://schemas.android.com/apk/res/android">
.
.
.
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
.
.
.
</manifest>

1.2. Capture Location Permission - Allow While Using

This section describes how to enable location permission only while using the Publisher’s application. Use the following code snippet to request the user to grant the Allow while using permission.

class PermissionsActivity : AppBaseActivity() {
.
.
.
// Function to request location permission
private fun requestPermission(permission: Permission) {
   Timber.d("REQUESTED ${getString(permission.permissionStringRes.title)} ${permission.status}")
   if (permission.manifestPermissions[0] == Manifest.permission.SYSTEM_ALERT_WINDOW) {
       if (Settings.canDrawOverlays(this)) {
           viewModel.permissionAccessGranted(permission)
       } else {
           openSettings(permission.requestCode)
       }
       return
   }

   val granted = viewModel.hasPermissionGranted(viewModel.getPermissions(permission))
   // Here, this Activity is the current activity
   if (!granted) {
       Timber.d("ASK ${getString(permission.permissionStringRes.title)} ${permission.status}")
       // Permission is not yet granted and hence request the required permission
       ActivityCompat.requestPermissions(
           this,
           permission.manifestPermissions,
           permission.requestCode
       )
   } else {
       // Permission has already been granted
       Timber.d("Granted permission ${getString(permission.permissionStringRes.title)} ${permission.status}")
       viewModel.permissionAccessGranted(permission)
   }
}
.
.
.
}


@Parcelize
data class Permission(
   .
   .
   .
   val manifestPermissions: Array<String>,
   val backgroundLocationManifestPermissions: Array<String> = emptyArray(),
   .
   .
   .
) : Parcelable {
   companion object {


// Location permission object
       val location = Permission(
           // UI Elements that needs to be displayed on different states of the permission
           permissionStringRes = getPermissionStringRes(PermissionRequestTypes.LOCATION_PERMISSION_REQUEST),
           // Required for requesting foreground location permission
           manifestPermissions = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
               arrayOf(
                   Manifest.permission.ACCESS_FINE_LOCATION,
                   Manifest.permission.ACCESS_COARSE_LOCATION
               )
           } else {
               arrayOf(
                   Manifest.permission.ACCESS_FINE_LOCATION
               )
           },
           // Required for requesting background location permission
           backgroundLocationManifestPermissions = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
               arrayOf(
                   Manifest.permission.ACCESS_BACKGROUND_LOCATION
               )
           } else {
               emptyArray()
           },
           requestCode = PermissionRequestTypes.LOCATION_PERMISSION_REQUEST.code
       )
      .
      . 
      .
}
}

1.2.1. How To Handle Denial of the 'Allow while using' Permission

If the Allow while using location permission is denied, display a rational dialog that conveys the requested permission's utility. If the user permanently denies the request, navigate the user to the application's settings page to manually update the location permission. Make sure that the Precise Location permission is granted for the required Android OS levels. Without access to the Precise Location, it should still be considered as location permission denied.

class PermissionsActivity : AppBaseActivity() {
…
…
…
private fun showRational(permission: Permission) {
   val context = binding.root.context
   with(binding) {
       errorTitleLayout.makeVisible()
       title.makeGone()
       error.setTextColor(ContextCompat.getColor(context, R.color.tx_red))
       if (permission.requestCode == PermissionRequestTypes.LOCATION_PERMISSION_REQUEST.code) {
           description.makeGone()
           errorDescription.makeVisible()
           errorDescription.text = context.getText(R.string.we_cannot_determine_your_location)
           error.text = context.getString(R.string.allow_location_access)
           stepsText.makeVisible()
           layoutGuide.makeVisible()
           permissionGuide.makeGone()
           setStepText(context)
       } else if (permission.requestCode == PermissionRequestTypes.ACTIVITY_PERMISSION_REQUEST.code) {
           description.makeGone()
           error.text = context.getString(permission.permissionStringRes.error)
           errorDescription.makeVisible()
           errorDescription.text = context.getText(R.string.we_cant_activate)
           permissionGuide.makeGone()
           layoutGuide.makeVisible()
           stepsText.makeVisible()
           stepsText.text = HtmlCompat.fromHtml(context.getString(permission.permissionStringRes.permissionGuideForError), HtmlCompat.FROM_HTML_MODE_LEGACY)
       }
   }
}
…
…
…
	private fun openSettings(requestCode: Int) {
   		val uri = Uri.parse("package:$packageName")
            val intent = Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, uri)
            if (requestCode == Permission.location.requestCode) {
                getResultForLocationPermission.launch(intent)
            } else if (requestCode == Permission.activityRecognition.requestCode) {
               getResultForActivityPermission.launch(intent)
            }
      }
…
…
…
}

1.3. Capture Location Permission - Allow All the Time

This section describes how to capture location permission Allow all the time, after you have obtained the Allow while using location permission from the user.

Use the following code snippet to request for the Allow all the time location permission.

class PermissionsActivity : AppBaseActivity() {
...
...
...
private fun requestBackgroundLocationPermission(permission: Permission) {
   ActivityCompat.requestPermissions(
       this,
       permission.backgroundLocationManifestPermissions,
       PermissionRequestTypes.BACKGROUND_LOCATION_PERMISSION_REQUEST.code
   )
}
...
...
...
}

If the requested location permission is denied, display a rational dialog. If the user permanently denies your request, navigate the user to the application's settings page to manually grant the location permission, as shown in the UX designs above.

2.0. Capture Physical Activity Permission

This section describes how to enable physical activity access on Android devices for IQL.

2.1. Update Android Manifest File

Add activity recognition permissions to the AndroidManifest file, as shown in the following tab.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:tools="http://schemas.android.com/tools"
   xmlns:android="http://schemas.android.com/apk/res/android">
.
.
.
   <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
/>
.
.
.
</manifest>

2.2. Capture Physical Activity Permission

After you have obtained the Location Permissions, request the user to grant the Physical Activity permission, using the following code snippets:

private fun requestActivityPermission(permission: Permission) {
   // Check if given permission is already provided. In this case, Activity permission.
   val granted = viewModel.hasPermissionGranted(viewModel.getPermissions(permission))
   if (!granted) {
       Timber.d("ASK ${getString(permission.permissionStringRes.title)} ${permission.status}")
       // Permission is not granted and hence request the required permission
       ActivityCompat.requestPermissions(
           this,
           permission.manifestPermissions,
           permission.requestCode
       )
   } else {
       // Permission has already been granted
       Timber.d("Granted permission ${getString(permission.permissionStringRes.title)} ${permission.status}")
       viewModel.permissionAccessGranted(permission)
   }
}

If the user denies the Physical Activity permission, display a rational dialog that explains exactly why this permission is needed. Then, navigate the user to the application's settings page to manually update the permission.

3.0. Capture Notification Permission

Android 13 (API level 33) and higher require a runtime permission for sending notifications from an application, if the Android targetSDKVersion 33.

3.1. Update Android Manifest File

The Android manifest file allows you to declare the specific permissions that an application needs, in order to access data from other applications. The Android manifest file helps the Android SDK to build the application by specifying the application's package name.

Add notification permissions to the AndroidManifest file, as shown below:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

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

</manifest>

3.2. Capture Notification Permission

After you have obtained the Physical Activity permission, request the user to grant Notification permission, using the following code snippets:

private fun requestPermission(permission: Permission) {
   Timber.d("REQUESTED ${getString(permission.permissionStringRes.title)} ${permission.status}")
   // check if the permission is granted
   val granted = viewModel.hasPermissionGranted(viewModel.getPermissions(permission))
   // Here, thisActivity is the current activity
   if (!granted) {
       Timber.d("ASK ${getString(permission.permissionStringRes.title)} ${permission.status}")
       // Permission is not yet granted and hence request the required permission
       ActivityCompat.requestPermissions(
           this,
           permission.manifestPermissions,
           permission.requestCode
       )
   } else {
       // Permission has already been granted
       Timber.d("Granted permission ${getString(permission.permissionStringRes.title)} ${permission.status}")
       viewModel.permissionAccessGranted(permission)
   }
}

4.0. Disable Or Ignore Battery Optimization

Some devices allow battery optimizations that affect Zendrive SDK’s capability to record trips in the background. This section describes how to configure battery settings accurately to record user's trips. Here's a partial list of the devices that allow battery optimization:

Samsung
OnePlus
Xiaomi
Huawei

We recommend that you use the following code snippets to ignore or disable user's battery optimization, after obtaining the Physical Activity permission.

@Parcelize
data class Permission(
   val permissionStringRes: PermissionStringRes,
   val manifestPermissions: Array<String>,
   val backgroundLocationManifestPermissions: Array<String> = emptyArray(),
   val requestCode: Int,
   var status: PermissionStatus = PermissionStatus.Initial
) : Parcelable {
   companion object {
.
.
.
val batterySettings = Permission(
   // UI Elements that needs to be displayed on different states of the permission
   permissionStringRes = getPermissionStringRes(PermissionRequestTypes.BATTERY_SETTINGS_REQUEST),
   // Required for requesting ignore battery optimization
   manifestPermissions = arrayOf(
       Manifest.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS
   ),
   requestCode = PermissionRequestTypes.BATTERY_SETTINGS_REQUEST.code)
.
.
.
.
   }
}

 
// Class to handle battery settings to disable or ignore battery optimization according to //manufacture types
class BatterySettingsActivity : AppCompatActivity() {
.
.
.
private fun goToSettingsSamsung() {
   val intent = Intent()
   intent.action =
       Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS
   intent.data = Uri.parse("package:$packageName")
   startActivityForResult(intent, REQUEST_CODE_SETTINGS)
}

private fun goToOnePlus() {
   val intent = Intent()
   intent.action =
       Settings.ACTION_SETTINGS
   intent.data = Uri.parse("package:$packageName")
   startActivityForResult(intent, REQUEST_CODE_SETTINGS)
}

private fun goToSettingsXiaomi() {
   val intent = Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS)
   intent.addCategory(Intent.CATEGORY_DEFAULT)
   intent.data = Uri.parse("package:$packageName")
   val activityExists = isActivityIntentResolvable(intent)
   if (activityExists) {
       startActivityForResult(intent, REQUEST_CODE_SETTINGS)
   }
}

private fun goToSettingsHuawei() {
   val started =
       startHuaweiIntent(PACKAGE_HUAWEI_COMPONENT)
   if (!started) {
       startHuaweiIntent(PACKAGE_HUAWEI_COMPONENT_FALLBACK)
   }
}
.
.
.
}

5.0. IQL Reference Application UX Design

Here is the overall design implementation for the IQL Reference Application:

6.0. Publisher Integration Testing Checklist

Use the following testing checklist to test the Capture User Permissions process:

Location Permission: Ensure that the user is prompted to always allow the application to access their location. If the user selects a permission type other than 'Always', display an error stating that location access needs to be set to 'Always' for the application to work correctly. In case Precise location access is turned off, make sure that the application displays an error, requesting the user to grant Precise location access.
Allow Once Permission Access: If the user selects the 'Allow once' location permission type, the application should display an error stating that location permission needs to be set to 'Always' for the application to work accurately.
'Don't Allow' Permission Type: If the user selects the Don't allow location permission type, make sure the application displays an error stating that location permission needs to be set to 'Always' for the application to work accurately.
Physical Activity: Ensure that the user is prompted to grant the physical activity permission. If the user denies the permission, display an error message indicating that the permission is required for the app to function properly.
Battery Optimization: Ensure that the application requests the user to disable battery optimization on devices where applicable.
Notification: Ensure that the user is requested for notification permission at least once. This allows the application to inform the user promptly if or whenever an offer is available. It also allows the application to inform the users about any possible issues affecting the program and offer generation.

PreviousCapture User Information NextEnable Program Reactivation