BlackBerry Push APIs (part 1) - Building an Application that Uses the BlackBerry Push APIs - BlackBerry Push API Domains , Subscriber Registration

10/12/2013 3:14:47 AM
The BlackBerry Push APIs allow a content provider to push content, any content as long as it conforms to RIM’s guidelines, to any BlackBerry device. Instead of pushing to the browser like Web Signals does, the content is pushed to a custom Java application (a push listener) that the content provider creates and distributes to subscribers. The only requirements for the subscriber are that the target device is running BlackBerry Device Software version 4.2 or higher and that the device is provisioned on the BlackBerry Internet Service (BIS).

Some examples of how this technology can be used are

  • Professional sports team: The organization could allow subscribers to subscribe to updates on the team status, rankings, and other topics. This avoids having the subscriber access a website to look up the information; it could be pushed to a Java application running on the device whenever new information was available.

  • Stocks: A financial-management service could create a service that allowed subscribers to register for the stocks they are interested in and deliver performance reports on a regular basis to a device application.

  • News: A news aggregator service could offer a service that allowed subscribers to define search terms they were interested in and push results when any related items were published online.

As a content provider, a push application can provide a service for free or can charge a subscription fee. The push application can push content daily, weekly, monthly, or on some trigger either controlled by the service or defined by subscribers. Push requests are limited to 8 kilobytes (8192 bytes) of payload per request and is constrained by any pushes per day (PPD) limitations RIM may impose on the service. There are also costs associated with the Push APIs. RIM charges organizations a setup fee and a usage fee for the service.

1. BlackBerry Push API Subscription Process

The BlackBerry Push APIs differ from Web Signals in that the registration process happens within a client-side Java application rather than through the browser. Figure 1 illustrates the registration process that must be completed before the application can receive data pushed from the content provider.

Figure 1. BlackBerry Push APIs push subscription process

The subscriber visits websites or an online application repository and downloads an application (1) designed to be the receiver for the pushed data the site offers. When the application is installed on the device and runs for the first time, a registration process begins that sends a request to the RIM Push Infrastructure requesting access to the service (2). The Push Infrastructure validates information in the registration request and returns an encrypted value to the application (3). The application submits a second registration request and includes the encrypted value it received from the first request (4). If everything is good with this second request, the RIM Push Infrastructure returns a status code, indicating the status of the registration process to the application. At this point, the client-side application should submit a registration to the push application (5), indicating that it’s configured and ready to receive pushed content.

2. Signing Up to Use the BlackBerry Push APIs

Before the push application can push any data using the BlackBerry Push APIs, the application must be registered with RIM to obtain the credentials needed to push data to subscribers. Information on the Push APIs and a link to the registration page is available at The BlackBerry Push API website is shown in Figure 2.

Figure 2. BlackBerry Push API developer website

After the registration form has been submitted and the service has been approved, RIM sends a response containing the information the application needs to be able to begin accepting subscriptions and delivering data to subscribers.

3. Building an Application that Uses the BlackBerry Push APIs

Now, it’s time to build the applications needed for your service. The service needs both a client application and a server-based application. RIM provides approved content providers with sample client and server applications that can be studied and used as a base for the applications created for a service. These applications can be downloaded from the BlackBerry Alliance Partner Portal: BlackBerry Universe for Partners.

The client application is called a Push Receiver or Push Listener Application and acts as a listener for the pushed data sent by the service. It registers as a BlackBerry startup application and listens on a particular port (defined when the service was registered) for data pushed to it from the RIM Push Infrastructure. When it receives a push, the application is responsible for processing the data, storing it somewhere so it can be rendered on the screen when the subscriber wants to view it, and (optionally) notifying the user that new data has arrived. If the data is important enough, the push receiver application could repeatedly notify the user until the application is opened. To learn how to build a push listener application in Java, analyze the source code provided to partners when they are approved to use the service or from the BlackBerry Emergency Contact List (ECL) sample application available at

The server-based application is responsible for managing everything related to push subscriptions. The service needs a database and a processing system to manage interaction with subscribers and to manage delivery of the content to subscribers through the RIM Push Infrastructure. When it comes to pushing the content to subscribers, any sort of scheduled or triggered process works; the selected option depends on the nature of the service being provided and how often the data changes.

The database maintains a table of subscriber information. For each subscriber, the application needs to at least store the device PIN associated with the subscription. The database can store additional information, such as the subscriber’s preferences for the service and any other information needed to manage delivery of content to the subscriber. If there is a fee to access the service, this is also probably where information about the subscriber’s subscription expiration, renewal date, and so on would be stored.

3.1 BlackBerry Push API Domains

The Push application must use the appropriate domain based on where a subscriber is located in the world. RIM has implemented regional Network Operations Centers worldwide, and through these regional centers, data is pushed. Because of this regionalization, the push application must ensure it uses the correct domain information when submitting any request. RIM currently supports three regions; Table 1 describes the scope of each region and lists the appropriate domain to use for each.

Table 1. BlackBerry Push API Production Domain Regions
RegionScopeWeb Signals Domain
naNorth America, Latin America, South America, and

For all BlackBerry Push APIs registration requests to the push infrastructure, HTTPS is used rather than HTTP. This allows the content provider credentials to be included in the POST without being visible to prying eyes.

3.2 Subscriber Registration

Registering a subscriber is a multipart process involving multiple connections to the RIM Push Infrastructure plus a connection to the content provider’s backend push application. The registration process takes place inside the custom device-side Java application created for the service.

The first step in the process involves an initial registration with the RIM Push Infrastructure. In this step, the client-side application submits an HTTP POST request to the RIM Push Infrastructure using the following URL:


The push parameters are described in Table 2.

Table 2. BlackBerry Push API Registration URL Parameters
Registration ParameterDescription
Push-DomainThe regional domain that the push recipient resides in.
Service-IDThe unique ID for the push service; this value is provided during registration for the service.
Device-OS-VersionThe version of the BlackBerry Device Software platform used by the device requesting access to the service. The value can be retrieved by calling the DeviceInfo.getPlatformVersion() method in Java.
Device-ModelThe model number for the device requesting access to the service. The value can be retrieved by calling the DeviceInfo.getDeviceName() method in Java.

For a North American subscriber on a BlackBerry 9000 running BlackBerry Device Software 4.6, the URL would look like this:


You might notice that, although the device is running Device Software 4.6, the platform version is actually 4.0. This is not a bug; it’s merely the way RIM handles versioning of the different components of the handheld operating system and device applications. The OS version is 4.0.x, while the BlackBerry Device Software version is 4.6.x.

The RIM Push infrastructure responds with a string of encrypted data that the application must return (within a certain timeframe) to the RIM Push infrastructure for the registration to complete successfully. The return URL looks similar to the previous URL except for the addition of the encrypted data to the end of the URL. The follow-up registration URL is performed via another HTTP POST and is in the following format, where [Encrypted-Data] is replaced with the content received from the server on the first request:


If the RIM Push Infrastructure returned someencryptedvalue from the initial registration request, the subsequent POST URL looks like this:

The RIM Push Infrastructure returns a response code, indicating the status of the request in the format of rc=some-value, where some-value is one of the response codes listed in Table 3.

Table 3. BlackBerry Push API Registration Result Codes
Response CodeDescription
200Registration successful.
10001The BlackBerry device PIN is missing or invalid.
10002The PSID is missing or invalid, or the push service is inactive.
10003The specified PIN is already subscribed to the push service.
10004The specified PIN has already been unsubscribed by the user.
10005The specified PIN has already been unsubscribed by the content provider.
10006The subscription status was set to an invalid value.
10007The specified PIN could not be found.
10009The subscription request failed because the access code was incorrect or an invalid number of parameters were passed.
10010The subscription request failed because the content provider already has the maximum number of subscribers.
10011A required parameter was missing from the subscription request.
-9999A system error occurred.

If the application is pushing the same content to every subscriber, the registration process is complete; when the application wants to push data to subscribers, it uses the push_all attribute for the <address> element in the push request.

If the application is pushing customized content to every subscriber or wishes to push to individual device PINs, there’s one more step in this process. After the push listener application has successfully registered with the RIM Push infrastructure, the client application must notify the backend push application that the particular device has completed the subscription process and is ready to receive pushed data. The format of this notification is not defined; the application submits the notification request in whatever manner and format suits the requirements for the application or the preference of the developer creating the application. All that matters is that the Push application has access to the registered device PIN because that is how the subscriber device is identified in push requests. If this step is not completed, a subscriber has a registered device that is never sent any data by the Push application.

For a sample application that demonstrates this registration process, refer to the sample application code provided by RIM.

Top 10
Review : Sigma 24mm f/1.4 DG HSM Art
Review : Canon EF11-24mm f/4L USM
Review : Creative Sound Blaster Roar 2
Review : Philips Fidelio M2L
Review : Alienware 17 - Dell's Alienware laptops
Review Smartwatch : Wellograph
Review : Xiaomi Redmi 2
Extending LINQ to Objects : Writing a Single Element Operator (part 2) - Building the RandomElement Operator
Extending LINQ to Objects : Writing a Single Element Operator (part 1) - Building Our Own Last Operator
3 Tips for Maintaining Your Cell Phone Battery (part 2) - Discharge Smart, Use Smart
- First look: Apple Watch

- 3 Tips for Maintaining Your Cell Phone Battery (part 1)

- 3 Tips for Maintaining Your Cell Phone Battery (part 2)
- How to create your first Swimlane Diagram or Cross-Functional Flowchart Diagram by using Microsoft Visio 2010 (Part 1)

- How to create your first Swimlane Diagram or Cross-Functional Flowchart Diagram by using Microsoft Visio 2010 (Part 2)

- How to create your first Swimlane Diagram or Cross-Functional Flowchart Diagram by using Microsoft Visio 2010 (Part 3)
Popular Tags
Microsoft Access Microsoft Excel Microsoft OneNote Microsoft PowerPoint Microsoft Project Microsoft Visio Microsoft Word Active Directory Biztalk Exchange Server Microsoft LynC Server Microsoft Dynamic Sharepoint Sql Server Windows Server 2008 Windows Server 2012 Windows 7 Windows 8 Adobe Indesign Adobe Flash Professional Dreamweaver Adobe Illustrator Adobe After Effects Adobe Photoshop Adobe Fireworks Adobe Flash Catalyst Corel Painter X CorelDRAW X5 CorelDraw 10 QuarkXPress 8 windows Phone 7 windows Phone 8