Push has always been a major part of BlackBerry as an extremely efficient way of providing real-time data to users without needing to keep your app running at all times. The main components of Push from BlackBerry 7 to BlackBerry 10 have remained largely unchanged, with applications needing to:

1. Register to receive push messages with the device
2. Register with the BlackBerry Push Service in the cloud to allow push messages for the app to begin being delivered
3. Register with your server side app so it knows there’s a new subscriber
4. Be ready to receive push messages at any time
5. Process pushes in a quick and efficient manner

The server-side portion of consumer push is identical between all BlackBerry smartphone versions, meaning you can use your current server-side app and push service credentials.

By włodi from London, UK (The Big Red Button Uploaded by Yarl) [CC-BY-SA-2.0 (http://creativecommons.org/licenses/by-sa/2.0)%5D, via Wikimedia Commons

BlackBerry 7

In BlackBerry 7 Java, there were two main ways to set up your application to receive push messages – open a port and begin listening indefinitely or register your port and application details with the device. The former basically required that your application begin a background process when the app was first installed, as well as every time the device started up. When the push arrived on the port opened by the app, the data could then be processed however required by the app, followed by the app once again listening on the open port for the next message. This method also required the app to perform “manual” registration, an HTTP POST, with the BlackBerry Push Service to allow devices to begin receiving push messages for your app.

https://github.com/blackberry/JDE-Samples/tree/master/com/rim/samples/device/httppushdemo (this sample shows Enterprise Push which is similar to the pre-5.0 Push API method through BIS)

The latter approach was introduced in BlackBerry 5 where new APIs were introduced that removed the need to keep an app thread running at all times. Instead, the app would register itself with the device by passing it the assigned port and push app ID, allowing the device to listen for push messages on behalf of the app and launch to pass the push message to be processed. This method provided a simple way to allow the app to perform the registration with the BlackBerry Push Service.

http://www.blackberry.com/developers/docs/7.0.0api/net/rim/blackberry/api/push/package-frame.html

BlackBerry 10

The approach used in BlackBerry 10 is most similar to the last approach mentioned for BlackBerry 7 and is arguably the simplest way to handle push messages yet. One simplification is that developers no longer need to worry about application ports, as the on-device service will now handle port selection directly with the BlackBerry Push Service. Another is that rather than needing to deal with reading network streams to receive the push payload, it is not delivered directly to the app fully available in the data portion of an invocation.

Application flow

The first thing your app will need is an entry in the bar-descriptor.xml file that registers the app to receive invocations from the device push notification service. Below is an example entry. The only thing you need to change is the invoke-target id value to a string unique to your app:

              <invoke-target id="com.unique.string.for.your.app">	
      <type>APPLICATION</type>
      <filter>
         <action>bb.action.PUSH</action>
         <mime-type>application/vnd.push</mime-type>
      </filter>
    </invoke-target>

The second thing to add to the bar-descriptor is the permission for consumer push (this can also be added through the GUI editor in the IDE):

<permission system=”true”>_sys_use_consumer_push</permission>

After the above entries exist, we are ready to start programming. Using the various Push APIs, the following flow needs to occur in the device app:

Create a Session

Frequency: Every time your app launches

This is where your app registers itself to receive push messages. Once your app passes the on-device service, it’s provided a push app ID as well as the invoke-target ID you specified in the bar-descriptor file. This basically tells the service, “If a push comes in with this push app ID, invoke my app using this invoke-target ID”.

PushService* m_pushService; //Member variable creation in header file

//In this case BLACKBERRY_INVOKE_TARGET_ID would be “com.unique.string.for.your.app” from above

m_pushService = new PushService(BLACKBERRY_PUSH_APPLICATION_ID, BLACKBERRY_INVOKE_TARGET_ID);
m_pushService->createSession();

Create a Channel

Frequency: Once for the lifetime of the app

After the session has been established on the device, the app then needs to register itself with the BlackBerry Push Service. This operation is referred to as “creating a channel”. The creation of a channel tells the BlackBerry Push Service, “If a push message arrives with this app ID and is addressed to my device, please let it through”. Without this step, pushes will never be delivered to the device.

m_pushService->createChannel(QUrl(BLACKBERRY_PUSH_URL));

Another important part of this step is that when the channel is created, it should return a “token” which currently is simply the value of the device PIN. This can be sent to your server once retrieved to let it know that a new device has subscribed.

Register to Launch

Frequency: Once for the lifetime of the app

Following the channel creation, your last step is to call the “register to launch” function. Unlike BlackBerry 7, BlackBerry 10 apps do not run all the time. When a push arrives however, the application can be launched into the tiled state to perform processing on the push it’s not already running. In order to be launched when a push arrives, the app must call the “register to launch” function. Otherwise if this function is not called and the application is closed, the push data will be lost.

m_pushService->registerToLaunch();

Once the above steps are completed, your app is ready to start receiving push messages. As push uses invocation, you can handle the messages in about the same way you would for a standard invocation of your app:
https://developer.blackberry.com/cascades/documentation/device_platform/
invocation/receiving_invocation.html

The one difference is that you need to use the PushPayload class to retrieve the push payload from the InvokeRequest’s data:
https://developer.blackberry.com/cascades/documentation/device_comm/push/
cs_receiving_a_push_message.html

Ready to get porting your BlackBerry Java push app over to BlackBerry 10? Here’s a great resource that walks through the entire service including lots of code snippets:
https://developer.blackberry.com/cascades/documentation/device_comm/push/index.html

Need a sample to test your current push credentials? Check our GitHub repositories:
https://github.com/blackberry/Cascades-Samples
https://github.com/blackberry/Cascades-Community-Samples

Never used Push before? Check out this overview of the service:
https://developer.blackberry.com/services/push/?CPID=PUSHAPI00

If you still have questions toss a post in the Push Development forums or send me a tweet:
http://supportforums.blackberry.com/t5/BlackBerry-Push-Development/bd-p/Applications_using_Push_Technology

@garettBeuk