5. Unsubscribing from a Subscription
There are two ways a subscriber can unsubscribe from
a Web Signal. The subscription service can provide them with a link on
a website that allows them to unsubscribe, or the service can provide
them with a link to the RIM’s Web Signals site to see a list of all of
their subscriptions and they can unsubscribe from there.
To give subscribers access to a link that allows
them to see all of the Web Signals they’re subscribed to, use the
following URL:
http://[push-domain]/mss/PM_sublist
As an example, for a North American subscriber, you would use
http://push.na.blackberry.com/mss/PM_subList
Because RIM uses information provided by the device
browser to identify the mobile user, the URL must be accessed from the
user’s BlackBerry device. Figure 8 shows the subscriptions list for the particular device.
Note
The
subscriber list URL is case sensitive. It must be entered exactly as
shown to view the list of Web Signals to which the device is subscribed. |
To unsubscribe a subscriber from a Web Signal, the
push application must provide subscribers with the means to request to
be removed from the subscriber list. After the push application
receives the notification from the subscriber, it would submit the POST
request to the RIM Push Infrastructure with the following URL:
https://[push-domain]/mss/PM_puidDereg?sid=[SID]&
pass=[SID-Password]&puids=[PUID-List]
More than one subscriber can be unsubscribed at a
time, so it might be best to accept unsubscription requests from
subscribers then submit the list to RIM in a batch periodically via the
Deregistration request. Table 11 provides a description for each of the parameters for the unsubscribe URL.
Table 11. Web Signals Deregistration Request URL Parameters
| 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. |
| PUID-List | Comma-separated
list of subscriber PUIDs to which the content is delivered. The push
application can unsubscribe all users by using ALL_USERS for this
parameter. |
For a North American subscriber to the mywebsignal Web Signal, the unsubscribe URL would be
https://push.na.blackberry.com/mss/PMpuidDereg
?sid=mywebsignal&pass=mypassword
&puids=someuser@somecompany.com
To unsubscribe a batch of subscribers, include each subscriber in a comma-separated list:
https://push.na.blackberry.com/mss/PM_puidDereg
?sid=mywebsignal&pass=mypassword
&puids=someuser@somecompany.com,
anotheruser@abc.com,yetanotheruser@def.com
All subscribers can be unsubscribed using the following URL:
https://push.na.blackberry.com/mss/PM_puidDereg
?sid=mywebsignal&pass=mypassword
&puids=ALL_USERS
It is hard to think of a reason why a subscription
service would want to unsubscribe all users unless the service were
being shut down or was in beta mode and wanted to start over, but the
capability is there.
If the RIM push infrastructure is able to
successfully process an unsubscription request, the server responds
with a JobID—an ID that uniquely identified the request. The job ID
identifies the push request for debugging purposes or if the content
provider needs to open an investigation with RIM. If the request is
unsuccessful, the system returns rc=some-value, where some-value is one of the response codes listed in Table 12.
Table 12. Web Signals Deregistration Request Response Codes
| Response Code | Description |
|---|
| 0400 | A SID was not provided in the request. |
| 0401 | A SID Password was not provided in the request. |
| 0402 | The request does not contain at least one PUID. |
| 0403 | Authentication failed. |
| 0404 | The specified SID does not have any subscribers, so there is nobody to unsubscribe. |
| 0405 | The SID has expired or is not active. |
| 1000 | The system is currently unavailable. |
