Would you like to tell us how we are doing?

You bet No thanks

Push Service

You can use the Push Service to develop a push-enabled application that runs on a BlackBerry device, and that receives push messages from a Push Initiator. 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 (to the general public) or through the BlackBerry Device Service (to enterprise users). The content is available to all users on their devices without waiting for downloads.

To use the Push Service with the BlackBerry Internet Service, you must register with BlackBerry. For more information about registering, visit Push Service. If you're using the Push Service with the BlackBerry Device Service, you don't need to register with BlackBerry.

Architecture

The architecture diagram shows a complete Push Service 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 diagram showing a complete push solution.
Component Description
Push Initiator The Push Initiator is the application that creates request messages (push request, cancel request, status-query request) and response messages (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 You can use the Push Service SDK as the server-side library or you can provide your own library. If you use the Push Service SDK, the server-side library provides the Java APIs that the Push Initiator uses to facilitate all interactions with the 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. For information about developing a Push Initiator using the Push Service SDK, see the Push Service SDK documentation.
Push Proxy Gateway The PPG processes push request messages and status-query messages that it receives from the Push Initiator. After the PPG processes a push request message, it sends a response message that communicates the overall outcome of the push message. The response message contains a result code or a PAP error code. The PPG can be the BlackBerry Internet Service or the BlackBerry Device Service.
Client-side library The BlackBerry 10 SDK for Adobe AIR contains the client-side library. The client-side library provides the ActionScript APIs that the sample application uses to create a session, create and destroy a channel, and receive push messages.
Push-enabled application The push-enabled application runs on a BlackBerry device and might send subscription-related requests to the Push Initiator. The push-enabled application uses the client-side library to create a session, create and destroy a channel, and receive push messages.

What can the Push Service offer?

Increased efficiency
You can choose where to send content. Using the Push Service, you can send content to:
  • Individual users (unicast)
  • Many users (multicast)
  • All of your users (broadcast)
The Push Initiator sends the content when it's available so that data traffic is generated only when necessary. Additionally, with the Push Plus service level, your push solution can store push requests on a local database on the push server. If the Push Initiator receives a result notification, it can then perform status queries locally.
End-to-end message visibility

With the Push Plus service level, you can receive up to three status reports for your push request: a server-level acknowledgment, transport acknowledgment, and application-level acknowledgment. You can also query the status of a push request for a specific BlackBerry device.

Runs in the background

The Push Initiator sends content as bandwidth becomes available so that it doesn't interfere with other applications, such as phone calls.

Minimal battery drain

The Push Service minimizes the impact on device batteries because the push-enabled application listens in the background for the Push Initiator to send content to it. The application doesn't need to poll the push server for content.

Less coding

The Push Service SDK minimizes the amount of code that you need to write to create a Push Service solution. You can use the APIs in the server-side and client-side libraries to perform these common tasks:

  • Send, query, or cancel push messages
  • Specify listeners, acknowledgments and their notifications
  • Track completed push messages
  • Track the running count of push messages

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 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 client application on a BlackBerry device with the Push Essentials level of service.

Process flow diagram showing how a push message is sent.
  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 client application on a BlackBerry device with the Push Plus level of service.

Process flow diagram showing how a push message is sent.
  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.