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.
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 http://na.blackberry.com/eng/developers/javaappdev/pushapi.jsp. The BlackBerry Push API website is shown in Figure 2.
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 www.blackberry.com/go/ecl.
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
| Region | Scope | Web Signals Domain |
|---|
| na | North America, Latin America, South America, and Africa | pushapi.na.blackberry.com |
| eu | Europe | pushapi.eu.blackberry.com |
| ap | Asia-Pacific | pushapi.ap.blackberry.com |
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:
https://[push-domain]/mss/PD_subReg?serviceid=[service-ID]&
osversion=[device-OS-version]&model=[device-model]
The push parameters are described in Table 2.
Table 2. BlackBerry Push API Registration URL Parameters
| Registration Parameter | Description |
|---|
| Push-Domain | The regional domain that the push recipient resides in.
|
| Service-ID | The unique ID for the push service; this value is provided during registration for the service. |
| Device-OS-Version | The
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-Model | The 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:
https://pushapi.na.blackberry.com/mss/PD_subReg?
serviceid=myAppName&osversion=4.0.0.183&model=9000
Note
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:
https://[push-domain]/mss/PD_subReg?serviceid=[service-ID]&
osversion=[device-OS-version]&model=[device-model]&
[Encrypted-data]
If the RIM Push Infrastructure returned someencryptedvalue from the initial registration request, the subsequent POST URL looks like this:
https://pushapi.na.blackberry.com/mss/PD_subReg?
serviceid=myAppName&osversion=4.0.0.183&model=9000&
someencryptedvalue
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 Code | Description |
|---|
| 200 | Registration successful. |
| 10001 | The BlackBerry device PIN is missing or invalid. |
| 10002 | The PSID is missing or invalid, or the push service is inactive. |
| 10003 | The specified PIN is already subscribed to the push service. |
| 10004 | The specified PIN has already been unsubscribed by the user. |
| 10005 | The specified PIN has already been unsubscribed by the content provider. |
| 10006 | The subscription status was set to an invalid value. |
| 10007 | The specified PIN could not be found. |
| 10009 | The subscription request failed because the access code was incorrect or an invalid number of parameters were passed. |
| 10010 | The subscription request failed because the content provider already has the maximum number of subscribers. |
| 10011 | A required parameter was missing from the subscription request. |
| -9999 | A 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.
