Adding and removing app permissions

Some plugins require that specific app permissions be added to the app configuration. In most cases, when you add a plugin that requires a permission, the tools automatically add it for you at build time.

In some cases, a permission is required only for a subset of the APIs contained by a plugin. In these cases, the tools do not add the permission. If you intend to use the restricted APIs within the plugin, you must add the required permission yourself. In addition, you may be required to add app permissions to use some HTML5 APIs, such as HTML5 notifications.

For example, adding the org.apache.cordova.file plugin to your project without specifying any permissions allows you to access only those files within the application sandbox. However, to access other files on the device file system, such as a music file, you must add the access_shared permission. In this case, adding the plugin does not automatically add the permission. Instead, you must add the permission yourself, either using the BlackBerry 10 WebWorks SDK web tool, or by manually adding them to the config.xml file.

Adding permissions using the SDK web tool

To add plugin permissions using the BlackBerry 10 WebWorks SDK web tool:

  1. Open BlackBerry WebWorks <version>. A new browser window opens, displaying the BlackBerry 10 WebWorks SDK web tool.
  2. In the left pane, click <your_project> > Configuration.
  3. In the Permissions section at the bottom of the page, select the permission you want to add to the project from the Permit drop-down list then click Add Permission. For information about the available app permissions, see Available app permissions.

Adding permissions to the config.xml file

The project's root folder contains the config.xml file, which contains the app permissions for the project. You can add a directly to the config.xml file by adding a <rim:permit> element. The config.xml file can contain one or more <rim:permit> elements, all of which must be children of the <rim:permissions> element.

To add a permission to the config.xml file:

  1. Open the config.xml file, in the text editor of your choice.
  2. Locate the <rim:permissions> element. If no <rim:permissions> element exists, add one:
    <rim:permissions>
    </rim:permissions>
  3. Add the app permission by inserting a <rim:permit> element in the <rim:permissions> element. For example, if you want to access a music file on the device file system, you must add the access_shared permission to the file, as follows:
    <rim:permissions>
        <rim:permit>access_shared</rim:permit>
    </rim:permissions>
    Some permissions require the system="true" attribute. For example:
    <rim:permissions>
        <rim:permit system="true">_sys_use_consumer_push</rim:permit>
    </rim:permissions

For information about the available app permissions, see Available app permissions.

Available app permissions

The following table identifies the available WebWorks app permissions, which are required to access specific native functionality or capabilities. Typically the tools automatically add the required permission when the plugin is added. However, if the plugin can function without the permission, and requires a permission only to access certain APIs within the plugin, then the tools do not add the permission. If you intend to use the restricted APIs, you must add the permission yourself.

This list of permissions represents only those app permissions that may be required to use the WebWorks or Cordova plugins that are installed with the BlackBerry 10 WebWorks SDK. Custom plugins that access native functionality may require app permissions that are not listed here. For example, to use a custom plugin that accesses the device's microphone to record audio, you must add the record_audio permission. For a complete list of native app permissions, see Available permissions in the BlackBerry 10 Native SDK documentation.

Functionality or capability Permission value Description
Camera

use_camera

Allows the app to take pictures, record video, and use the camera's flash.

Device information

read_device_identifying_information

Allows the app to access device identifiers such as serial number and PIN.

Location information

access_location_services

Allows the app to access the device’s current or saved locations. This permission replaces read_geolocation, and includes access to location information from GPS, Wi-Fi, and cell ID.

Shared files

access_shared

Allows the app to access pictures, music, documents, and other files stored on the device, at a remote storage provider, on a media card, or in the cloud.

Push

_sys_use_consumer_push

Allows the app to use push functionality.

You must include the system="true" attribute when you add this permission. See <rim:permit> for more information.

Run in background

run_when_backgrounded

Allows the app to run JavaScript and networking in the background.

Your app can run in the background either by including the run_when_backgrounded permission or by adding the com.blackberry.push plugin to your project.

Use this feature sparingly and only when your application must perform processing in the background. Running the app in the background can negatively impact the battery life of the device.

BBM Social Platform

bbm_connect

Allows the app to connect to BBM so that the user can chat or update their BBM profile without leaving the app.

Email and PIN messages

access_pimdomain_messages

Allows the app to access email and PIN messages, including viewing, creating, sending, and deleting messages.

Contacts

access_pimdomain_contacts

Allows the app to access contacts, including viewing, creating, and deleting contacts.

Calendar

access_pimdomain_calendars

Allows the app to access the calendar, including viewing, adding, and deleting appointments.

Notifications

post_notifications

Allows the app to post a notification to the notification area of the screen.

Last modified: 2015-04-16



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus