Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Proactive and notification-driven

What makes an app proactive? Let's look at the the Messages application to answer that question. A distinguishing feature of Messages 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. You don't need to manually request a message 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 app by using the Push Service, which allows content developers to submit requests to push up to 8 KB of content to one or more BlackBerry devices.

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

  • 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 app 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.

Approach

Example

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 app.

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 app is available, the app 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 pop-up dialog box.

When a critical event occurs, the app displays a pop-up dialog box. The user must actively dismiss the dialog box. Because a pop-up 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 app, the app icon on the Home screen changes to an alternate image.

Understanding the Push Service

Before getting into the specifics of creating a push solution, it is helpful to understand the features and architecture of the Push Service. The 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:

Component

Description

Push Proxy Gateway (PPG)

The PPG is the main functional component of the 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. The PPG is middleware, specifically a push data server, within the BlackBerry Infrastructure.

Push Initiator

The Push Initiator is the server-side app. 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.

We won't cover extending the Bookshelf web service to function as a Push Initiator in this guide, however, the Push Service SDK can simplify the process of creating and submitting push messages.

Push-enabled app

The push-enabled app is the client-side app that is installed on the BlackBerry device. In our case, this is Bookshelf. A push-enabled app is an app 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 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 app.

Find out more

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

Tutorial: Making an app push-enabled

Imagine you're creating an app called Bookshelf that should notify its users by pushing a notification when a user is geographically near a released book. Apps that push notifications are referred to as push-enabled. We can also have Bookshelf push notifications when someone comments on a book in a user's library, or when a book a user releases is found.

To receive push notifications, an app needs to do the following:

  • Implement the MessageListener interface.
  • Create and send a subscription message, to inform the Push Initiator and the Push Service that the app 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 app 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 page for more information on setting up an alternate entry point.

Implementing the MessageListener interface

Import the required classes and interfaces.

import net.rim.device.api.io.messaging.*; 
import java.io.IOException; 
import java.io.InputStream;

Define a class that implements the MessageListener interface.

public class MyMessageListener implements MessageListener {

Implement onMessage().

    public void onMessage(Destination dest, Message incomingMessage) {

Initialize a String variable (in this sample, called payload) to hold the response data.

        String payload = null;

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(); 
        }

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();

If the response is small, convert the contents of the stream into a byte array.

            byte[] data = null; 
            try 
            { 
                data = net.rim.device.api.io.IOUtilities.streamToBytes(is); 
            } 
            catch (IOException e) 
            { 
                // process the error 
            }

If the conversion was successful, convert the byte array to a String and assign it to payload.

            if(data != null) 
            {
                payload = new String(data); 
            } 
        }

If payload contains data, issue a notification to alert the BlackBerry device user about the newly arrived content.

        if(payload!=null) 
        { 
            updateIndicator( 1 );
        }

Implement onMessageCancelled() and onMessageFailed().

Subscribing to the Push Initiator

Import the required classes and interfaces.

import net.rim.device.api.io.messaging.*;

Initialize a NonBlockingReceiverDestination variable to manage the subscription.

NonBlockingReceiverDestination nbrd = null;

Create a MessageListener object to process incoming push content.

try
{
    MyMessageListener pushListener = new MyMessageListener();

Create a URI object that specifies the port number that the app listens on.

URI pushURI = URI.create("http://:101");

Create an InboundDestinationConfiguration object to set parameters for the push subscription.

    InboundDestinationConfiguration config = InboundDestinationConfigurationFactory.createBPSConfiguration
        (false, // don't start this app when a push message arrives
        false, // allow other apps to receive these push messages
        false, // do not store these messages (persistence not supported)
        "12-Ab234cD5eF67h890", // application ID,
        BPSuri); // BlackBerry Push Service URI

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);

Create a NonBlockingSenderDestination object to send a subscription message.

        NonBlockingSenderDestination bpsDestination =
                    DestinationFactory.createNonBlockingSenderDestination
                    (myContext, uri, responseListener);

Build the subscription message.

        ByteMessage subMsg =
                    BpsSubscriptionMessageBuilder.createByteSubscriptionMessage
                    (bpsDestination, nbrd, "user", "pwd");

Send the subscription message.

        bpsDestination.send();

Updating the banner indicator

Import the required classes and interfaces.

import net.rim.blackberry.api.messagelist.*;
import net.rim.device.api.system.EncodedImage;

Obtain a reference to an ApplicationIndicatorRegistry object.

ApplicationIndicatorRegistry reg = ApplicationIndicatorRegistry.getInstance();

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 );

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);

Retrieve the registered indicator by invoking ApplicationIndicatorRegistry.getApplicationIndicator(). Save the return value in an ApplicationIndicator variable.

ApplicationIndicator appIndicator = reg.getApplicationIndicator();

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 );