Would you like to tell us how we are doing?

You bet No thanks

Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Push Service

You can use the Push Service to develop a push solution that delivers content from a Push Initiator on a server to a push-enabled application on a BlackBerry device. With push technology, the Push Initiator doesn't need to wait for a request from the push-enabled application to deliver the content. The Push Initiator can deliver up to 8 KB of content (images, text, or audio) to many devices at once through the BlackBerry Internet Service, the BlackBerry Enterprise Server, the BlackBerry Device Service, or through all three simultaneously.

To use the Push Service with the BlackBerry Internet Service, you must register with Research In Motion. If you're using the Push Service with the BlackBerry Enterprise Server or the BlackBerry Device Service, you don't need to register with RIM.

For more information about the Push Service, or to register with RIM, visit Push Service.

Architecture

The architecture diagram shows a complete push solution that includes the server-side library and the client-side library. The libraries work together to deliver content from the Push Initiator to a push-enabled application.


Architecture of the Push Service framework.

Component

Description

Push Initiator

The Push Initiator is the application that creates request messages (such as a push request, cancel request, or status-query request) and response messages (such as a result-notification response) using the server-side library, and submits them to the Push Proxy Gateway (PPG). The Push Initiator also uses the server-side library to process subscription-related requests that it receives from the push-enabled application on the BlackBerry device.

Server-side library

The Push Service SDK contains the server-side library. The server-side library provides the Java APIs that the Push Initiator uses to facilitate all interactions with the PPG. The Push Initiator uses the server-side library to create push messages, status-query messages, and result-notification response messages in PAP XML format for delivery to the PPG. The Push Initiator uses the server-side library to process result-notification messages, status-query response messages, and push-response messages that it receives from the PPG. The Push Initiator also uses the server-side library to process subscription-related requests, such as subscribe, unsubscribe, suspend, and resume requests, that it receives from the push-enabled application.

Push Proxy Gateway

The PPG processes push request messages that it receives from the Push Initiator. After the PPG processes a push request message, it sends a response message to the Push Initiator that communicates the result of the push message. The response message contains a result code or a PAP error code. The BlackBerry Internet Service, the BlackBerry Enterprise Server, or the BlackBerry Device Service can act as the PPG.

Client-side library

The SDK for the development platform that you choose includes the client-side library for the push solution. The client-side library provides the APIs that the push-enabled application uses to receive push messages from the Push Initiator.

The following SDKs contain the client-side library for BlackBerry 7 and earlier:

The following SDKs contain the client-side library for BlackBerry 10:

Push-enabled application

The push-enabled application is the client application that runs on a device. The push-enabled application uses the client-side library to receive push messages from the Push Initiator. The push-enabled application might also send subscription-related requests to the Push Initiator.

Process flows

The Push Initiator can send a push message to many devices at once through the BlackBerry Internet Service, the BlackBerry Enterprise Server, the BlackBerry Device Service, or through all three simultaneously. Here's what happens when the Push Initiator sends a push message to subscribed users on BlackBerry devices.

BlackBerry Internet Service


How the Push Service works with the BlackBerry Internet Service.

When the PPG is the BlackBerry Internet Service, push messages are sent following this process:

  1. The Push Initiator sends a push message to the BlackBerry Internet Service in the form of an HTTPS POST.

    The push message is a MIME multipart message, which contains the following items:
    • A WAP PAP 2.1 XML control entity, which describes the delivery parameters and specifies one or more BlackBerry devices to which the content will be delivered
    • The content to deliver to the specified BlackBerry devices
  2. The BlackBerry Internet Service receives the push message and attempts to authenticate the Push Initiator.
  3. If the Push Initiator is successfully authenticated, the BlackBerry Internet Service validates the push message.

    • If the Push Initiator is within the daily quota of push messages, and the request contains all the required information, the BlackBerry Internet Service accepts the push message.
    • If the Push Initiator has exceeded the push limits, the BlackBerry Internet Service rejects the message.
  4. The BlackBerry Internet Service returns a push response to acknowledge receipt of the push message, and indicates whether the message is accepted for processing or rejected. If the push message is rejected, the BlackBerry Internet Service returns an error code to the content provider that provides the reason for the rejection.
  5. The BlackBerry Internet Service sends the push message to the specified BlackBerry devices.
  6. Each BlackBerry device notifies the BlackBerry Internet Service when the push message is received. A push message is considered successful if the message is delivered before the specified expiry time and it meets the criteria specified by the <quality-of-service> element in the push message.
  7. If the Push Initiator requests notification, the BlackBerry Internet Service sends a result notification (acknowledgement) message to the push server.
  8. The Push Initiator responds to the BlackBerry Internet Service, acknowledging the receipt of the result notification.

BlackBerry Enterprise Server or BlackBerry Device Service


How the Push Service works with the BlackBerry Enterprise Server.

When the PPG is the BlackBerry Enterprise Server or the BlackBerry Device Service, push messages are sent following this process:

  1. The Push Initiator sends a push message to the BlackBerry MDS Connection Service of the BlackBerry Enterprise Server or the BlackBerry Device Service in the form of an HTTPS POST.

    The push message is a MIME multipart message, which contains the following items:
    • A WAP PAP 2.0 XML control entity, which describes the delivery parameters and specifies one or more BlackBerry devices to which the content will be delivered
    • The content to deliver to the specified BlackBerry devices
  2. The BlackBerry MDS Connection Service returns a push response to acknowledge receipt of the push message, and indicates whether the message is accepted for processing or rejected. If the push message is rejected, the BlackBerry MDS Connection Service returns an error code to the content provider that provides the reason for the rejection.
  3. The BlackBerry MDS Connection Service sends the push content to the specified BlackBerry devices.
  4. Each BlackBerry device notifies the BlackBerry MDS Connection Service when the push message is received. A push message is considered successful if the message is delivered before the specified expiry time and it meets the criteria specified by the <quality-of-service> element in the push message.
  5. If the Push Initiator requests notification, the BlackBerry MDS Connection Service sends a result notification message to the push server.
  6. The Push Initiator responds to the BlackBerry MDS Connection Service, acknowledging the receipt of the result notification.

Levels of service

When you use the Push Service with the BlackBerry Internet Service, you can choose from two levels of service: Push Essentials and Push Plus.

When you use the Push Service with the BlackBerry Enterprise Server or the BlackBerry Device Service, the Push Plus level of service is included.

Push Essentials

When you use the Push Essentials level of service, you can send content to a device, but you can't query the status of the content or receive acknowledgments after you send the content. However, you can set the expiry time for content delivery for up to 30 days.

Here's how content is sent to a push-enabled application on a BlackBerry device with the Push Essentials level of service.

Push Essentials service level.
  1. The content provider sends content in a push request.

  2. The PPG authenticates and acknowledges the push request.

  3. The PPG pushes the content to the specified device or devices.

  4. Each BlackBerry device acknowledges the push request to the PPG.

Push Plus

The Push Plus level of service offers the following additional functionality so that you can check the status and receive notifications about delivered content:

  • Results notification lets you know when messages are delivered, if they couldn't be delivered, or if they expired waiting to be delivered.
  • The PPG keeps track of the current status of a push message, and you can use a status query to check the status. The status of a push message can be pending, delivered, undeliverable, or expired.
  • Push cancellation can withdraw messages if they haven't been delivered already.
  • You can set the expiry time for content delivery for up to 8 hours.

Here's how content is sent to a push-enabled application on a BlackBerry device with the Push Plus level of service.

Push Plus service level
  1. The content provider sends content in a push request, and can request to receive a result notification.

  2. The PPG authenticates and acknowledges the push request.

  3. The PPG pushes the content to the specified device or devices.

  4. Each BlackBerry device acknowledges the push request to the PPG.

  5. If the content provider requested to receive a result notification when it sent content in step 1, the PPG sends a notification to the content provider indicating whether the push message was delivered, was undeliverable, or expired waiting to be delivered.

  6. The content provider acknowledges the receipt of the result notification.

  7. Alternatively, if the content provider didn't request to receive a result notification, the content provider can request the status of the content from the PPG. The status request can be for any or all of the devices that received the content.

  8. If the content provider requests the status of the content, the PPG returns a single response that contains the current status for the specified devices.