3.3 Pushing Data to Subscribers
To push data to one or more subscribers, the push
application must build an HTTP POST request that contains all the
information needed for the push and deliver it to the same server
described above. The POST URL contains all the information passed to
the RIM Push Infrastructure; the body of the POST is not used to
deliver any information.
The Push URL is formatted with the following information:
https://[push-domain]/mss/PM_submitJob?sid=[SID]
&pass=[SID-Password]&validfor=[expiration]&title=[title]
&readiconURL=[Read-Icon]&unreadiconURL=[Unread-Icon]&
contentURL=[Content-URL]&puids=[PUID-List]
HTTPS protects the contents of the SID and SID password when delivered in the URL.
Table 6 provides a description for each of the push URL parameters.
Table 6. Web Signal Push Request URL Parameters
| Push Parameter | Description |
|---|
| Push-Domain | The regional domain that the push recipient resides in. Refer to Table 3 for the possible values for this parameter. |
| SID | The Service ID (SID) assigned to this Web Signal by RIM. |
| SID-Password | The password associated with the SID. |
| Expiration | The
time, in seconds, that the push request is valid. The minimum value is
7,200 seconds (2 hours) and the maximum value is 86,400 seconds (24
hours). |
| Title | Specifies
the title that appears on the BlackBerry Home Screen for the Web
Signal. The push application uses this value to identify the Web Signal
on the device, but can also use it to provide some information about
the contents of the signal. (Refer to Figure 6
for an example of how this is used by AccuWeather in their service.)
The title must be in English and can be of a maximum length of 256
bytes. Valid characters for the title are both upper and lower
alpha-numeric characters (A-z and 0-9), plus the !, -, @, ., and _ characters. It can contain internal spaces, but both leading and trailing spaces are removed. |
| Read-Icon | Specifies
the absolute URL for the icon file (in PNG format) displayed after the
mobile user opens the signal after a successful push. The icon file
must conform to the standards for BlackBerry application icons and the
URL accessible by external (outside the firewall) resources. |
| Unread-Icon | Specifies
the absolute URL for the icon file (in PNG format) displayed until the
mobile user has openeds the signal after a successful push. The icon
file must conform to the standards for BlackBerry application icons and
the URL accessible by external (outside the firewall) resources. |
| Content -URL | Specifies
the absolute URL for content being pushed to the device. The URL
provided here will be opened in the browser when the user opens the Web
Signal.
The URL can be up to 2,048 bytes in length. |
| PUID-List | Comma-separated
list of subscriber PUIDs to which the content will be delivered. The
push application can push to all subscribers for the SID by using
ALL_USERS for this parameter. |
The requirement for Icon URLs to be absolute URLs
pointing to the icon file is based on the fact that the BlackBerry
device retrieves the icons separately after the push request has been
received. The BlackBerry Device Software has to know exactly where to
locate the file and has to be able to access the file from outside the
company’s firewall. The icon URL can be up to 2,048 bytes in length.
Assuming email address is used for the PUID, to push content to a North American subscriber, the push URL would look like this:
https://push.na.blackberry.com/mss/PM_submitJob?
sid=mywebsignal&pass=mypassword&validfor=86400&title=
My%20Web%20Signal&readiconURL=http://ws.someserver.com/
read.png&unreadiconURL
=http://ws.someserver.com/unread.png&contentURL=
ws.someserver.com/signal&[email protected]
Because spaces are not valid characters in Internet URLs, the example used %20 to encode any spaces in the URL provided.
If the push application needed to push to more than one subscriber, the push URL would look like this:
https://push.na.blackberry.com/mss/PM_
submitJob?sid=mywebsignal
&pass=mypassword&validfor=86400&title=My%20Web%20Signal
&readiconURL=http://ws.someserver.com/read.png
&unreadiconURL=http://ws.someserver.com/unread.png
&contentURL=ws.someserver.com/signal
&[email protected],[email protected],
[email protected]
If the push application wanted to push to all subscribers of the service, a sample push URL would be
https://push.na.blackberry.com/mss/PM_
submitJob?sid=mywebsignal
&pass=mypassword&validfor=86400&title=My%20Web%20Signal
&readiconURL=http://ws.someserver.com/read.png
&unreadiconURL=http://ws.someserver.com/unread.png
&contentURL=ws.someserver.com/signal&puid=ALL_USERS
For a successful push request, the push server
responds with a JobID. The job ID identifies the push request for
debugging purposes or if the content provider needs to open an
investigation with RIM. For unsuccessful requests, the server returns rc=some-value, where some-value is one of the response codes listed in Table 7.
Table 7. Web Signals Subscriber Registration Response Codes
| Response Code | Description |
|---|
| 0500 | A SID was not included in the push request URL. |
| 0501 | A SID password was not included in the push request URL. |
| 0502 | A PUID was not included in the push request URL. |
| 0503 | Authentication failed. |
| 0504 | A title was not included in the push request. |
| 0505 | A read icon URL was not included in the push request. |
| 0506 | An unread icon URL was not included in the push request. |
| 0507 | A content URL was not included in the push request. |
| 0508 | The push expiration (validFor) parameter was not included in the push request. |
| 0509 | Invalid title. |
| 0510 | The read icon URL is not a valid URL. |
| 0511 | The unread icon URL is not a valid URL. |
| 0512 | The content URL is not a valid URL. |
| 0513 | The validFor parameter is not valid. |
| 0514 | The value for validFor parameter is not between the minimum and maximum allowed values (7200 < value < 86400). |
| 0515 | The SID has expired or is not active. |
| 0516 | The SID has exceeded the daily limit for push requests. |
| 1000 | The system is currently unavailable. |
