Proactive and notification-driven

Proactive and notification-driven applications are fundamental to the BlackBerry® experience. Much of the success of BlackBerry devices was built upon the core BlackBerry applications with these qualities.

Consider the Messages application on the device. A distinguishing feature of this application is not just that you can receive email anywhere, but that the content of the email is delivered to the device as soon as it is available, with no user intervention. A user doesn’t need to pull a message down from the messaging server to read it. When the server receives an email message for a user, the server proactively “pushes” that message to the user’s device. The Messages application listens in the background for messages to arrive and, upon receiving a new message, displays a notification icon at the top of the screen.

The push model is largely responsible for helping to make BlackBerry devices so invaluable to their users. This same model can be applied to any application by using the BlackBerry® Push Service, which allows content developers to submit requests to push up to 8 KB of content to one or more BlackBerry devices.

Being proactive—getting information to the user as soon as it is avaliable and without the user requesting it—can take your app from common to uncommonly useful, from app to Super App.

What are the benefits of a proactive and notification-driven application?

  • Use more efficient strategies than polling. Polling techniques waste battery power, since these techniques are designed to regularly open a connection to check for new data, even when there is no new data available. With push technology, an application listens on a specified port number in the background for incoming push content. A network connection is only opened when new push content is available.
  • Bring information directly to the user's attention. Once an app is registered to receive push content, the user does not need to do anything to transfer the content to the BlackBerry device. The app simply receives the content from the server, and only needs to notify the user when the content is available on the device.
  • Deliver content in a timely manner. With push technology, content can be sent as soon as it is available. Typically, there is very little lag between the push content arriving at the server and being delivered to the device.

Approaches to notification

To notify a BlackBerry® device user of an event, you can choose from a number of notification types. Some of these notifications are discreet, noticed only when the user is looking for them, and others are more overt. You can issue multiple notifications for a single event.

The discoverability of the notification type, or types, should match the importance of the event to the user. For urgent events, you may want to issue an audio notification or a vibration that immediately attracts the user's attention. For less important events, you can use more discreet notification types. Regularly occurring events, for example, in an app in which sports scores are pushed overnight, require only subtle notification—or no notification at all—since the user has an expectation that the content will arrive around the same time each day.



Display a banner indicator.

When a new message is pushed to the device, a small icon is displayed in the Home screen banner. You can customize the image so that it is specific to your application.

Flash the LED indicator.

When the daily sports scores are pushed to the device, the BlackBerry device LED flashes. You can customize the behavior of the LED notification. For example, you can configure the LED to flash a yellow light when the event occurs.

Play a sound.

When a new text message arrives, a sound is played. You can use any of the default sounds that are available on the device, or provide your own custom sounds.

Vibrate the BlackBerry device.

When a stock you are monitoring reaches a specified value, the BlackBerry device vibrates.

Send an email or text message.

When an update to an application is available, the application sends a message to the Messages application. As a best practice, if you send a message as a notification, you should also display a custom banner indicator, so that the user can see what type of message has arrived.

Display a popup dialog box.

When a critical event occurs, the application displays a popup dialog box. The user must actively dismiss the dialog box. Because a popup dialog box is a UI element, it is not appropriate for background notifications.

Display an alternate Home screen icon.

When new push content is available for an application, the application icon on the Home screen changes to an alternate image.

Understanding the BlackBerry Push Service

Before getting into the specifics of creating a push solution, it is helpful to understand the features and architecture of the BlackBerry® Push Service. The BlackBerry Push Service provides developers with access to the push technology upon which much of the success of BlackBerry devices is built.

A push solution is made up of three main components:



Push Proxy Gateway (PPG)

The PPG is the middleware, specifically a push data server, within the BlackBerry® Infrastructure. The PPG is the main functional component of the BlackBerry Push Service, and is responsible for receiving push requests from a Push Initiator and delivering the content to the appropriate port on the BlackBerry device.

Push Initiator

The Push Initiator is the server-side application. A Push Initiator takes the content that is to be pushed to users, packages it in a push request with a PAP control entity (an XML document that contains the recipient addresses and defines delivery parameters such as an expiry time or reliability level), and submits that push request to the PPG for delivery. In our scenario, the Bookshelf web service plays the role of the Push Initiator.

Extending the Bookshelf web service to function as a Push Initiator is beyond the scope of this guide. However, Research In Motion has provided the BlackBerry® Push Service SDK to help simplify the process of creating and submitting push messages.

Push-enabled app

The push-enabled app is the client-side application that is installed on the BlackBerry device. A push-enabled app is an application that is designed to listen on a specific port and receive incoming content that has been pushed to this port on the device. In our scenario, we’ll be extending the Bookshelf app to become a push-enabled app.

Be aware that to create a push solution, you must first register your solution with the BlackBerry Push Service. When you register, you will receive an Application ID for your push solution, which is used to associate your Push Initiator with your push-enabled application.

Find out more

For more information about pushing content, visit the following resources:

Making Bookshelf a push-enabled application

To listen for and receive push content, a push-enabled application must:

  • Implement the MessageListener interface
  • Create and send a subscription message, to inform the Push Initiator and the BlackBerry® Push Service that the application is present on the BlackBerry device, and is a valid address for push content sent from this Push Initiator
  • Issue a notification to the user when new content arrives

In addition, to ensure that the application is always ready to receive push content while the BlackBerry device is on, we'll need to create an alternate entry point for Bookshelf. This entry point runs a background process automatically when the BlackBerry device turns on but does not display the UI, allowing Bookshelf to receive and process push content as it arrives. See the Always on chapter for more information on setting up an alternate entry point.

Implement the MessageListener interface

  1. Import the required classes and interfaces.
  2. Define a class that implements the MessageListener interface.
    public class MyMessageListener implements MessageListener {
  3. Implement onMessage().
        public void onMessage(Destination dest, Message incomingMessage) {
  4. Initialize a String variable (in this sample, called payload) to hold the response data.
            String payload = null;
  5. If the response is a ByteMessage object, retrieve the response as a String and assign it to payload.
            if (incomingMessage instanceof ByteMessage) 
                ByteMessage reply = (ByteMessage) incomingMessage; 
                payload = (String) reply.getStringPayload(); 
  6. If the response is a StreamMessage object, retrieve the response as an InputStream object.
            else if(incomingMessage instanceof StreamMessage)
                StreamMessage reply = (StreamMessage) incomingMessage; 
                InputStream is = reply.getStreamPayload();
    1. If the response is small, convert the contents of the stream into a byte array.
                  byte[] data = null; 
                      data =; 
                  catch (IOException e) 
                      // process the error 
    2. If the conversion was successful, convert the byte array to a String and assign it to payload.
                  if(data != null) 
                      payload = new String(data); 
  7. If payload contains data, issue a notification to alert the BlackBerry® device user about the newly arrived content.
                updateIndicator( 1 );
  8. Implement onMessageCancelled() and onMessageFailed().

Subscribe to the Push Initiator

  1. Import the required classes and interfaces.
  2. Initialize a NonBlockingReceiverDestination variable to manage the subscription.
    NonBlockingReceiverDestination nbrd = null;
  3. Create a MessageListener object to process incoming push content.
        MyMessageListener pushListener = new MyMessageListener();
  4. Create a URI object that specifies the port number that the application listens on.
    URI pushURI = URI.create("http://:101");
  5. Create an InboundDestinationConfiguration object to set parameters for the push subscription.
        InboundDestinationConfiguration config = InboundDestinationConfigurationFactory.createBPSConfiguration
            (false, // don't start this application when a push message arrives
            false, // allow other applications to receive these push messages
            false, // do not store these messages (persistence not supported)
            "12-Ab234cD5eF67h890", // application ID,
            BPSuri); // BlackBerry Push Service URI
  6. Create a NonBlockingReceiverDestination object that specifies the InboundDestinationConfiguration object that defines the parameters for the push subscription, the port number on which the app listens, and the MessageListener object responsible for receiving and processing the incoming push content.
            nbrd = DestinationFactory.createNonBlockingReceiverDestination
                        (config, pushURI, pushListener);
  7. Create a NonBlockingSenderDestination object to send a subscription message.
            NonBlockingSenderDestination bpsDestination =
                        (myContext, uri, responseListener);
  8. Build the subscription message.
            ByteMessage subMsg =
                        (bpsDestination, nbrd, "user", "pwd");
  9. Send the subscription message.

Update the banner indicator

  1. Import the required classes and interfaces.
    import net.rim.blackberry.api.messagelist.*;
    import net.rim.device.api.system.EncodedImage;
  2. Obtain a reference to an ApplicationIndicatorRegistry object.
    ApplicationIndicatorRegistry reg = ApplicationIndicatorRegistry.getInstance();
  3. Create an indicator based on an encoded image by invoking EncodedImage.getEncodedImageResource() and passing in the file name as an argument. Save a reference to the encoded image in an EncodedImage variable. Create an instance of the ApplicationIcon class using the EncodedImage as an argument.
    EncodedImage image = EncodedImage.getEncodedImageResource("BookShelf-Icon-notification-32x32.png" );
    ApplicationIcon icon = new ApplicationIcon( image );
  4. Register the image as an application indicator by invoking ApplicationIndicatorRegistry.register(). In the following code sample, the second parameter specifies that the indicator can have a numeric value associated with it (for example, new message count). The third parameter specifies that the indicator should be visible.
    ApplicationIndicator indicator = reg.register( icon, true, true);
  5. Retrieve the registered indicator by invoking ApplicationIndicatorRegistry.getApplicationIndicator(). Save the return value in an ApplicationIndicator variable.
    ApplicationIndicator appIndicator = reg.getApplicationIndicator();
  6. Set the image and value for the indicator by invoking ApplicationIndicator.set(). You should consider only showing a value if it is greater than 0.
    appIndicator.set( newIcon, newValue );
Next topic: Efficient
Previous topic: Finding a book

Was this information helpful? Send us your comments.