Runtime Permission API

Permissions that are granted/denied at the app’s run time are known as runtime permissions. These permissions are not requested by the app during its install process. Apps require runtime permissions to access the resources of the device or the end-user's data. The runtime permissions give users more control over the functionality of the application. Quantum Visualizer provides a set of APIs that helps you check the status of the permission, request and obtain permission to access a resource.

The Runtime Permissions API uses the kony.application Namespace and contains the following functions.

Function	Description
`kony.application.checkPermission`	Checks for and returns the permission status of one or more resources.
`kony.application.requestPermission`	Requests for the end-user's consent to access a particular resource.
`kony.application.requestPermissionSet`	Sends a request for a set of permissions. The status of the request is sent back to the user through a callback.
`kony.application.openApplicationSettings`	Opens the application-specific settings or the device-level application settings.

To check the status of a permission for a resource, use the kony.application.checkPermission function. You can then request the user’s consent to access a resource or set of resources by using the kony.application.requestPermission or kony.application.requestPermissionSet function. Use the kony.application.openApplicationSettings function to open the Application settings to grant permissions.

In the kony.application.requestPermission function, specify the following Resource constants to proceed with the API.

RESOURCE_EXTERNAL_STORAGE = 1009
RESOURCE_PHOTO_GALLERY = 1011;

For Android, make sure that the WRITE_EXTERNAL_STORAGE permission is defined under the Manifest Properties. Here are the steps to define:

Open the application, and click Project Settings icon. The Project Settings window opens.
Click the Native tab, and then click Android sub-tab.
Under the Manifest Properties, click the Permissions tab.
Select the WRITE_EXTERNAL_STORAGE options from the left pane and click Add. Make sure that the selected options is moved to the right pane.
Under the Manifest Properties, click the Tags tab.
Click Finish.

To view the functionality of the Runtime Permission API in action, download the sample application from the link below. Once the application is downloaded, build and preview the application using the Quantum App.

Permission Model in different platforms

Android

The Android versions prior to 6.0, the system permissions were granted by the Android system to the apps during its installation process without user intervention. But from the Android 6.0 onwards, users grant permissions to the apps. These permissions are granted at the app run time, but not during the app installation. In Android, the system permissions are categorized in to:

Normal: The permissions that do not directly cause any risk to user’s privacy are considered as normal permissions. If you add a normal permission to your app’s manifest, the system grants permission automatically without user intervention.

Dangerous: The permissions that provide access to the user’s confidential data are known as dangerous permissions. If any dangerous permission added to your app’s manifest, explicitly the user has to grant permission to your app to access. All dangerous permissions are associated to a group. If user grants permission to any one in the group, the other permissions in the group are also granted automatically. For more information and list of dangerous permissions, refer to Android System Permissions.

The apps developed for Android 6.0 and later versions need to check the permission status manually, and then request to obtain the permission to use a particular resource.

iOS

Similarly, from iOS 8.0 onwards, there are a set of sensitive resources protected by user consent. To access these resources, apps need to check the permission status and obtain the necessary permissions manually. Application-specific permissions can also be altered from the device global settings.

In iOS devices, if your app does not have permission to access a particular resource, the app can request for permission only for once at launching the app for the first time. If the user grants permission, your app can access the resource; if the user denies, the app cannot access the resource and cannot request for permission once again from the app as well. When the app request for the permission second time or later, the system prompts the cannot access pop-up.

The only way to make the app access the resource is user has to enable the access using the device's global settings.

Handling Permissions Automatically by Platforms

Apart from providing the APIs to check, request, and obtain permissions - Quantum Visualizer enables the platforms handle the permissions for the apps. Platforms handling the permissions helps avoiding occurrence of any issues while migrating to the latest versions of the platforms. For example, changing Android target SDK from previous versions to 6.0 or later versions.

Certain synchronous APIs throw the “PermissionError” exception when user denies permission. To handle these exception, place try-catch block around these APIs.

Example for usage of the Runtime Permission API Functions

The following example gives you brief idea about how runtime permission APIs work and can be utilized.


var options = {
isAccessModeAlways:true
};
var result = kony.application.checkPermission(kony.os.RESOURCE_LOCATION,options);
if(result.status == kony.application.PERMISSION_DENIED){ 
//Indicates permission denied
   if(result.canRequestPermission){
     kony.application.requestPermission(resourceConfig, permissionStatusCallback);
     }
   else{
     Var basicConfig = {
     alertType : constants.ALERT_TYPE_CONFIRMATION,
     message : “Please enable the permission in Device Settings to proceed. Do you want to open settings?”,
     alertHandler : permissionAlertHandler
     }
     kony.ui.Alert(basicConfig);
   }
}
else if(result.status == kony.application.PERMISSION_GRANTED){
     kony.location.getCurrentPosition();
     }
else if(result.status == kony.application.PERMISSION_RESTRICTED){
     alert(“Resource Aceess Restricted for User”);
     }
function permissionAlertHandler(resp){
   if(resp)
     kony.application.openApplicationSettings();
    }
function permissionStatusCallback(response){
   if(response.status == kony.os.PERMISSION_GRANTED)
     kony.location.getCurrentPosition(…);
   else if(response.status == kony.os.PERMISSION_DENIED){
     Var basicConfig = {
     alertType : constants.ALERT_TYPE_CONFIRMATION,
     message : “Please enable the permission in Device Settings to proceed. Do you want to open settings?”,
     alertHandler : permissionAlertHandler
     }
     kony.ui.Alert(basicConfig);
  }
}

Permission Status

When apps request for the permissions to access the required resources, the underlying platform responds the permission status. For example, if any resource is not protected by a permission, the platform responds with granted status immediately. If the resource is not available, the platform responds with denied status.

Here is a list of permission statuses returned by platforms when apps requested for permissions. The platforms return these statuses based on the user's decision when the app requested for a permission. For example, if an app wants to access the user's location and for this, the app prompts a dialog box with the "Allow" and "Deny" options. If user taps the "Allow" option, the permission is granted and if user taps the "Deny" option, the permission is denied. And the platform returns the respective statuses to the app in the back end. From Android 6 onwards, two options “Allow” or “Deny and Never Ask Again” are displayed. When "Never Ask Again" option is chosen by the user, request permission dialog box will not be shown for that application and for the respective permissions unless it is changed manually from the phone settings.

kony.application.PERMISSION_DENIED

Indicates not enough permissions to access the resource. So, app should request for a permission. The status is responded when:

end-user denies to access the resource
the resource is not available.

kony.application.PERMISSION_GRANTED

Indicates app is authorized to access the resource. The status is responded when:

end-user grants permission to access the resource
resource is not protected by any permission.

kony.application.PERMISSION_RESTRICTED

Indicates device policy prohibits the app to use the resource. In this case, app cannot not access the resource.

kony.application.RESOURCE_NOT_SUPPORTED

Indicates given resource ID is not applicable in the platform. The status is responded when

the resource ID is not supported in the underlying platform
the resource ID is invalid.

kony.application.PERMISSION_NEVER_ASK_AGAIN

Applicable for Android only. Indicates not enough permissions to access the resource and the user will not see the request again. The status is responded when:

user denies to access the resource and does not want to see the request again.

Resource IDs

As runtime permissions are required to access the resources - the resources are identified with the help of resource IDs exhibited by the platforms. You can also pass additional options to identify the exact resource to access. The additional options contain platform-specific keys based on the resource ID that needs permission. For example, if your app wants to access the user location, the resource ID is "LOCATION" and you can use the "isAccessModeAlways" property as an additional option, which is a platform-specific key for iOS devices.

For the resources protected by the permissions, the Android platform identifies the permission required based on the permission declared in the AndroidManifest.xml using the additional options provided along with the resource ID.

The following table lists the resource IDs along with the supported platform-specific additional options and associated Android permissions. The Android permissions listed for the resource IDs in the table below, need to be set true under Manifest Properties in the Project Settings>Native>Android tab.

Resource ID	Description	Platform-specific Option	Android Permission
kony.os.RESOURCE_ LOCATION	Access to the user's location.	isAcessModeAlways: Indicates the mode of geo location usage. Type: Boolean Platform: iOS	ACCESS_FINE_LOCATION ACCESS_COARSE_LOCATION
kony.os.RESOURCE_CAMERA	Access to the device's camera.	isVideoCapture: Indicates permission required to access camera to capture a photo or a video. The default value is false. To access camera to record a video needs RECORD_AUDIO permission in the Android platform. Type: Boolean Platform: Android isAccessModePublic: Indicates whether a captured photo can be saved to external storage or not. The isAccessModePublic option needs WRITE_EXTERNAL_STORAGE permission in the Android platform to access external storage location. Type: Boolean Platform: Android	CAMERA WRITE_EXTERNAL_STORAGE RECORD_AUDIO
kony.os.RESOURCE_PHOTO_GALLERY	Access to the photo album or gallery.	-	Not protected by any permission.
kony.os.RESOURCE_CONTACTS	Access to the user's contacts.	-	READ_CONTACTS WRITE_CONTACTS GET_ACCOUNTS
kony.os.RESOURCE_CALENDAR	Access to the device's calendar.	-	READ_CALENDAR WRITE_CALENDAR
kony.os.RESOURCE_EXTERNAL_STORAGE	Access to the external storage such as SD card.	-	READ_EXTERNAL_STORAGE WRITE_EXTERNAL_STORAGE
kony.os.RESOURCE_LOCATION_ACCESS_IN_BACKGROUND	Access to the device location when application is running in background. This is applicable only to Android platform.	-	ACCESS_BACKGROUND_LOCATION ACCESS_FINE_LOCATION ACCESS_COARSE_LOCATION
kony.os.RESOURCE_NOTIFICATION	Access to receive notifications.	-	POST_NOTIFICATION
kony.os.RESOURCE_MEDIA	Access to photos and videos available on the device.	-	READ_MEDIA_IMAGES READ_MEDIA_AUDIO READ_MEDIA_VIDEO

NOTE: Support for the kony.os.RESOURCE_NOTIFICATION and kony.os.RESOURCE_MEDIA Resource IDs is available from the Android 13 release.
When you invoke these Resource IDs on Android 13 (or later versions) devices, the permission request dialog box appears with the Allow and Don't Allow options.
When you invoke these Resource IDs on Android 12 (or earlier versions) devices, the kony.application.checkPermission and the kony.application.requestPermission APIs return the RESOURCE_NOT_SUPPORTED value in the callback.