Let’s Talk About Push

As you may know, Push is now available to almost all BlackBerry® 10 development approaches: Cascades™ Framework, BlackBerry® WebWorks™, Adobe® AIR® and Android™*. That said, I thought it would be a good idea to provide a high-level overview of the entire Push process which is shared across all platforms.

(*Support for Push to Android Runtime applications will be supported in a future BlackBerry 10 release, and support of enterprise Push is available; however, to keep things concise this article will focus on consumer Push in currently-supported platforms only. More details on the others to come in a future blog post.)

I will be focusing on the client-side portion of this service. If you have used Push through the BlackBerry® Internet Service (BIS) in the past, then there is nothing different needed for your server-side code at this time – it will work as-is with BlackBerry 10!

For anyone who does not yet know what Push is, here is a brief overview: If your BlackBerry 10 application works with a server to retrieve data, there are a few ways it can typically know when new data is available:

1. Pull – Request all data all the time
   1. Not efficient (battery and bandwidth-wise)
   2. Info may be available to client well before pull
   3. Client application needs to be running
2. Poke – Message the server and ask if new data is available, pull if available
   1. Info may be available to client well before poke
   2. Client application needs to be running
3. Push – The server sends the client new data as soon as it becomes available
   1. Efficient
   2. Data is immediately available to the client
   3. Client application does not need to be running

Push is the more efficient way of delivering data to the client application; this service is synonymous with the BlackBerry® experience, where it has been used for delivering emails and BlackBerry® Messenger (BBM™) messages since the beginning.

Getting started

If you have not done so already, you can get signed up for a Push Service account on the following site: https://developer.blackberry.com/services/push

Once you have successfully registered, you will receive very important information which will be used for creating your client and server-side applications. Focusing on the client, you will receive an Application ID value which will be unique to your Push application, and you will also receive a PPG (Push Proxy Gateway) URL which will be used by your client to register to begin receiving push data from this particular Application ID. More on these two values later — for now it is important only to know that they are received after registering to use the Push Service.

Invocation Framework

Let’s start with the piece that brings everything together: the Invocation Framework. Invocations are an incredibly powerful tool used throughout BlackBerry 10. In the case of Push, this is how the target application will receive the pushed data whether it is running or closed. With that in mind, the first thing we need to do is register our application to receive invocation requests when a Push is received. To do that, we add an invoke-target element to the application’s bar-descriptor.xml* file:

<invoke-target id="unique.text.value">
<entry-point>1</entry-point>
<type>APPLICATION</type>
<filter>
<action>bb.action.PUSH</action>
<mime-type>application/vnd.push</mime-type>
</filter>
</invoke-target>

The important elements in bold above:

1. id – This value is chosen by you. It is a unique identifier used to invoke your application specifically. It is important to choose a value that is not likely to be used by other applications.
   
2. action – The "bb.action.PUSH" value denotes that this invoke-target can handle data pushes.
   
3. mime-type – The MIME type used by pushed data is "application/vnd.push", so this element states that this invoke target can handle the push data MIME type.

Numbers 2 and 3 above cannot be changed, but it is important to understand what they represent.

Once your application has been installed with the invoke-target element in the bar-descriptor, it is now ready to be invoked with Push data. The invocation happens the same way as a non-Push invocation; the only difference is that the data provided in the invocation will include a PushPayload object containing the contents of your pushed data. Before the OS knows to invoke this application, however, there are a few things that need to be taken care of, beginning with the Push Notification Service.

*If developing using BlackBerry WebWorks / HTML 5 then you would modify the config.xml file. The XML would be almost identical to what is stated above except that <invoke-target id=”unique.text.value”> would become <rim:invoke-target id=”unique.text.value”> and </invoke-target> would become </rim:invoke-target>

Push Notification Service (PNS)

The PNS is always running on BlackBerry 10. This service handles the mapping between the unique Application ID (received after registering for the Push Service) and the Invoke-Target (specified above in the bar-descriptor.xml file). When your application first launches, it should always create a PushService session instance. This instance takes 2 primary values as parameters: the Invoke Target and the Application ID. After this has been successfully created, the PNS now has a mapping between the Application ID and the Invoke Target.

To take a quick scenario-based example, when a Push comes in to the device from the BlackBerry Push Service, it will always include an Application ID. PNS will receive this Push and read the Application ID. It will then check its records to see what invoke-target has been registered against this Application ID, and then invoke your application based on this mapping.

Note: If you used Push in BlackBerry® 7.1 OS and lower then you may be wondering about ports; in BlackBerry 10 PNS abstracts the port logic for you, so all you need to worry about is the Application ID. PNS guarantees there will not be a port conflict on your behalf.

Registering with the Push Service

If you have gotten this far, then everything is ready to go on the device side. However, your client application still needs to register with the Push Service to allow pushes for the specified Application ID to be delivered to your device. The process of registering with BPS is known as creating a "channel". This tells BPS that the device has the required application installed and that it would like to start receiving pushed data. This helps to prevent unsolicited pushed data from being sent to your device. Channels are fairly static — they persist through device resets, so you should only need to create one for the lifetime of the application install. There is a chance that the channel may get deleted by the server, so the recommendation would be to create a channel once every 30 days or less.

Channel creation is handled by the same PushService session instance mentioned in the PNS section above. The same call that creates the channel returns a "token" object; at this time, the token is a string representation of the device PIN. This can be sent off to your server-side application to let it know that there is a new device that would like to begin receiving pushed data. This is not handled by the framework as server-side implementations will vary. The sample applications do show how to perform this registration if using the server-side sample included with the Push Service SDK.

Handling the Push Invocation when the client app is closed

Once again relying on our PushService instance, there is a method that can be called which will allow the application to launch in the background when a Push arrives.

BlackBerry WebWorks / HTML 5 – launchApplicationOnPush
Cascades – registerToLaunch
Adobe AIR – registerToLaunch

If this is set to true, then the application will launch as soon as a Push is received and run in a minimized state. Should the user be in another application at the time, they will not be interrupted by this process — it is transparent. The client app can then process the Push as needed and possibly use the Notification APIs to let the user know new data is available to be viewed.

Summary/Conclusion/Where to go next

Well, there you have it — a generalist overview of Push across the board on BlackBerry 10. If you would like to add the power of Push to your application then I would recommend a few next steps:

1. Register to evaluate the Push Service. This provides a means to test out the Push Service in a live environment. This can be tested today on BlackBerry 10 Dev Alpha devices (simulators are not currently supported).
   
2. Check out the sample for the platform you wish to target. All samples provide the same UI and functionality, so it’s a matter of what you are familiar with:

Cascades
BlackBerry WebWorks / HTML 5
Adobe AIR

If you would like more information on Push, please take a look at the following resources:

• JAM48 – Leveraging BlackBerry Services: Push and Notification Manager
• Developer Support Forums
• BlackBerry Developer Portal