Sending data to the BlackBerry Browser

If you're using BlackBerry 7 and earlier on the BlackBerry device, you can send data to the BlackBerry Browser. When you send data to the BlackBerry Browser, you access the push technology that the BlackBerry MDS Connection Service provides without having to create your own client-side application. The BlackBerry Browser is designed with a listening thread, which listens in the background for data to be delivered to the device. You can push any content that is supported by the target version of the BlackBerry Browser.

The BlackBerry Browser supports several push options, allowing you to choose the approach that is best suited to your needs. You can specify which option to use by using an HTTP header. Additional HTTP headers that are specific to a browser push application can allow you to control how the content appears to the user. These browser-specific headers must be included in addition to the PAP control entity or BlackBerry push headers that are part of every push request.

There are two request types associated with a browser push:

Request type

Description

Browser message

This request type delivers content to the message list, where it appears as an item in the list. Clicking the item in the message list opens the BlackBerry Browser and displays the pushed content.

Browser cache

This request type delivers content directly to the browser cache, but provides no notification to the user. The next time the user attempts to access the associated URL, the browser retrieves and displays the updated content from the cache.

Sending data to the messages application

Your server-side application can send push data to the messages application on the BlackBerry device. A browser message push request can include a descriptive title, which appears as the subject of the message in the messages application. Otherwise, the browser message displays the URL of the associated data as the subject of the message. Users can click on the message to open the BlackBerry Browser and view the data.

When you push data to the messages application, the pushed data is stored in the browser message item, not in the BlackBerry Browser push data cache. When the user deletes the message, the pushed data is deleted with it.

When a browser message arrives on the BlackBerry device, a notification icon appears in the BlackBerry device banner. If the user has configured it to do so, the BlackBerry device issues an alert. By default, the BlackBerry device provides no notification when a browser message arrives.

To push data to the messages application, specify a value of browser-message for the X-Rim-Push-Type header.

You can also choose to include the X-Rim-Push-Title header, which specifies a title used as the subject of the message when it appears in the messages application.

Sending data to the browser cache

Your server-side application can send data directly to the BlackBerry Browser cache. The user receives no notification indicating that new data is available, but the next time that the user visits the specified URL, the browser retrieves the data from the cache.

Browser cache push requests can be used in conjunction with browser message push requests to preload the cache with external resources, such as images or style sheets, that might be referenced by other pushed data, but aren't included. If these resources are pushed to the cache, users can display the data quickly, even if they aren't connected to a wireless or Wi-Fi network. Otherwise, the BlackBerry Browser must make an HTTP request to retrieve referenced resources from the server, which reduces the benefit of a push application.

You can include the X-Rim-Push-Channel-ID header with a browser cache push to associate the cached data with an existing browser channel. If a channel identifier is specified in the request, when the data is pushed to the cache, the URL of the data is added to the appropriate channel (if the channel is already active on the device).

To push to the BlackBerry Browser cache, specify a value of browser-content for the X-Rim-Push-Type header.

You can also choose to include the X-Rim-Push-channel-ID header, which specifies the channel ID of the browser channel with which to associate the data.

Defining cache control properties

When you push content to the BlackBerry Browser, the default length of time the data remains in the pushed data cache varies based on the version of the BlackBerry Device Software the recipient BlackBerry device is running:

  • In BlackBerry Device Software 3.7 or earlier, the BlackBerry Browser clears the cache after 29 days.
  • In BlackBerry Device Software 3.8 or later, the BlackBerry Browser clears the cache after 12 hours.
  • In BlackBerry Device Software 4.2 or later, if the data URL has a query, the data is not cached.

Expired data is cleared from the pushed data cache, even if the user hasn't viewed it.

You can use the Cache-Control or Expires caching directive to increase or decrease the amount of time the data is stored. The BlackBerry Browser respects any caching directives included with pushed data, whether specified in the data header, or within HTML <meta> tags.

Using the Cache-Control header, you can use the max-age control to specify the time, in seconds, the data was pushed by the BlackBerry MDS Connection Service, before the cached data expires. For example:

Cache-Control: max-age=3600

Using the Expires header, you can specify an explicit date and time, in HTTP format, at which the data expires. For example:

Expires: Wed, 07 Oct 2009 08:00:00 GMT

The effect of either method is essentially the same. If you use the Cache-Control header, you can define a static value, since the expiration time is relative to the time the BlackBerry MDS Connection Service pushed the data. If you use the Expires header, you should define the value as a variable and set it appropriately with each push request. However, if you're pushing static resources directly to the cache, such as a style sheet, or an image that is unlikely to change, it is better to use the Expires header, so you can specify an expiry date that is far into the future to keep the component fresh longer.

Transcoding data

If it has been configured to do so, the BlackBerry MDS Connection Service automatically transcodes pushed data before it sends it to the BlackBerry Browser. When the BlackBerry MDS Connection Service transcodes data, it changes the pushed resources into formats that are more suitable for sending over the wireless network and for rendering in the BlackBerry Browser.

Push requests can override the transcoding rules configured for the BlackBerry MDS Connection Service using the X-Rim-Transcode-Content header. This header can be used to specify a list of MIME types that the BlackBerry MDS Connection Service should transcode. If the HTTP header X-Rim-Transcode-Content: application/xhtml+xml is set, then the BlackBerry MDS Connection Service transcodes XHTML data before pushing it to the BlackBerry devices.

You can also specify a value of none to prevent the BlackBerry MDS Connection Service from transcoding any data. For best results, you should typically allow the BlackBerry MDS Connection Service to transcode all your data.

Although most often used with browser content, the X-Rim-Transcode-Content header can also be used in conjunction with a BlackBerry Java Application, if a transcoder exists on the BlackBerry MDS Connection Service for the data format you're sending.

HTTP headers used by the BlackBerry Browser

If you push data to the BlackBerry Browser, you must include a set of headers that define the browser behavior when it receives the pushed data. You can specify whether the data is delivered to the messages application or to a browser channel, and if necessary, specify URLs to icons. These BlackBerry Browser push headers are required in addition to whatever delivery parameters you specified in the PAP control entity or BlackBerry push headers.

When using the PAP push format, the browser headers must be included in the data portion of the multipart message. When using the BlackBerry push format, these headers are simply added to the BlackBerry push headers included in the HTTP POST request.

When the BlackBerry MDS Connection Service encounters the browser push headers, it forwards these headers to the BlackBerry device untouched.

The BlackBerry Browser supports the following headers:

Header

Description

X-Rim-Push-Type

Specifies the browser push type. This header is required for all browser push requests.

This header may have one of the following values:

  • browser-content: Pushes data directly to the browser’s pushed data cache. The next time that the user visits the specified URL, the browser retrieves the updated data from the cache.
  • browser-message: Pushes data to the message list, where the message is identified as a browser message.

X-Rim-Push-Title

Specifies a text string that is used to identify the push application on the Home screen, in the message list, or in the browser bookmarks.

Additonal HTTP headers

When sending data to the BlackBerry Browser, you may also want to include the following headers to define additional controls for the data:

Header

Description

Expires

Specifies an explicit date and time, in HTTP format, at which the data expires. For example:

Expires: Wed, 07 Oct 2009 08:00:00 GMT

If you use the Cache-Control: max-age directive, there is typically no need to include the Expires header.

Cache-Control

Specifies the caching directive for the pushed data. Use the max-age control to specify the time, in seconds, before the cached data expires. For example:

Cache-Control: max-age=3600

If you use the Expires header, there is typically no need to include the Cache-Control: max-age directive.

X-Rim-Transcode-Content

Specifies which types of pushed data the server should transcode.

This header may have one of the following values:

  • */*: Prompts the BlackBerry MDS Connection Service to transcode all data for which it has a transcoder. If you do not specify the X-Rim-Transcode-Content header, the BlackBerry MDS Connection Service transcodes all data by default.

  • none: Forces the BlackBerry MDS Connection Service to send all data to the BlackBerry Browser without transcoding it.
  • list_of_MIME_types : Specifies a comma-separated list of MIME types which the BlackBerry MDS Connection Service transcodes before sending the data to the BlackBerry device.

Content-Location

Specifies the URL location from which the data is downloaded, if the data is not included.