Sending data to the BlackBerry Browser

If the devices you are pushing content to are running BlackBerry 7 or earlier, 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 app. 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 app 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 app

Your server-side push initiator can send push data to the messages app 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 app. 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 app, 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 app, 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 app.

Sending data to the browser cache

Your server-side push initiator 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 app.

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, 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. For example, 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 app 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 app on the Home screen, in the message list, or in the browser bookmarks.

Additional 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.