You might have heard the terms “push” and “push notifications” thrown around before. So in a nutshell, what’s push good for? Push does pretty much what the name implies: it allows you to push information to BlackBerry® smartphones the moment it is available, and the user gets the push message almost immediately after it’s sent.

Push is an interesting technology because you need to write two applications for it to work:

1) You have to write a server-side push application (sometimes called a Push Initiator) so that you can send out push messages to BlackBerry smartphones.
2) You also have to write a client-side push application (sometimes called a push-enabled application) so that users can receive those push messages on a BlackBerry smartphone.

The rest of this blog post concentrates on the push-enabled application, and explains how to write a good application using the BlackBerry® WebWorks™ SDK.

The Push Service APIs that are part of the BlackBerry WebWorks SDK are brand new for BlackBerry® 10. When we created the APIs, our goal was to start fresh – to make things clean and simple. We also wanted to make sure that the Push Service APIs would work well with other new APIs introduced for BlackBerry 10, like invoke events (that is, the blackberry.invoked feature).

There are only two classes that you have to worry about in the Push Service APIs:

1) PushService has the business logic that you need to start receiving push messages in your app

and

2) PushPayload is essentially a value object containing the content and headers of your push message.

Now that you want your app to start receiving pushes, where do you start? The first question to ask yourself is whether or not you’re developing this app for the general public. If you are, you should register to evaluate the Push Service at this link: https://www.blackberry.com/profile/?eventId=8121 After registering, you’ll receive an email with all the information that you need to write your push-enabled application, including your application ID, password, and the PPG URL you will be pushing messages to. If you’re developing your app for enterprise users, you don’t have to worry about registering.

In order to use the Push Service APIs, you need to update your application’s config.xml:

1) You need to reference the blackberry.push feature:

<feature id=”blackberry.push” />

2) You need to add a feature tag for blackberry.invoked:

<feature id=“blackberry.invoked” />

This feature tag relates to the handling of invoke events. A push notification comes into your application as an invoke event.

3) Finally, you need to have an entry relating to the invoke events that you receive for push messages:

Take note of the id attribute (also known as the “invoke target id”). This attribute has to match the options.invokeTargetID that is passed in to the call to the static create function of the PushService class (more about the create function in a moment). Another important detail is that the action tag is set to “bb.action.PUSH”. This setting makes it clear that the invoke relates specifically to push messages.

Now, here’s a quick rundown of the Push Service APIs. Don’t worry, there aren’t many.

1) Call the static create function on the PushService class to get a PushService object you can start using. If the create call fails, you won’t have access to a PushService object. That’s why the create function has success and fail callbacks. You’ll need a lot of the info from the email you received when you registered to evaluate the Push Service (for public apps), so have that info handy for this call.

2) If your application is not running, one of the major advantages of push is to allow your application to be launched when a new push comes in, and to have your app continue to run in the background. This allows valuable device resources to be saved because your app doesn’t have to be running all the time to be able to receive push messages.

The default behavior for your application is to not have it launch when a new push comes in. That’s where the launchApplicationOnPush function comes in (from the PushService class). If you call it with a value of true, then it will activate the launch functionality. You can turn this functionality off at any time by calling launchApplicationOnPush again with a value of false.

When that’s done, how does the server-side Push Initiator know who to push to? There’s something we call a “token” that you get back when you do a createChannel. You need to pass the toke along to the Push Initiator so it knows who to address a push to. If you’re using the Push Service SDK I recommended above, then you just simply pass this token to the Push Initiator using an HTTP request (we call it a subscribe operation).

4) Ok, you’re now ready to receive pushes (you created the channel) and you’re ready to send pushes (the Push Initiator has the token). Fire off a push to the token using your Push Initiator.

5) In BlackBerry 10, the push comes to the app as an invoke event using the new blackberry.invoked feature in BlackBerry WebWorks. We register for the event with the following call:

Now that we have the invoke request in our invokedCallbackFunc callback, how do we get the push out of it? Simply call the PushService object’s extractPushPayload function passing in the invoke request and it will give you back a PushPayload object.

(Quick side note: You’ll probably want to make sure the invoke event you received was for a push. The invoke event can be for other various reasons too. It’s easy to check though. Just make sure

6) And there you go. You have the PushPayload object, and you can do whatever you want with the data.

You might have noticed that the “data” property of the PushPayload object is of type Blob. Look at the extractPushPayload function in the API Reference for PushService (see the link I gave above). It shows examples of how to convert that Blob into something that you can actually display to users.

7) From this point onwards, you app will continue to receive push messages. If at any time you want your app to stop receiving push messages, simply call the destroyChannel function on your PushService object.

Sure, using push requires some extra effort. You do need to write two applications, but the benefits to your users are huge. Just imagine displaying notifications in your app the moment an event of interest happens in the real world. That’s a pretty powerful thing.

And that’s why the BlackBerry WebWorks SDK for the client-side application (and Push Service SDK for the server-side application) is there to help make your life easier and to use push to its full potential.