BlackBerry Push APIs (part 2) - Building an Application that Uses the BlackBerry Push APIs - Unsubscribing From the Push System, Pushing Data to a Subscriber

10/12/2013 3:18:46 AM

3.3 Unsubscribing From the Push System

When a subscriber no longer wants to receive content from the service, the device-side application must notify the RIM Push Infrastructure and, if the listener application registered with the push application, notify the push application as well. To unsubscribe with the RIM Push Infrastructure, the following URL must be used:

https://[push-domain]/mss/PD_subDereg?serviceid=[service-ID]

The push parameters are described in Table 4.

Table 4. BlackBerry Push API Deregistration URL Parameters
Registration Parameter	Description
Push-Domain	The regional domain that the push recipient resides in. Refer to Table 1 for the possible values for this parameter.
Service-ID	The unique ID for the push service; this value will be provided during registration of the service.

For a North American subscriber, the POST URL would look something like this:

https://pushapi.na.blackberry.com/mss/PD_subDereg?
serviceid=myAppName

The RIM Push Infrastructure responds with a string of encrypted data that the application must return (within a certain timeframe) to the RIM Push Infrastructure for the deregistration process to complete successfully. The return URL looks similar to the previous one except for the addition of the encrypted data to the end of the URL. The follow-up registration URL is performed via another HTTP POST and is in the following format, where [Encrypted-Data] is replaced with the content received from the server on the first request:

https://[push-domain]/mss/PD_subDereg?serviceid=[service-ID]
&[Encrypted-data]

If the RIM Push Infrastructure returned someencryptedvalue from the initial registration request, the subsequent POST URL looks like this:

https://pushapi.na.blackberry.com/mss/PD_subDereg?
serviceid=myAppName&someencryptedvalue

The RIM Push Infrastructure returns a response code, indicating the status of the request in the format of rc=some-value, where some-value is one of the response codes listed in Table 5.

Table 5. BlackBerry Push API Deregistration Request Result Codes
Response Code	Description
200	The deregistration was completed successfully.
10004	The deregistration process has already been completed by the user.
10005	The deregistration process has already been completed by the service provider.

The device-side application is also responsible for notifying the content provider service of the unsubscribe using whatever mechanism is appropriate for the application.

This concludes the discussion of the push receiver, device-side application. The remaining activities related to the BlackBerry Push APIs are all performed from the backend push application.

3.4 Pushing Data to a Subscriber

When the push application is ready to send data to one or more subscriber devices, the application must submit a push request to the RIM Push Infrastructure containing the data being delivered. The push request is a simple PAP request. Because the application merely pushes data to a destination application, the format of the push request is much simpler because many of the push parameters used for browser push don’t apply and are, therefore, not needed.

For a PAP push request, the message body is sent as a MIME multipart message, as shown in Figure 3. The MIME message contains an XML document that describes the push (the control entity), plus the data that is pushed to the destination device(s). The boundary shown in the figure is just a random series of characters that is not included anywhere as part of the message content. It distinguishes between the different parts of the MIME multipart message.

Figure 3. PAP Push Request Format

When pushing data to a subscriber, the push application uses the following URL for the HTTP POST request sent to the RIM Push infrastructure, where push-domain refers to one of domains listed in Table 1:

http://[push-domain]/mss/PD_pushRequest

The HTTP POST request must contain two header values: Content-Type and Authorization. The push application must set the Content-Type HTTP request header to tell the receiving service the format of the request. In the Content-Type header, the application can use any boundary string, as long as it is unique (not used anywhere else in the message). The following example just uses some random characters typed on the keyboard:

Content-Type:multipart/related; type="application/xml";
boundary=jausyhstaositate

In Java, the header can be set using the following code:

HttpURLConnection psConn =
  (HttpURLConnection)psUrl.openConnection();
psConn.setRequestProperty( "Content-Type", "multipart/related;
 type=\"application/xml\"; boundary=jausyhstaositate" );

The application delivers the credentials for the push request in the Authorization header. The credentials are passed as a Base64 encoded combination of the provider’s push service ID (PSID) and password (PSID:Password). To perform this operation in Java, use the following code:

String auth = "Basic " + new BASE64Encoder().encode((psid + ":"
+ pswd).getBytes());
psConn.setRequestProperty("Authorization", auth);

After the request headers are set up correctly, it’s time to format the content of the message. As shown in Figure 3, the first component of the push request is an XML control entity that describes the push request. A simple push-message control entity is shown here that defines a push request for a single device PIN:

<pap>
 <push-message push-id="UniquePushID" source-reference="PSID">
    <address address-value="DevicePIN1" />
  </push-message>
</pap>

To push to multiple devices, the push request would contain multiple address elements, as shown here:

<pap>
  <push-message push-id="UniquePushID" source-reference="PSID">
    <address address-value="DevicePIN1" />
    <address address-value="DevicePIN2" />
    <address address-value="DevicePIN3" />
  </push-message>
</pap>

If the application needed to push to all subscribers, the push request would look similar to the one shown here:

<pap>
  <push-message push-id="UniquePushID" source-reference="PSID">
     <address address-value="push_all" />
  </push-message>
</pap>

The application can specify additional (optional) elements/attributes in the control entity, as shown here:

<pap>
  <push-message push-id="UniquePushID" source-reference="PSID"
    ppg-notify-requested-to="someurl"
    deliver-before-timestamp="sometime" >
    <address address-value="DevicePIN1" />
    <quality-of-service delivery-method="confirmed" />
  </push-message>
</pap>

The supported attributes for the push-message control entity elements are defined in Table 5.

Table 5. PAP Push Push-Message Control Entity Elements/Attributes
Element	Attributes
<push-message>	push-id: A unique ID associated with this particular push request. The ID must be provided with any subsequent requests cancelling or requesting the status of the push request. The push application is responsible for generating this unique push-id. This is a required attribute for the push-message element. source-reference: The unique Push Service ID (PSID) assigned to the push service when it was registered with the RIM Push Infrastructure. The ID identifies the push content provider, the push application, and the port number the data is delivered to on the destination device. This is a required attribute for the push-message element. ppg-notify-requested-to: Specifies the URL that is triggered by the RIM Push Infrastructure when the push request has been processed. This is an optional attribute for the push-message element; if no value is provided, the push application is not notified when the pushed content has been delivered. deliver-before-timestamp: Specifies the date and time that the push must be delivered before. If the content is not delivered by this date/time, it is discarded by the RIM Push Infrastructure. The value provided here must be in Coordinated Universal Time (UTC). Example: ‘2009-02-11T11:00:00Z’ where the Z at the end of the string indicates UTC. This is a required attribute for the push-message element.
<address>	address-value: Specifies the address of one or more destination devices. The address-value must be a valid device PIN that has already been registered in the RIM Push Infrastructure for this push application. This is a required element for the push request.
<quality-of-service>	delivery-method: Specifies the delivery reliability for the push message. The attribute values defined below here define criteria for determining successful delivery of the push content. Possible values are: confirmed: A message is considered delivered when the content has been delivered to the destination application on the device. notspecified, preferconfirmed, or unconfirmed: A message is considered delivered when the content has been delivered to the destination device. In order to have a delivery notification sent to the push application, the request must also enable the ppg-notify-requested-to attribute defined above.

The following is an example of what the push message would look like when sent to the RIM Push Infrastructure:

--jausyhstaositate
Content-Type: application/xml; charset=UTF-8

<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 1.0//EN"
  "http://www.openmobilealliance.org/DTD/pap_1.0.dtd"
  [<?wap-pap-ver supported-versions="2.0,1.*"?>]>
<pap>
  <push-message push-id="UniquePushID" source-reference="PSID">
    <address address-value="DevicePIN1" />
  </push-message>
</pap>
--jausyhstaositate
CouponTitle="Really Great Deal"
CouponExpiry="September 12, 2009"
CouponDetails="Act now to receive 20% off on all products"
--jausyhstaositate

When the RIM Push Infrastructure has processed the push request, it returns an HTTP result code and an XML document containing information about the results of the request. The server returns either a 200 (OK) or a 202 (Accepted); any other status code indicates that there was a problem with the push. A sample of the XML document returned is shown in the following example:

Content-Type: application/xml
<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 1.0//EN"
"http://www.openmobilealliance.org/tech/DTD/pap_1.0.dtd">
<pap>
  <push-response push-id="UniquePushID"
    sender-address=" http://ws1.someserver.com/push_app"
    sender-name="RIM Push-Data"
    reply-time="2009-09-12T13:00:00Z">
    <response-result code="status-code" desc="Description" />
  </push-message>
</pap>

Table 6 lists the elements and the attribute values associated with each element in the response message.

Table 6. PAP Push Response Elements/Attributes
Element	Attribute/Description
<push-response>	Push-ID: The unique Push ID associated with the push request Sender-Address: The name of the server sending the response Reply-Time: The date and time (in Coordinated Universal Time [UTC]) that the reply was sent
<response-result>	Code: One of the status codes listed in Table 7 Desc: The description for the status code

Table 7 contains the list of PAP response status codes used by the push-response message and other response messages from the RIM push infrastructure.

Table 7. PAP Response Status Codes
Status Code	Description
1000	The request succeeded (the data reached the destination device).
1001	The request has been accepted for processing (the push request has been accepted by the server but has not been validated for delivery to the destination device).
2000	The request is invalid (malformed syntax).
2001	The requested action is forbidden or the request was refused.
2002	The specified PIN is not recognized.
2003	Address not found.
2004	The Push ID specified was not found for the provided push service.
2005	Capabilities mismatch.
2006	Required capabilities not supported by client.
2007	The Push ID specified is not unique.
2008	The Push ID was located, but cancellation is not possible.
3000	Internal server error.
3001	The server does not support the requested operation.
3002	Version not supported.
3003	The action is not possible because the message is no longer available.
3006	Transformation failure.
3007	Specified delivery method not possible.
4000	Service failure.
4001	Service unavailable.
4500	The request has expired.
4501	The request failed.
4502	The push request failed because the BlackBerry device listen port was closed.
5xxx	The mobile client aborted the operation.

The push application must parse the response message to determine the results of the push request. The application can also receive a notification when the data actually arrives on the device by specifying a URL in the ppg-notify-requested-to attribute of the push-message element in the push request.

When the application specifies a ppg-notify-requested-to URL in the push request, depending on the quality of service defined in the request, the RIM Push Infrastructure triggers the URL when the data arrives on the device (quality-of-service confirmed) or when the data arrives at the destination application (all other options for quality-of-service). Additionally, the PAP specification indicates that this mechanism can also notify when an error has occurred. Because there’s no guarantee that the RIM Push Infrastructure is able to deliver the push, the push application should use this mechanism to detect whether the push was delivered and, if the data is important enough to the subscriber, push the data again if it wasn’t delivered.

The response from the RIM Push Infrastructure is delivered in the form of a Result Notification Response message. This message is an XML control entity containing information about the status of the push message. The PAP specification indicates that the result message could be a MIME multipart message containing XML control entities from both the push service and the device, but RIM does not seem to support that option. A sample result notification message is shown here:

<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 1.0//EN"
"http://www.openmobilealliance.org/
tech/DTD/pap_1.0.dtd">
<pap>
  <resultnotification-message push-id="UniquePushID"
    sender-address="https://www.pushdatadomain/paprequestpage"
    sender-name="RIM Push-Data"
    message-state="Message State"
    code="1000"
    desc="OK">
    <address address-value="DevicePIN1" />
  </resultnotification-message>
</pap>

Table 8 lists the possible elements and attributes for the response message.

Table 8. PAP Resultnotification-Message Elements/Attributes
Element	Attribute/Description
<resultnotification-message>	Push-ID: The unique Push ID associated with the push request. Sender-Address: The URL for the server sending the response. Sender-Name: A descriptive name for the response sender. Message-State: One of the Message state options listed in Table 9. Code: One of the status codes listed in Table 7. Desc: The description for the status code. Received-Time: The date and time (in Coordinated Universal Time [UTC]) when the push request was received by the RIM Push Infrastructure. Event-Time: The date and time (in Coordinated Universal Time [UTC]) that the push request reached its completed state.
<Address>	Address-Value: The device PIN for which the response is associated.
<quality-of-service>	Delivery-Method: If a quality of service element was included in the original push request, it is included in the response.

Table 9 contains the list of possible Message State attributes for the response message.

Table 9. Message State Options
Message State	Description
Aborted	The destination BlackBerry device aborted the delivery process.
Cancelled	The push message was cancelled by the content provider before the content was delivered to the destination BlackBerry device.
Delivered	The push content was successfully delivered to the destination BlackBerry device.
Expired	The push message reached its maximum age (defined in seconds in the push request) before it could be delivered by the RIM Push Infrastructure.
Pending	The push message is still in queue, it has not been processed yet.
Rejected	The push message was not accepted for delivery by the RIM Push Infrastructure.
Timeout	The delivery process timed-out.
Undeliverable	The push message cannot be delivered to the destination BlackBerry device.
Unknown	An unknown error has occurred.

The push application is responsible for responding to the RIM Push Infrastructure acknowledging receipt of the result notification. A sample resultnotification-response message is shown here:

<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 1.0//EN"
"http://www.openmobilealliance.org/tech/DTD/pap_1.0.dtd">
<pap>
  <resultnotification-response push-id="UniquePushID"
    code="1000" desc="OK" />
</pap>

Table 10 contains a listing of the possible attributes for the resultnotification-response element in the Result Notification Response message.

Table 10. PAP Push Resultnotification-Response Element Attributes
Attribute	Description
Push-id	A unique ID associated with a particular push request. The push application is responsible for generating this unique push-id and including it with the initial push request.
Code	One of the result codes listed in Table 7.
Desc	The textual description for the result code.

It’s likely that the push application would always respond with a 1000, indicating that the response was received successfully.