Subscription query request message

With either level of service in the Push Service, you can request information about the status of a subscriber. The subscription query is an extension to the PAP standard, and it is available to all content providers who use the Push Service.

With a <subscriptionquery-message> request, you can explicitly poll the Push Service database to identify which BlackBerry devices are no longer subscribed. You can then deactivate those subscriptions in your database. When you remove or deactivate those subscriptions, you shorten your push cycle and then you can push more messages before reaching your push quota.

To understand the results of a subscription query, you need to understand how the Push Service responds when a BlackBerry device user no longer has your client application, either because the user removed the application without cancelling the subscription, or changed BlackBerry devices.

After you send a push message with confirmed reliability, the following events happen for each addressed BlackBerry device without your application:
  • If the push fails to reach a BlackBerry device with your application on it, it will begin a counter.
  • If a successful push or new registration to the PPG is not delivered within 60 days, the subscription becomes inactive (unsubscribed). This is only a status change, and does not remove the subscription.
  • The Push Service no longer sends data to the application on the device.
  • If the Push Service did send the data, the device user would be charged for the data even though the BlackBerry device had discarded the data because the intended application is not there.
  • After the Push Service removes the subscription in its records, any subsequent push messages will not be sent for that application to that device.

For content providers with the Push Plus level of service, if you send the status query for a PIN or token without a client application, the Push Service sends an error back to you.

All content providers can use a subscription query request to query the status of up to 10,000 PINs or tokens. The Push Service returns the status for each PIN or token so that you can process it accordingly. You can also request a specific status (active or suspended), and the Push Service returns a list of PINs or tokens that have that status. You should deactivate any PINs or tokens in your Push Initiator that the Push Service doesn't record as active or suspended.

Here's an example of a subscription query request. The status-value="active" in the <status/> element means that the subscription request returns only addresses that currently have the status of "active."

<?xml version="1.0"?>
 <!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 2.1//EN"
"http://www.openmobilealliance.org/tech/DTD/pap_2.1.dtd">
<bpds version="1.0">
	<subscriptionquery-message pushservice-id="32-C9ViiTf34OTf7yigCHZZ">
		<status status-value="active"/>
	</subscriptionquery-message>
</bpds>
There are three subscription statuses that may be returned after submitting the query:
  • active: The subscriber is active on the PPG and is able to receive pushes.
  • suspended: The subscriber's account has been suspended by the Content Provider and is therefore unable to receive pushes.
  • unsubscribed: The subscriber is inactive on the PPG and cannot receive pushes.

Here's an example of a response to a supplied PIN or token request.

<?xml version="1.0"?>
 <!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 2.1//EN"
"http://www.openmobilealliance.org/tech/DTD/pap_2.1.dtd">
<bpds version="1.0">
    <subscriptionquery-response pushservice-id="32-C9ViiTf34OTf7yigCHZZ">
        <subscriptionquery-result
            event-time="2011-01-14T14:11:00Z"
            code="xxxx"
            desc="XXXXXXXXXXXXXXX"/>
        <subscriptionquery-detail
            status="active"
            event-time="2011-01-01T00:00:00Z">
            <address address-value="111111111"/>
        </subscriptionquery-detail>
        <subscriptionquery-detail
            status="suspended"
            event-time="2009-08-15T12:54:00Z">
            <address address-value="222222222"/>
        </subscriptionquery-detail>
        <subscriptionquery-detail
            status="unsubscribed"
            event-time="2010-01-01T17:52:00Z">
            <address address-value="333333333"/>
        </subscriptionquery-detail>
        <subscriptionquery-detail
            status="unknown"
            event-time="2011-01-14T14:11:00Z">
            <address address-value="444444444"/>
        </subscriptionquery-detail>
    </subscriptionquery-response>
</bpds>