App permissions
You can access restricted functionality on the device by setting app permissions.
BlackBerry 10 devices can capture rich information from their environment, via the GPS receiver, a microphone, and so on. To help protect against potentially malicious code, users must grant your application access to the functionality. If your app uses APIs that access restricted functionality, without first requesting permission to access the device, the APIs return errors. For example, if you attempt to access a file in a shared folder without the access_shared permission, you get a "permission denied" error on open. Your app must handle these errors gracefully.
You must specify each device permission your application requires with a separate <permission> element in the project's BAR application descriptor file.
The following table describes <permission> element values that are available:
| Feature | Permission element values | Description |
|---|---|---|
| Background processing | run_when_backgrounded | Perform background processing. Without this permission, your app will be stopped when the user switches focus to another app. Use this permission sparingly and only when your app must perform processing in the background. This permission is useful for apps that play music or manage downloads. Apps that use this permission are rigorously reviewed for acceptance to BlackBerry World storefront for their use of power (device battery) |
| BlackBerry Messenger | bbm_connect | Connect to the BlackBerry Messenger (BBM) and access to 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 in real time |
| Calendar | access_pimdomain_calendars | Access the calendar on the device. This access includes viewing, adding, and deleting calendar appointments |
| Camera | use_camera | Access any of the data coming from cameras on the device. This access allows an app to take pictures, record video, and use the flash. |
| Contacts | access_pimdomain_contacts | Access the contacts stored on the device. This access includes viewing, creating, and deleting contacts |
| Device Identifying Information | read_device_identifying_information | Access unique device identifiers such as the PIN and serial number. This access also allows you to access SIM card information on the device |
| Email and PIN Messages | access_pimdomain_messages | Access the email and PIN messages stored on the device. This access includes viewing, creating, sending, and deleting messages |
| GPS Location | read_geolocation | Access the current GPS location of the device |
| Internet | access_internet | Use internet connection from a Wi-Fi, wired, or another connection to a destination that is not local on the user's device |
| Location | access_location_services | Access the current and saved locations on the user's device |
| Microphone | record_audio | Access the audio stream from the microphone on the device |
| Narrow swipe up | narrow_landscape_exit | Reduce the region of the home swipe up gesture to occur only in the middle edge of the bottom of the bezel instead of a full-length swipe. This access allows apps in a landscape orientation, such as games, to use corner regions for menus and virtual gamepads and prevents the game from inadvertently going into the background |
| Notebooks | access_pimdomain_notebooks | Access the content stored in the notebooks on the device. This access includes adding and deleting entries and content from the notebook. |
| Notifications | post_notification | Post a notification to the notification area of the screen |
| Phone | access_phone | Determine when a user is on a phone call. This access includes access to the phone number assigned to the device and the BlackBerry ID of the user |
| Push | _sys_use_consumer_push | Access to use 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 Research In Motion. When you register, you receive a confirmation email message that contains information that your application needs to receive and request push messages. For more information about registering, visit https:// developer.blackberry.com/services/push/. If you're using the Push Service with the BlackBerry Enterprise Server or the BlackBerry Device Service, you don't need to register with RIM. |
| Shared Files | access_shared | Read and write files that are shared between all applications. This allows your app to access pictures, music, documents and other files stored on the user's device, at a remote storage provider, on a media card, or in the cloud |
| Text Messages | access_sms_mms | Access the text messages stored on the device. This access includes viewing, creating, sending, and deleting text messages |
Permission settings can cause some unexpected behavior in your application. For
example:
- If you don't set the use_camera permission, then each time a user attempts to open the camera, the user will be prompted to allow access.
- If you don't specify the record_audio setting, the user will be prompted when the application tries to use the microphone.
- For the access_shared and use_camera settings, if the permission isn't specified, the user isn't prompted and the feature doesn't work.