App permissions

An app can gather and use information about the device that it's running on. An app can retrieve device information such as the PIN and the serial number, as well as information about contacts, calendar entries, and email messages. An app can also access information about the device's surroundings, such as location and positioning information. By using this information, you can develop apps that integrate with other apps that users already have on their devices, which helps you provide an exceptional user experience.

Some of this information is considered sensitive and requires special permission to access. For example, users probably don't want just any app to be able to access their contact information, so they must grant your application access to the functionality that it needs.

The image to the right shows an example of a permission request to use the microphone on the device. This dialog box is handled and displayed automatically by the BlackBerry 10 OS when a permission request is required, so you don't need to create it yourself in your app.

Screen showing the app permissions request dialog box.

Keep in mind that users might choose not to grant certain permissions that your app needs to run properly. Users can also modify app permissions in the Settings app at any time. If users don't grant these permissions, your app should handle this situation either by closing (with an appropriate error message so the user knows what's happened) or by continuing to run with limited functionality. To learn more, see Handling ungranted permissions.

To help protect against potentially malicious code, if your app uses APIs that access restricted functionality without first requesting permission to access the device, the API returns errors. For example, if your app tries to access a file in a shared folder and your app doesn't include the access_shared permission, you receive a "permission denied" error.

You specify app permissions in the bar-descriptor.xml file of your project. Each permission is included in a separate <permission> element in the file. There are two ways to specify permissions for your app. You can use the Permissions check boxes on the Application page of your bar-descriptor.xml file or you can add permission elements manually on the Source page of your bar-descriptor.xml file.

Using the Permissions check boxes

When you open the bar-descriptor.xml file in the Momentics IDE for BlackBerry, you can click the Application tab to see the list of permissions that you can add to your app. In the Permissions section, you can select check boxes that are associated with each permission that you want your app to have.

When you select a permission, the appropriate <permission> element is added automatically to the bar-descriptor.xml file. You can verify that the element was added by clicking the Source tab.

Screen showing the permissions check boxes in the bar-descriptor.xml file.

Adding permission elements manually

Some permissions might not be available as a check box on the Application tab of the bar-descriptor.xml file. If you need to add these types of permissions to your app, you can click the Source tab and add the <permission> elements yourself.

<permission>access_notify_settings_control</permission>
<permission>access_wifi_public</permission>
<permission>_sys_run_headless</permission>

Handling ungranted permissions

If you are developing an app that requires a permission, you should make sure that the app can handle the case when the user doesn't grant the permission. When your app has a set of requested permissions specified in the bar-descriptor.xml file, the app asks the user to grant the permissions when the app starts. The user may deny one or more of the requested permissions.

Your app can't check which permissions have been granted while the app is running. Your app can only execute the functions that require the permission and handle any errors that it encounters.

Screen showing a permissions dialog box in a Cascades app.When an error that could be the result of an ungranted permission occurs, you can display a SystemDialog that explains the issue to the user and then directs the user to the Settings app with the Application Permissions screen opened. If the permission is critical to the functionality that your app is offering, a SystemDialog is a good choice because you can offer the user the option to change the permission immediately.

If the permission isn't necessary but provides additional functionality, you can provide feedback inline with a SystemToast or you can decide not to provide any feedback. For example, if your social media app shares the user's current location but the user hasn't granted the access_location_services permission, you can choose not to interrupt the UI with a dialog box because the functionality is not critical.

The following code sample shows how to attach a SystemDialog to your UI. The confirmButton is labeled "Launch Settings", and when the confirmButton is tapped, the Settings app is invoked. The displayPermissionError() function displays the SystemDialog when something goes wrong. This function can be reused for any error that might occur because a permission has not been granted by the user. When you call the function, you just have to supply the text of the message that asks the user if there is a permission that has not been granted.

import bb.system 1.2
    
    // ...     
        
    // Attach a system dialog that is used to display
    // information about missing permissions.
    attachedObjects: [

        SystemDialog {
            id: errorDialog
            title: qsTr("Something went wrong.")
            confirmButton.label: qsTr("Launch Settings")

            onFinished: {
                if (value == SystemUiResult.ConfirmButtonSelection) {
                    // The app settings object can also 
                    // launch the system settings app.
                    _appSettings.invokeSystemSettings
                        ("settings://permissions");
                }
            }
        }
    ]

	// This function is called when something goes wrong 
    // because a permission was not granted.
    function displayPermissionError(error) {
        errorDialog.body = error + 
        	qsTr(" You have to restart the app " +
        		"after changing permissions.");
        errorDialog.show();
    }

For example, your app can call displayPermissionError() when your app fails to save a photo. In the following code sample, the photoSaveFailed() signal triggers a call to the function to display the dialog box:

                
onPhotoSaveFailed: {
    // The photo couldn't be saved.
    // It could be that the permission to 
    // access shared files was not granted. 
    // Display a dialog box since this is 
    // the most likely scenario.

    displayPermissionError(qsTr("The photo couldn't be saved. "
        + "Make sure that the access_shared permission is set "))
    photoTaken = false;
}

Each API handles permissions differently. You should look at every API your app uses that requires a permission and find out what kind of errors you get when the permission has not been granted.

For example, the CalendarService class requires that the access_pimdomain_calendars permission is granted to construct a new CalendarService. If you try to call any CalendarService functions on an invalid object, your app will fail. In this case, you should probably check that the CalendarService object was created successfully before you do anything with it. If the CalendarService object was not created successfully, you could display a SystemDialog asking the user if the access_pimdomain_calendars permission was set.

If you are using the Camera class, you can create a Camera object successfully whether or not the use_camera permission is granted. It’s only when your app calls Camera::open() that the use_camera permission is necessary. To handle errors that occur when Camera::open() is called, you should listen for the cameraOpenedFailed() signal, and then check the error code to see why it failed. The camera might not open because the use_camera permission has not been granted. You can display a SystemDialog for this type of failure. For more information about finding supported and accessible cameras, see Opening the camera.

To see a sample app that uses these techniques to check for ungranted permissions, download the Rundgang sample. To learn more about system dialogs, see Dialog boxes, prompts, and toasts and review the UI guidelines for dialog boxes and toasts. To learn more about invoking the Settings app, see Invoking core applications.

Available permissions

Be sure to check the API reference for the classes that you're working with to determine which permissions you need to add.

The following table describes <permission> element values that are available:

Permission and element value Description

BlackBerry Messenger

bbm_connect

Connect to BlackBerry Messenger (BBM). You can use this permission to access contact lists and user profiles, invite BBM contacts to download your app, initiate BBM chats and share content from within your app, and stream data between apps.

Since: BlackBerry 10.0.0

Calendar

access_pimdomain_calendars

Access the calendar on the device. This access includes viewing, adding, and deleting calendar appointments.

Since: BlackBerry 10.0.0

Camera

use_camera

Access data that's received from the cameras on the device. With this permission, your app can take pictures, record videos, and use the flash.

Since: BlackBerry 10.0.0

Capture Screen

use_camera_desktop

Take a screen shot or video of any information visible on the screen of the device. This permission also allows the app to share the user's screen.

Since: BlackBerry 10.2.0

Contacts

access_pimdomain_contacts

Access the contacts that are stored on the device. This access includes viewing, creating, and deleting contacts.

Since: BlackBerry 10.0.0

Control Notification Settings

access_notify_settings_control

Modify global notification settings. Apps only have permission to read their own notification settings.

This permission is not available as a check box on the Application tab of the bar-descriptor.xml file.

Since BlackBerry 10.2.0

Device Identifying Information

read_device_identifying_ information

Access unique device identifiers, such as the PIN or the serial number. This permission also allows you to access SIM card information on the device.

Since: BlackBerry 10.1.0

Email and PIN Messages

access_pimdomain_messages

Access the email and PIN messages that are stored on the device. This access includes viewing, creating, sending, and deleting messages.

Since: BlackBerry 10.0.0

Gamepad

use_gamepad

Access gamepad functionality. This permission also indicates that the app has official gamepad support in the BlackBerry World storefront.

Since: BlackBerry 10.0.0

GPS Location

read_geolocation

Read the current GPS location of the device.

This permission is deprecated. Use the access_location_services permission instead.

This permission is not available as a check box on the Application tab of the bar-descriptor.xml file.

Deprecated: BlackBerry 10.2.0

Hub Accounts

_sys__manage_pimdomain_ external_accounts

Create a custom account that’s accessible in the BlackBerry Hub. BlackBerry must allow your developer account to sign your app to use this restricted permission. To use this permission, complete the App Permissions Request form.

This permission is not available as a check box on the Application tab of the bar-descriptor.xml file.

Since: BlackBerry 10.2.0

Hub Integration

_sys_access_pim_unified

Integrate with the BlackBerry Hub. With this permission, your app can create and manage data in the BlackBerry Hub. BlackBerry must allow your developer account to sign your app to use this restricted permission. To use this permission, complete the App Permissions Request form.

For the best user experience, you should integrate with the BlackBerry Hub in a headless app, preferably integrated with the Push Service. This approach ensures that incoming data is updated in the BlackBerry Hub, even when your app is not running, with minimal impact on battery life.

For more information, see /native/documentation/cascades/device_platform/headless_apps/index.html and /native/documentation/cascades/device_comm/push/index.html.

This permission is not available as a check box on the Application tab of the bar-descriptor.xml file.

Since: BlackBerry 10.2.0

Internet

access_internet

Use the Internet connection from a Wi-Fi, wired, or other type of connection to access locations that are not local on the device.

Since: BlackBerry 10.0.0

Location

access_location_services

Access the current location of the device, as well as locations that the user has saved.

Since: BlackBerry 10.0.0

Microphone

record_audio

Access the audio stream from the microphone on the device.

Since: BlackBerry 10.0.0

My Contact Info

read_personally_identifiable_ information

Access user information on the device, such as the first name, last name, and BlackBerry ID username of the user currently associated with this device.

Since: BlackBerry 10.0.0

Narrow Swipe Up

narrow_landscape_exit

Reduce the width of the region along the bottom bezel of the device that accepts swipe-up gestures. When you use this permission, swipe-up gestures are recognized in a more narrow area along the bottom bezel.

This behavior allows apps that run in landscape orientation, such as games, to use corner regions for menus and virtual gamepads and prevents the game from inadvertently being sent to the background.

This permission is not available as a check box on the Application tab of the bar-descriptor.xml file.

Since: BlackBerry 10.0.0

Notebooks

access_pimdomain_notebooks

Access the content that's stored in notebooks on the device. This access includes adding entries to, and deleting entries from, the notebooks.

Since: BlackBerry 10.0.0

Phone

access_phone

Access phone features on the device. This access includes requesting the dial pad, initiating a call, and requesting information about calls and lines.

Since: BlackBerry 10.0.0

Phone Control

control_phone

Control the current call. This access includes ending a call and sending DTMF tones to the phone.

Since: BlackBerry 10.2.0

Post Notifications

post_notification

Post notifications to the notification area of the device screen. This permission does not require the user to grant your app access.

Since: BlackBerry 10.0.0

Push

_sys_use_consumer_push

Access the Push Service with the BlackBerry Internet Service. This access allows an app to receive and request push messages.

To use the Push Service with the BlackBerry Internet Service, you must register with BlackBerry. When you register, you receive a confirmation email message that contains information that your app needs to receive and request push messages. For more information about registering, visit the Push Service documentation.

If you're using the Push Service with a BlackBerry Enterprise Server or the BlackBerry Device Software, you don't need to register with BlackBerry and you must not specify the Push permission for your app.

Since: BlackBerry 10.0.0

Run as Active Frame

run_when_backgrounded

Perform background processing. Without this permission, your app stops all processing when the user switches focus to another app.

You should use this permission sparingly and only when your app must perform processing in the background. Apps that use this permission are rigorously reviewed for acceptance to the BlackBerry World storefront for their use of device battery power.

This permission is useful for apps that play music or manage downloads.

Since: BlackBerry 10.0.0

Run in Background

_sys_run_headless

Perform certain tasks in the background, without opening the app, for a short period of time.

Due to the potential for misuse of the functionality associated with this permission, apps that use this permission are rigorously reviewed for acceptance to the BlackBerry World storefront.

This permission is not available as a check box on the Application tab of the bar-descriptor.xml file.

Since: BlackBerry 10.2.0

Run in Background continuously

_sys_headless_nostop

Run in the background at all times. You must request access before your app can run as a long-running headless app. To use this permission, complete the App Permissions Request form.

Due to the potential for misuse of the functionality associated with this permission, apps that use this permission are rigorously reviewed for acceptance to the BlackBerry World storefront.

This permission does not appear on the Application tab in the IDE. You must add the permission manually on the Source tab.

Since: BlackBerry 10.2.0

Shared Files

access_shared

Read and write files that are shared between all apps on the device. With this permission, your app can access pictures, music, documents, and other files that are stored on the user's device, at a remote storage provider, or on a media card.

Since: BlackBerry 10.0.0

Text Messages

access_sms_mms

Access the text messages that are stored on the device. This access includes viewing, creating, sending, and deleting text messages.

Since: BlackBerry 10.0.0

Wi-Fi Connection

access_wifi_public

Receive Wi-Fi event notifications such as Wi-Fi scan results or changes in the Wi-Fi connection state.

This permission also allows limited Wi-Fi control for hotspot aggregator applications that manage network selection and authentication to a Wi-Fi Hotspot.

This permission doesn't allow the app to force a connection to a specific network profile when there are other available networks that have a higher priority configured on the device. It's not necessary to configure this permission if you only want to retrieve or query information about existing Wi-Fi connections.

This permission is not available as a check box on the Application tab of the bar-descriptor.xml file.

Since: BlackBerry 10.2.0

Last modified: 2014-01-23

comments powered by Disqus