Providing an integrated experience

Making the most of the available features on the device is key to providing an integrated experience for your users. Cascades offers a number of features that you can use to create an integrated app, including app invocation, personal information management (PIM), location, and sensors.

App integration

The invocation framework and cards let you access the features and functions of other apps directly from your own app. The information below outlines how you can use the invocation framework and cards in your app.

Invocation framework

The invocation framework allows you to invoke the functionality of another app from the UI of your app. The benefit of the invocation framework is that it doesn't interrupt the user experience flow of your app when invoking another app; users can perform a task and quickly return to your app.

An app is eligible to be invoked when it is registered as a target app in the bar-descriptor.xml file, which specifies the type of data the target app can handle. The app making the invocation request is known as the client app, and it sends an invocation request containing the unique ID of the target app, the action that should be performed, and the data that should be acted upon. The invocation framework takes care of starting the target app, and managing the exchange.

For example, you could use the invocation framework to view a PDF file by invoking the Adobe Reader app.


A card allows you to use a single screen, or stack of screens, from another app to perform a specific task. Cascades provides three types of cards:

  • Previewers: Allow you to view existing content
  • Composers: Allow you to create and edit content
  • Pickers: Allow you to choose existing content

When invoked, a card appears on the screen using a smooth transition animation. Previewers slide in from the right side of the screen, while composers and pickers slide in from the bottom of the screen. The image below demonstrates a previewer card being invoked.

A diagram showing how a card transitions.

A card appears as part of the client app, but maintains its own process and security context. This allows you to perform tasks such as picking a contact, composing an email, or previewing an image directly from your app.

For example, you could use a composer card to allow users to quickly create and send an email using pre-populated information.

Personal information management

Personal information management (PIM) refers to the ability to add, change, and delete information that's specific to a particular user on a BlackBerry device. This information can include account and contact information, calendar events, messages, and notebook information.

Cascades offers a set of PIM APIs that allow you to interact with PIM entries directly in your app, and a number of service classes are available to make things easier for you.


The AccountService API allows you to associate users with a particular provider, such as an enterprise service or social networking account. Each account contains a set of supported services, such as contacts and geolocations. You can use these classes to retrieve information about an account and its provider and services.

Screens showing a user adding a new email account.


The CalendarService API lets you add, change, and delete entries (called events) in the calendar database on a device. You can add new events and include related information such as the location, start and end time, and list of attendees. You can also include more detailed information for an event, such as frequency and recurrence information, sensitivity, reminder time, and whether the event is a special type of event (for example, an all-day event or a birthday).

The Calendar app.


The ContactService API lets you add, change, and delete entries in the Contacts app on a device. You can add new contacts and specify information such as email and postal addresses, phone numbers, photos, and so on. You can also specify more detailed information about a contact, such as whether a phone number is a work phone number, home phone number, or mobile phone number.

An entry in the Contacts app.


The MessageService API lets you create and send messages directly from your apps. You can build different types of messages, such as email messages or text messages, and send them to a list of recipients that you specify. Each message can include basic information like a subject, body, and priority, as well as more detailed information (for example, MIME type, follow-up flag status, and attachments). You can also create conversations, which are chat-like interactions that you can choose to display in a special way in your apps (say, by using a chat interface that's similar to BBM.


The NotebookService API lets you add and change entries in the Remember app on a device. This app stores items in list-type structures called notebooks. Each notebook can contain a list of items or tasks called notebook entries. A notebook entry represents a single thought or action that a user might want to track. Users can use the Remember app to track any list-based information they want.

Screens of the remember app.


One of the ways that you can get users hooked on your app is by allowing them to communicate with other users and other types of devices. On BlackBerry 10, you have a number of different options for communication, including BBM integration, telephony, NFC, and Bluetooth.


Creating a BBM connected app is a great way to promote and keep users engaged with your app. You can use BBM in your app to allow users to share information, or invite others to try your app. In addition, if you are looking to create an app that meets the Built for BlackBerry certification, including BBM support is a great way to help meet the necessary criteria.


One of the most important aspects of keeping your users connected is including telephony functionality. You can include telephony support in your app to find and display a phone number, place a call, or interact with an external system using DTMF.


Near Field Communication (NFC) is a short range radio technology that allows NFC-enabled devices to communicate with each other over distances of up to 1.5 cm (5/8 in.).

As you plan your app, consider ways you can include NFC functionality. Common use cases include, but are not limited to:

  • Sharing Bluetooth handover information
  • Sharing a small amount of data between two instances of your app running on separate devices
  • Quickly exchanging contact information


In addition to NFC, you also have the option of using Bluetooth in your app. Bluetooth offers higher transfer speeds and range over NFC, but requires more effort to establish a connection between devices.

In Cascades, you can use a Bluetooth card to share a local file between two devices.


Cascades provides a number of location services you can use in your app, including positioning, geocoding, and mapping information. These services can be used for any number of different types of apps, including weather, device location, and navigation.


The most basic location service is positioning. By using this service, you can find the current location of a device using GPS satellites, cell ID, or Wi-Fi positioning.

Geocoding and reverse geocoding

If you're looking for an address, or need the geospatial positioning of an address, you need the geocoding and reverse geocoding services. Geocoding returns geospatial coordinates for a provided address, while reverse geocoding returns an address for provided coordinates.


When it comes to displaying a location, you have two options. You can display a location within your app by using a MapView, or you can display it within the BlackBerry Maps app.


BlackBerry 10 devices support a range of sensors that you can use to collect data about the device's external environment. If you want to use sensor data in your app, Cascades provides the Sensors API that allows you to access and react to the incoming sensor data. Some of the sensors that are supported are as follows:


The accelerometer reports on changes to the acceleration of the device along three axes. This sensor is useful if your app is designed to handle motion input from a user.

Ambient light sensor

The ambient light sensor is used to measure the amount of light in the current environment. This sensor is useful for conserving battery life, as it can be used to increase and decrease the power of the backlight depending on the lighting conditions.


The compass sensor takes the 3D device orientation and turns it into a 2D device heading (otherwise known as the azimuth). The azimuth is a value in degrees from magnetic north in a clockwise direction.


The gyroscope returns readings that measure the velocity of the device along three axes. The gyroscope's readings represent the current angular velocity rather than a fixed rotation. The measurements are in degrees per second.

What's next?

Look at Keeping your users updated to learn about how the different ways for retrieving external content and presenting it to your users.

Last modified: 2015-03-31

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

comments powered by Disqus