Functions
The Runtime Permission API contains the following functions, which are part of the voltmx.application Namespace.
voltmx.application.checkPermission
Checks and returns the permission status of one or more resources.
Syntax
voltmx.application.checkPermission(resourceId\[constant/String\], options\[JSObject\])Input Parameters
| Parameter | Description |
|---|---|
| resourceId [constant/String] - Mandatory | Specify the ID of the resource or name of the permission (only for Android) for which you want to check the status. You can specify either a String (permission name) or an integer (resourceId) value. The feature to specify the name of the permission as a String is applicable only for Android. For instance, you can query a Native Android permission from the AndroidManifest.xml file by specifying the String directly: “android.permission.READ_PHONE_STATE”. |
| options [JSObject] - Optional | Specify the additional option to identify the exact resource of which you want to know the status. This is a platform-specific key. For more information, refer to Resource ID. |
Example 1
var options = {
isAccessModeAlways: true
};
var result = voltmx.application.checkPermission(voltmx.os.RESOURCE_LOCATION, options);
if (result.status = = voltmx.application.PERMISSION_DENIED) {
voltmx.application.requestPermission();
} else if (result.status = voltmx.application.PERMISSION_GRANTED) {
voltmx.location.getCurrentPosition();
}Example 2
< uses - permission android: name = "android.permission.READ_PHONE_STATE" / >
var result = voltmx.application.checkPermission("android.permission.READ_PHONE_STATE");
if (result.status = = voltmx.application.PERMISSION_DENIED) {
voltmx.application.requestPermission();
} else if (result.status = voltmx.application.PERMISSION_GRANTED) {
voltmx.location.getCurrentPosition();
}Return Values
JSObject
A JS Object contains the authorization status of the requested resource. The returned JSObject contains the following keys:
| Return value | Description |
|---|---|
| status [constant] | Resource status constant which indicates the overall status of the resource authorization. For more information, refer to Permission Status. |
| canRequestPermission [Boolean] | Indicates whether you can request for the permissions or not in case the value of the status is PERMISSION_DENIED. In the iOS platform, authorization for a resource can be requested only once. For more information, refer to Permission model in iOS.In the Android platform, the app can request for the permissions even though the status return value is PERMISSION_DENIED or direct the user to app settings to turn on or off the authorization. |
Platform Availability
- Android
- iOS
- Windows
- SPA
voltmx.application.getBackgroundPermissionOptionLabel
Fetches the localized label that corresponds to the option in the Project Settings that grants access for the app to run in the background.
The intended use of this permission is for apps to reference this label in the instruction that is displayed to the users requesting background access.
Syntax
voltmx.application.getBackgroundPermissionOptionLabel()Input Parameters
None
Example
showEducationalUI: function() {
var text = voltmx.application.getBackgroundPermissionOptionLabel();
voltmx.ui.Alert({
"alertType": constants.ALERT_TYPE_CONFIRMATION,
"alertTitle": "Backgroun Location Permission",
"yesLabel": "Ok",
"noLabel": "Cancel",
"message": "Allow Background Location Permission by click on the " + text,
"alertHandler": this.callback
}, {
"iconPosition": constants.ALERT_ICON_POSITION_LEFT
});
},
callback: function() {
voltmx.application.requestPermission("android.permission.ACCESS_BACKGROUND_LOCATION", this.permissionStatusCallback);
},
permissionStatusCallback: function(response) {
if (response.status == voltmx.application.PERMISSION_GRANTED) {
alert("granted");
} else {
alert("denied")
}
}Return Values
String
Platform Availability
- Android
voltmx.application.isAutoRevokeWhitelisted
Checks whether an application is exempt from having its permissions be automatically revoked when the app is unused for an extended period of time.
Note: This API is only available on Android 11 (OS API level 30), or later devices. If the app uses target SDK versions less than version 30, the behavior of this API may not be as expected.
Syntax
voltmx.application.isAutoRevokeWhitelisted()Input Parameters
None
Example
function isAutoRevokeWhitelisted() {
var retVal = voltmx.application.isAutoRevokeWhitelisted();
voltmx.print(" Is my application whitelisted "+ retVal);
}Return Values
Boolean
- true: The package is whitelisted from having its runtime permission be auto-revoked if unused for an extended period of time.
- false: The package is not whitelisted from having its runtime permission be auto-revoked if unused for an extended period of time.
Platform Availability
- Android
voltmx.application.launchAutoRevokeSettings
This API navigates the user to the application’s page in the system settings, from where users can prevent the system from automatically revoking the application permissions.
In the app settings screen that appears, users must follow these steps to prevent the system from revoking the app permissions:
- Tap Permissions.
The App Permission Settings appear. - Disable the Remove permissions if app isn’t used option.
Note: This API is only available on Android 11 (OS API level 30), or later devices.
Syntax
voltmx.application.launchAutoRevokeSettings();Input Parameters
None
Example
function launchAutoRevokeSettings(){
voltmx.application.launchAutoRevokeSettings();
}Return Values
None
Remarks
This API is useful in situations where the app works in the background and there is no user interaction. For example, the API can be used in the following scenarios:
- Provide family safety
- Sync data
- Communicate with smart devices
- Pair compatible devices
Platform Availability
- Android
voltmx.application.requestPermission
Sends a request to the end-user to provide the access to specific resource.
Syntax
voltmx.application.requestPermission(resourceId\[constant/String\], statusCallback\[Function\], options\[JSObject\])Input Parameters
| Parameter | Description |
|---|---|
| resourceId [constant/String] - Mandatory | Specifies the ID of the resource or name of the permission (only for Android) that you want to access. You can specify either a String (permission name) or an integer (resourceId) value. The feature to specify the name of the permission as a String is applicable only for Android. For instance, you can query a Native Android permission from the AndroidManifest.xml file by specifying the String directly: “android.permission.READ_PHONE_STATE”. The available resourceId constants are as follows: voltmx.os.RESOURCE_CAMERA voltmx.os.RESOURCE_LOCATION voltmx.os.RESOURCE_PHOTO_GALERY voltmx.os.RESOURCE_CONTACTS voltmx.os.RESOURCE_CALENDAR voltmx.os.RESOURCE_SIRI (iOS-specific) voltmx.os.RESOURCE_AUDIO_RECORD voltmx.os.RESOURCE_NOTIFICATION (iOS-specific) |
| statusCallback [Function] - Mandatory | A callback function receives the end-user’s decision. The statusCallback function receives a JS Object, which contains overall status and permission-specific status that end-user responded on the permission dialog box. function statusCallback(response); Here, response is a hash map that contains the authorization status of the requested resource. This argument contains the following key: status [constant] Resource status constant that indicates the overall status of the resource authorization. The possible values for status are as follows: voltmx.application.PERMISSION_GRANTED voltmx.application.PERMISSION_DENIED voltmx.application.PERMISSION_NEVER_ASK_AGAIN |
| options [JSObject] - Optional | Specifies the additional option to identify the resource for which you want permission. This key is applicable on android only. To obtain the voltmx.application.PERMISSION_NEVER_ASK_AGAIN status, you have to set the getNeverAskAgainStatus key to true and pass the key in the options object. If the key is not set, and the user selects either the Deny or Never Ask Again options, then the permission status is considered as VoltMX.application.PERMISSION_DENIED.var options = { “isVideoCapture”: true, “getNeverAskAgainStatus”: true } |
| options [Object] - For Notifications | This is a mandatory parameter for notifications. {notificationtypes : constants} The available constants are as follows: voltmx.notificationsettings.BADGE voltmx.notificationsettings.SOUND voltmx.notificationsettings.ALERT |
Example 1
//< uses - permission android: name = "android.permission.READ_PHONE_STATE" >
voltmx.application.requestPermission("android.permission.READ_PHONE_STATE", permissionStatusCallback);
function permissionStatusCallback(response) {
if (response.status == voltmx.application.PERMISSION_GRANTED) {
voltmx.location.getCurrentPosition();
} else if (response.status == voltmx.application.PERMISSION_DENIED) {
//Display Application Settings alert by using voltmx.application.openApplicationSettings()
}
}Example 2
function requestpermission() {
var options = {
"isVideoCapture": true,
"getNeverAskAgainStatus": true
}
voltmx.application.requestPermission(voltmx.os.RESOURCE_LOCATION, permissionStatusCallback, options);
}
function permissionStatusCallback(response) {
alert("response ::" + JSON.stringify());
if (response.status == voltmx.application.PERMISSION_GRANTED) {
voltmx.location.getCurrentPosition();
} else if (response.status == voltmx.application.PERMISSION_DENIED) {
Requestpermission(); /* To show the reason to users for granting the permission to use the feature and then raise a request. */
} else if (response.status == voltmx.application.PERMISSION_NEVER_ASK_AGAIN) {
voltmx.application.openApplicationSettings(); /* To show the reason to users for granting the permission to use the feature and then open application settings to grant the request. */
}
)
}Return Values
| Function | Description |
|---|---|
| JSObject | A JSObject contains the authorization status of the requested resource. The returned JSObject contains the following key: status [constant] Resource status constant which indicates the overall status of the resource authorization. For more information, refer to Permission Status. > Note: In the Android platform, the status remains PERMISSION_DENIED if at least one of the permissions associated with the resource is denied by the end-user. |
Platform Availability
- Android
- iOS
- Windows
- SPA
VoltMX.application.requestPermissionSet
When invoked, this API sends a request for a set of permissions. The status of the request is sent back to the user through a callback.
Syntax
VoltMX.application.requestPermissionSet(permissions, callback) Input Parameters
| Parameter | Description |
|---|---|
| Permissions | Array of qualified android permission strings. |
| Callback | Function object result will invoke this function. The result is a JSobject where the key is permission string and the value is the permission status. |
Example
function requestpermission() {
voltmx.application.requestPermissionSet(["android.permission.CAMERA", "android.permission.WRITE_CONTACTS"], permissionStatusCallback);
}
function permissionStatusCallback(response) {
var camera = "android.permission.CAMERA";
var contacts = "android.permission.WRITE_CONTACTS";
for (var i in response) {
/* iterating through permissionSet key value pair from response jsObject where 'i' is permission key and result is permission status */
var result = response[i];
if (result == voltmx.application.PERMISSION_DENIED) {
// show message and raise request again
} else if (result == voltmx.application.PERMISSION_NEVER_ASK_AGAIN) {
// show message and open settings page
voltmx.application.openApplicationSettings();
}
}
}Return Values
None.
Platform Availability
Android
voltmx.application.openApplicationSettings
Opens the application-specific settings or device-level application settings.
You may need to direct the end-user to application settings to manually enable or disable a permission for the app to access a particular resource. This function is required when the end-user had denied the permission when the app prompted with a dialog box, and later wants the app to access the resource. For example, if your app wants to access the user’s contacts - so the app displayed a dialog box with “Allow” and “Deny” options, asking end-user to grant permission for the first time. The end-user tapped the “Deny” option and the app cannot access the user’s contacts. Later, after some point of time, if end-user wants the app access the user’s contacts; at that time, you can call the openApplicationSettings API that allows the user to navigate to the application settings screen, and then grant the required permission to the app.
The behavior of the openApplicationSettings API in different platforms:
- Windows: There is no provision to open the application-level settings. The openApplicationSettings API accepts the resourceid as an optional parameter that helps open the resource-specific settings screen. If the resourceid is not provided, results in unexpected behavior.
- iOS: Opens the application-level settings screen showing the access status of the resource. The end-user can turn on or off the access to the resource from the app. The resourceid parameter is ignored in the iOS platform.
- Android: Opens the application-level settings screen showing the access status of the resource. The end-user can turn on or off the access to the resource from the app. The resourceid parameter is ignored in the iOS platform.
Syntax
voltmx.application.openApplicationSettings(resourceId\[const\])Input Parameters
| Function | Description |
|---|---|
| resourceId [constant] - Optional | Specify the resource ID of the resource that you want open its settings. The parameter works only for Windows. For more information, refer to Resource ID. |
Example
voltmx.application.openApplicationSettings(voltmx.os.RESOURCE_CONTACTS);Return Values
None
Platform Availability
- Android
- iOS
- Windows
