Push
The Push object allows you to leverage the BlackBerry push architecture to receive push data in your application.
Since the state for JavaScript for a web page is only as long as the web page is being viewed, there is a need for
the app to maintain the open port for push information. This allows this listening for push data to remain open
between page transitions. If no current active callback is assigned to the push listener, the app will queue the
push data (limiting the number of messages using maxQueueCap if available) for the application until a subsequent
openPushListener call is made for that port.
At that point it will then pass the data to the subscribed callback function. To subscribe to the same previously
opened push port on a new web page, a secondary call to openPushListener is called. In this scenario it will
reassign the callback provided to the already open port.
- Explicit register, unregister menu options.
- Use automatic, periodic registration calls to the BlackBerry Push Service to ensure that subscribers receive their desired pushes. The period you pick would depend on the application you write. If you plan to send out a high frequency of pushes to a subscriber in a given day, you will want to make the registration calls more frequent (e.g. once a day). If your application will only send out a low number of pushes in a given day to a subscriber, then you can make the registration calls less frequent (e.g. once a week).
Supported Platform(s)
- BlackBerry OS 5.0+ |
- Ripple Emulator |
API | BB5.0 | BB6.0 | BB7.0 | PB1.0 | PB2.0 | BB10 | Ripple |
---|---|---|---|---|---|---|---|
blackberry.push.closePushListener | Y | Y | Y | Y | |||
blackberry.push.openBESPushListener | Y | Y | Y | ||||
blackberry.push.openBISPushListener | Y | Y | Y | ||||
blackberry.push.openPushListener | Y | Y | Y | Y |
Configuration Document Settings
To use all of the API described for this object, you must ensure the following settings are in your configuration document: |
You must declare the feature element(s) below in your configuration document: |
Feature ID | BB5.0 | BB6.0 | BB7.0 | PB1.0 | PB2.0 | BB10 | Ripple |
---|---|---|---|---|---|---|---|
<feature id="blackberry.push" /> | Y | Y | Y | Y |
Permission Elements (PlayBook and BlackBerry 10+) |
---|
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application. |
Functions
** Marked for Deprecation
Functions
static
void
blackberry.push.closePushListener
([port : Number])
Closes the listening connection for an already open push channel.
When this method is called, it will stop listening for incoming data on the push port.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
Parameters | |
---|---|
port | The port used in the open push method. If port is not specified, all open ports will be closed. |
Code Example:
|
static
void
blackberry.push.openBESPushListener
(options : Object, onData: function(data : blackberry.push.Data), onSimChange: function())
Opens the push listener to allow an application to listen for BES pushes. Only one port can be opened at a time if openBESPushListener
or openBISPushListener functions are used.
If calling openBESPushListener on a page where the port is already open, the callbacks will be updated to use the latest one passed in. The queue size and wake up page will not be updated.
If an application registered to BES push is closed and a push message arrives, the application will be launched in background and the wake up page is displayed. rim:allowInvokeParams="true" attribute must be specified in the content element of config.xml.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
options |
Object literal that allows the user to specify the port, wake up page and maximum queue size.
port: The port on the device to listen for pushes on. wakeUpPage: The page that wlll be displayed when application is closed and a new push message arrives. maxQueueCap: Optional parameter that specifies how many messages the app should queue if the port was not closed, but a function handler was lost (for example, during a page transition). If the parameter is not specified, no limit will be imposed. |
onData |
The callback that is invoked when a new push has been received. To enable reliable push and acknowledge receipt of the payload, the callback must explicitly return 0 indicating that the push message has been accepted. Returning any other value (including not returning anything at all) in the callback would indicate that the message has been declined.
data: Object that contains the data that was just received. |
onSimChange | The callback that is invoked when SIM card is changed. When this happens, the push is stopped, and user is recommended to close the push listener, unregister the old user from the content provider, and advise the user to re-register. |
Code Example:
|
static
void
blackberry.push.openBISPushListener
(options : Object, onData: function(data : blackberry.push.Data), onRegister: function(result : Number), onSimChange: function())
Opens the push listener to allow an application to listen for BIS pushes. Only one port can be opened at a time if openBESPushListener
or openBISPushListener functions are used.
If calling openBISPushListener on a page where the port is already open, the callbacks will be updated to use the latest one passed in. The queue size and wake up page will not be updated.
If an application registered to BIS push is closed and a push message arrives, the application will be launched in background and the wake up page is displayed. rim:allowInvokeParams="true" attribute must be specified in the content element of config.xml.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
options |
Object literal that allows the user to specify the port, appId, server URL, wakeup page and maximum queue size.
port: The port on the device to listen for pushes on. appId: The id provided to you for your push application after signing up to use the BlackBerry Push Service. serverUrl: The URL of the push server. Examples of this URL include: http://pushapi.eval.blackberry.com if using the eval environment of the BlackBerry Push Service or http://pushapi.na.blackberry.com if using the production environment of the BlackBerry Push Service. wakeUpPage: The page that wlll be displayed when application is closed and a new push message arrives. maxQueueCap: Optional parameter that specifies how many messages the app should queue if the port was not closed, but a function handler was lost (for example, during a page transition). If the parameter is not specified, no limit will be imposed. |
onData |
The callback that is invoked when a new push has been received. To enable reliable push and acknowledge receipt of the payload, the callback must explicitly return 0 indicating that the push message has been accepted. Returning any other value (including not returning anything at all) in the callback would indicate that the message has been declined.
data: Object that contains the data that was just received. |
onRegister |
The callback that is invoked when the result of the registration is received.
result: The registration result. These include: 0: success, 1: network error, 2: rejected by server, 3: invalid parameters, -1: general error. |
onSimChange | The callback that is invoked when SIM card is changed. When this happens, the push is stopped, and user is recommended to close the push listener, unregister the old user from the content provider, and advise the user to re-register. |
Code Example:
|
static
void
blackberry.push.openPushListener
(onData: function(data : blackberry.push.Data), port : Number, [transport : blackberry.identity.Transport], [maxQueueCap : Number])
Deprecation Notice:
This API is deprecated, please use blackberry.push.openBESPushListener or blackberry.push.openBISPushListener instead.Known Issues:
Using this API in multiple applications could cause large CPU usage on some of the applications. It is recommened to use (blackberry.push.openBESPushListener or blackberry.push.openBISPushListener) instead.
Registers a callback function that will be called when new data has been pushed to the device.
If calling openPushListener on a page where the port is already open, the callback will be updated to use the
latest one passed in. NOTE: In such cases where consecutive calls to openPushListener occurs on the page,
the transport argument will only be used on the first call, and ignored for all others. Any calls to
openPushListener should have matching calls to closePushListener to ensure ports are not left open accidentally.
Known issue: Running multiple push applications or opening multiple port in the same application could cause large CPU usage. It is recommended to use new push API when writing new push application. Opening multiple ports in the same application is not allowed in the new push API.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
Parameters | |
---|---|
onData |
This callback function is triggered when data is received.To enable reliable push and acknowledge receipt of the payload, the callback must explicitly return 0 indicating that the push message has been accepted.Returning any other value (including not returning anything at all) in the callback would indicate that the message has been declined.
data: Object that contains the data that was just received. It has a payload property which is a Blob. The developer can then retrieve the data either as a Blob or use blackberry.utils.blobToString() function to convert it into a string if the data is a string. |
port | Integer port number to listen on for push data. |
transport | Optional parameter where you can choose which communications transport you wish to listen on. |
maxQueueCap | Optional parameter that specifies how many messages the app should queue if the port was not closed, but a function handler was lost (for example, during a page transition). |
Code Example:
|