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 running
2) 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 running
3) 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

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

Hopefully you aren’t getting tired of me yet, and I’m sure you are not tired of the updates to the BlackBerry® WebWorks™ SDK. We’ve just posted a new release, and it squarely falls in the high-value realm. While incremental, it empowers a significant feature of the BlackBerry WebWorks platform: custom API extensions. That’s right, like previous BlackBerry WebWorks platforms, you can now write your own extensions to enable native capabilities not yet exposed by the pre-packaged BlackBerry WebWorks APIs!

First, let’s quickly mention the other major item in this release: Now, when you build your application, you can pass a configuration file to bbwp.exe – the main command line tool for BlackBerry WebWorks – which will pass parameters on to the other downstream command line tools that bbwp.exe leverages. bbwp.exe is your main command line tool to create your applications for BlackBerry WebWorks: it will give you your .BAR file and even sign it for you. However, under the covers, it uses a couple of other command line tools that are part of the BlackBerry tool chain to perform these actions such as creating the .BAR and signing it. These other tools sometimes have parameters that are not exposed by bbwp.exe. With this release, we have provided a parameter (-p or –param) on bbwp.exe to provide a file on the bbwp.exe command line that you can use to pass on to the downstream tools any additional parameters you choose. It is a simple json structure that you can mark up. The main use case we hear quite often is providing the signing tool with proxy settings. Check out the params-example.json file in the root of your BlackBerry® 10 WebWorks SDK installation for an example. It contains the framework for providing parameters to the other two tools, the native packager that creates the .BAR, and the signing tool which signs the .BAR.

OK, now back to custom extensions. As a quick recap, BlackBerry WebWorks APIs are conceptually comprised of two different things: an API or service in the native platform, and a JavaScript® front-end to this native service. All of the APIs that are part of the official BlackBerry WebWorks SDK take advantage of this architecture and a system called jNext. jNext is what binds the JavaScript layer to the native layer. You can now build your own API extensions in exactly the same way we do.

To get started, you will first need to download our BlackBerry 10 Native SDK and configure it. This will give you access to all that the native environment offers. Go do that now and come back here for the next step.

All right, you’re back. Next step is to visit our GitHub Community API repo and download the sample BlackBerry 10 Native SDK project we have provided. This sample project is a working example of an extension that monitors memory usage on the device. Everything you need to create your own extension is modeled here. A full walk-through of the project and its components can be found in the README associated with the project in the GitHub repository, so check that out next, and get working on your extension.

Once you are done, I highly recommend that you check out our Community API repository, and seriously consider contributing your extension to the repository so that others can take advantage of your awesome work. To contribute the extension you will need to apply the ASL 2.0 license, and complete a few other administrative things, but then the whole BlackBerry WebWorks community can benefit.

One thing to bear in mind with your extension: we really didn’t want to hold back on releasing this feature to our community, but we do know that one thing will change in our next BlackBerry WebWorks SDK release. When you completed your extension, you would have had to create/modify a file called manifest.json. This file provided metadata regarding your extension. Moving forward, we will very likely model the format of this file after the CommonJS package.json file format (used by npm modules). This should not constitute very much refactoring, as the current file format is very concise, and the community alignment is valuable in itself.

OK, that’s it for this release. As always the team is working on some exciting stuff for the next release. I can’t wait for the next release! Until then, head over to our download page and our GitHub repo to start working on your custom extensions!

Olá!, I’m Fernando, originally from Brazil and now based in Canada as part of RIM’s Developer Relations team. My mission is helping to make this planet a better, connected, fun place to live. I am also a writer, photographer and avid bass player, I’m passionate about aviation and it seems I have been spending too much time with robotics. (Editor’s note: You know how I feel about robots.)

We at RIM are extremely proud to announce that the BlackBerry® Native SDK for BlackBerry Tablet OS 2.0 is out of beta and now available for download! Based on requests from our developer community, we have been focusing on improving the user experience and providing a consistent environment with comprehensive APIs, resources and documentation.

Let’s take a look at some of the IDE enhancements:

• The EGit plugin allows developers to check out source code directly from GitHub via the IDE.
• A new easy-to-use wizard, Add Library Dependency, simplifies the process of adding library dependencies to a project.
• With per-project SDK support, you can now configure your SDK/toolchain on a per-project basis. This allows you to have projects in your workspace build against different versions of the device.
• A streamlined deployment setup wizard makes it easier for you to set up your development environment and troubleshoot issues. The wizard also leverages automatic device detection to help you set up your targets.
• You can now report bugs directly from the IDE. Select ‘Report a Bug’ from the Help menu in the IDE to report a bug and include screenshots, directly from the IDE.
• You can now filter files out of the BAR package to exclude unnecessary assets.
• BAR files in the Project Explorer can now be expanded to show contents. Files in the BAR can be opened (read-only) in the appropriate editor.
• The Import wizard has a new option, ‘BlackBerry Tablet OS Existing Code as BlackBerry Tablet OS C/C++ Makefile Project,’ to import existing code.
• The BAR file editor now allows viewing of localized manifests for each locale.
• Two new profiles, QNX Developer and C/C++ Developer (CDT), allow you to control access to functionality depending on developer type.
• AIR Native Extension Support, which includes new workflows has been added to the IDE to help you build and debug native extensions. This includes an ANE project type that works with the Adobe command line tools to generate ANEs. In addition, the new ANE launch configurations help you debug your ANE on the device.
• Access to more example projects using the New Example wizard.

The BPS (BlackBerry Platform Services) APIs have evolved too, now including more features and several enhancements:

• Sensor: many sensors are available, for example: accelerometer, magnetometer, temperature, luminance, etc.
• Device Information: functions for reading information like OS version, PIN, serial number etc.
• Soundplayer: several functions to play system sounds (like camera shutter, device lock etc).
• LED service: control of the LEDs and colors to notify users even if the device isn’t being used.
• Audio Mixer API: enables your application to react to events (headphone connected/disconnected, mute, etc) and also control audio properties. Also new input and output channels are available.

And also, highlights on Scoreloop! The addition of the Scoreloop SDK offers game developers next-generation technology for mobile social gaming features: achievements, challenges, user profiles, leaderboards, awards and more. The social features are modular so you can integrate only the ones you want, while maintaining your app’s look and feel.

You can get start at the Native SDK webpage, in the download section. Also take a look at:

• Documentation – in the documentation section, you will find a great source of information about tutorials, recipes, guides and a great directory of open source libraries ported and available on github.
• Forums – in the Native SDK forums, you can discuss support topics, learn from the community and interact directly with us.

So, are you ready? Let us know what you think in the comments!