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
a. Not efficient (battery and bandwidth-wise)
b. Info may be available to client well before pull
c. Client application needs to be running2) Poke – Message the server and ask if new data is available, pull if available
a. Info may be available to client well before poke
b. Client application needs to be running3) Push – The server sends the client new data as soon as it becomes available
a. Efficient
b. Data is immediately available to the client
c. 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

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:

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.

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:CascadesBlackBerry WebWorks / HTML 5Adobe AIR

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

Last week, we saw the BlackBerry® Application Platform take a major step forward. We’ve posted several key announcements made at BlackBerry DEVCON Asia, and we’re already receiving tremendous feedback from the developer community. To recap:

BlackBerry® Tablet OS announcements

With the release of the beta version of the BlackBerry® WebWorks™ SDK, developers can now build BlackBerry® WebWorks™ applications for both the BlackBerry® PlayBook™ tablet and BlackBerry® smartphone platforms!

Developers can now fully test in-app payments with the BlackBerry Payment Service, with the release of the BlackBerry App World™ v2.1 client now available for beta testing.

With the release of an updated BlackBerry® Push Service SDK, it has never been easier to develop push applications for the BlackBerry platform.

With these announcements we’d like to open the door further, talk about where we are today – and what’s to come.

The BlackBerry Tablet OS will support Adobe AIR and BlackBerry WebWorks apps when the BlackBerry PlayBook tablet launches. Stay tuned for updates regarding support for Java® and Native C/C++ apps.

Last week at DEVCON Asia, we provided updates on several enhancements to the BlackBerry smartphone platform. We previewed what’s coming soon with the BlackBerry® 6.1 platform, including OpenGL®-ES2.0, Support for Digital Compass (enabling augmented reality), new location and user interface APIs. We also provided an update on the highly anticipated BBM™ Social Platform, confirming BETA SDK availability in Q1 of this year.

We couldn’t be more excited about our direction!

Today’s BlackBerry WebWorks offering is a sign of what’s to come with the BlackBerry platform. We are fully embracing modern Internet technologies including HTML5, JavaScript®, Adobe® Flash® and AIR, Java and OpenGL as platforms for content services and powerful applications. With the Adobe AIR and BlackBerry WebWorks platforms, we are immediately opening up the BlackBerry PlayBook tablet to millions of web, Flash and mobile app developers who can also leverage our application distribution channels and BlackBerry Payment Service. With Java, Native C/C++ and OpenGL coming to BlackBerry Tablet OS in the future, we have an exciting vision for a mobile platform that offers the broadest choice and greatest flexibility to developers.

We hope you join in our enthusiasm and excitement for the future of mobile computing. As always, we look forward to hearing your feedback and we’ll provide further updates on both our smartphone and Tablet OS platforms soon!