How it works

Push technology lets you send up to 8KB of content (images, text, or audio) to BlackBerry devices as soon as it's available. The Push Initiator is the server-side application that sends the content to many devices at once through the BlackBerry Internet Service, the BlackBerry Enterprise Server, the BlackBerry Device Service, or through all three simultaneously. The push-enabled application is the client-side application on the device that receives the content.

The following 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.


Architectural diagram showing a complete push solution.

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

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 interact 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 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 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 to develop the push-enabled application 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


Process flow diagram showing how a push message is sent.

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


Process flow diagram showing how a push message is sent.

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. The majority of push-enabled apps in BlackBerry World use Push Essentials.

If you are pushing data through the BlackBerry Enterprise Service, you have access to features comparable to Push Plus.

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.

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

Push Plus is a paid level of service. It 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.

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