BlackBerry
Skip Top Navigation
Developers Partners
North America [change region] Products Solutions Purchasing Support
Developers


BlackBerry Developer Journal

Push Me! Pushing Web Content to
BlackBerry Wireless Devices

Mark Sohm, Research In Motion

Many organizations purchase or create web-based applications for use by staff and external users. In many situations it makes sense to extend these applications to the mobile user by making use of BlackBerry wireless devices and the BlackBerry Mobile Data Service (MDS). Note that MDS is part of the BlackBerry Enterprise Server. For more information on BlackBerry MDS please see "Understanding MDS: A Developer's Perspective", published in Volume 1, Issue 3 of the BlackBerry Developer Journal.

Deploying and enabling a web-based application on a BlackBerry wireless device allows for reduced development time by not creating a BlackBerry application. A Browser Push differs from a BlackBerry client push application as there is no requirement to develop a client to reside on the device. There are four types of Browser Push that can be sent to the BlackBerry wireless device.

Topics within this section include:

Browser Channel Push

A Browser Channel Push sends a web page and two icons to the BlackBerry wireless device. The web page is stored in the cache of the BlackBerry Browser, and an icon is shown on the home screen of the device. An unread icon can be specified so that when a new Browser Channel Push arrives to the device, it will display the unread icon. After the user has opened and visited the page, the read icon is shown. This provides the user with a visual indication as to when a page has been updated. Itís useful for a news service so that users are aware of when new data has arrived. The icons can even change with every push allowing an application to continually push different icons. This would be useful for a weather application updating the current weather conditions.

Browser Channel Delete Push

A Browser Channel Delete works in a similar, but opposite fashion of the Browser Channel Push. It will remove an icon on the BlackBerry Home screen that has been sent via a Browser Channel Push. Icons initiating from a Browser Channel Push can also be removed from the device itself.

Browser Content Cache Push

Browser Content Cache Push is the most discreet type of Browser Push. A Browser Content Push will push a web page to the BlackBerry wireless device and store it in the BlackBerry Browserís cache. The user is not informed in any way when this push takes place, or when the page has been updated.

Browser Message Push

Instead of creating an icon on the home screen of the BlackBerry wireless device, a Browser Message Push will arrive in the Inbox on the device. When the user opens the message, the default browser on the device is launched then opens the page. Unlike the Browser Channel Push or Browser Content Push, the web page is stored as a browser message instead of in the BlackBerry Browserís cache. This means that the page will be available until the message is deleted. It will not be removed from the BlackBerry Browser cache when other events (browsing, cache clear) take place. The message created from a Browser Message Push is not sent to, and will not appear in, a userís Inbox on their desktop. It is sent directly to the device.

How to push

Push applications can be created using any development language that is able to initiate a network connection and perform an HTTP post. A post to the BlackBerry MDS Server handles the delivery of the push to a BlackBerry wireless device. The post is made up of the standard html request headers, a few unique Browser Push headers and the web page being pushed (it is not required to send the web page when performing a Browser Channel Delete Push). The following additional http request headers are required for a Browser Push to take place.

Required

X-RIM-Push-Title
X-RIM-Push-Type

Optional

X-RIM-Push-Channel-ID
X-RIM-Push-UnRead-Icon-URL
X-RIM-Push-Read-Icon-URL

The "X-Rim-Push-Title" header holds the title that will appear on the home screen of the device for a Browser Channel Push, or in the subject of the message of a Browser Message Push. The "X-RIM-Push-Type" header holds the value that represents the type of push being sent. Possible values are:

  • Browser-Channel
  • Browser-Message
  • Browser-Content
  • Browser-Channel-Delete

The "X- RIM-Push-Channel-ID" header contains the URL of the page to be pushed to the device. This is not required when performing a Browser Message or Browser Content push. The "X-RIM-Push-UnRead-Icon-URL" and "X-RIM-Push-Read-Icon-URL" are optional headers that specify the URL of the icons to be used for a Browser Channel Push. If these are not specified then the default Browser Channel Push icons are used. These two headers are not required for Browser Message, Browser Content or Browser Channel Delete Push and may be omitted.

The page that is to be pushed is submitted once the headers are sent. It is recommended that this page resides on a web server, although it is not required. If it is not located on a web server, a user would be unable to refresh the page. If the page has been removed from the BlackBerry Browser cache (if a Browser Channel or Browser Content Push was used) they would be unable to view it. It is not required to send the actual page when performing a Browser Channel Delete.

Sample Java Push Application

A sample Java based push application is included and documented with the BlackBerry JDE. The BlackBerry JDE can be downloaded using the following link:

http://www.blackberry.com/developers/downloads/jde/

Sample PHP Push Application

PHP can be used to create a simple, transferable web page that can be used to initiate a Browser Push to the device. Accessible from any browser, it allows you to send any type of Browser Push discussed here to any user on your BlackBerry Enterprise Server. Any web server that is enabled for PHP should be able to serve up this page without additional configuration. Please see the listing at the end of this article of the sample PHP application. This application relies on an html page that contains a form to collect the required push information from the user. This is a basic html form and is not discussed below.

The first step in the PHP application is to create the URL the request will be posted to.

$path = "/push?DESTINATION="
      . $HTTP_POST_VARS['email']
      . "&PORT=7874&REQUESTURI=/";

The destination points to the email address or BlackBerry PIN of the user to deliver the Browser Push to. The port number 7874 is the port the BlackBerry Browser is listening on for incoming push requests. Once this URL has been constructed we open a socket connection to the BlackBerry MDS Server.

$besfs = @fsockopen($HTTP_POST_VARS['besHostname'],
         $HTTP_POST_VARS['besPort'], $errno, $errstr,30);

The BlackBerry MDS Server hostname and MDS push port supplied in the html push form are used as parameters to open the socket connection. If the connection was successfully opened we can start to write out the header information.

fputs($besfs, "POST $path HTTP/1.0\r\n");

fputs($besfs, "Host: "
    . $HTTP_POST_VARS['besHostname'] . "\r\n");

fputs($besfs, "Content-Location: "
    . $HTTP_POST_VARS['pushURL'] . "\r\n");

fputs($besfs, "X-RIM-Push-Title: "
    . $HTTP_POST_VARS['pushTitle'] . "\r\n");

fputs($besfs, "X-RIM-Push-Type: "
    . $HTTP_POST_VARS['pushType'] . "\r\n");

The standard HTTP request headers are sent along with the two required BlackBerry Push headers. The URL of the page to be pushed, the push title and push type are retrieved from the html form the user submitted. If the Browser Push is a Browser Channel or Browser Channel Delete, "X-RIM- Push-Channel-ID" is required. If a Browser Channel Push is being sent, the URL of the read and unread icons are specified. Not specifying a URL for the read and unread icons will cause the device to use its default icons.

if ($HTTP_POST_VARS['pushType'] == "Browser-Channel"
||  $HTTP_POST_VARS['pushType'] == "Browser-Channel-Delete")
{
  fputs($besfs, "X-RIM-Push-Channel-ID: "
      . $HTTP_POST_VARS['pushURL'] . "\r\n");

  //Send the push icon URL's if we are using
  //a browser channel push.
  if($HTTP_POST_VARS['pushType'] == "Browser-Channel")
  {
    fputs($besfs, "X-RIM-Push-UnRead-Icon-URL: "
        . $HTTP_POST_VARS['unreadIconURL'] . "\r\n");

    fputs($besfs, "X-RIM-Push-Read-Icon-URL: "
        . $HTTP_POST_VARS['readIconURL'] . "\r\n");
  }
}

Now that the required header information has been sent to the BlackBerry MDS Server we are ready to push the web page. Sending the entire web page would not be required when sending a Browser Channel Delete.

$webURL = parse_url($HTTP_POST_VARS['pushURL']);

//Set the port to 80 if not otherwise specified
//in the push URL.
if (empty($webURL['port']))
  $port = 80;
else
  $port = $webURL['port'];

//Open a socket connection to the webserver
//hosting the page to push.
$webfs = @fsockopen($webURL['host'], $port, $errno, $errstr, 30);
fputs($webfs, "GET " . $webURL['path'] . " HTTP/1.1\r\n");
fputs($webfs, "Host: " . $webURL['host'] . "\r\n");
fputs($webfs, "Connection: Close\r\n\r\n");

//Read and discard the first line from the
//webserver (should be HTTP/1.1 200 OK).
fgets($webfs);

//Read in the page to push from the web server
//and write it out to the MDS server.
while (!feof($webfs))
{
  fputs($besfs, fgets($webfs));
}
//Close the connection to the web server.
fclose($webfs);

If the push is a Browser Channel Delete then two additional headers must be specified. These are only required for a Browser Channel Delete as they would normally be supplied in the headers passed through from the web server when performing a Browser Channel, Browser Message or Browser Content Push.

if ($HTTP_POST_VARS['pushType'] == "Browser-Channel-Delete")
{
  //No content to send when performing a
  //Browser Channel Delete Push.
  fputs($besfs, "Content-length: 0\r\n");
  fputs($besfs, "Connection: Close\r\n\r\n");
}

At this point the push should have been sent to the BlackBerry MDS Server. All that is left is to capture the output from the BlackBerry MDS Server and pass it back to the user performing the push. A response code of 200 from the BlackBerry MDS Server indicates that a successful push has taken place.

$buf = "";
//Capture the MDS serverís reply to the push.
while (!feof($besfs))
  $buf .= fgets($besfs,128);

fclose($besfs);
//Display the MDS server's reply.
echo "Response from MDS: <br>";
echo $buf;

From the sample code above you can see how easy it is to create a Browser Push application for the BlackBerry wireless device. Doing so will give you a framework to deploy most types of web application to BlackBerry users. You can simply place the entire file shown below on a PHP enabled web server and begin pushing to BlackBerry users immediately.


Download The Source


Please email your comments, suggestions and editorial submissions to


Top |  Table of Contents |  Journal in PDF Format |  Legal Disclaimer
 
     
 Home | Products | Solutions | Purchasing | Support | Developers | Worldwide | News | About Us | Contact Us | Site Map
 Legal | Copyright © 2008 Research In Motion Limited, unless otherwise noted.