2. BlackBerry Push Infrastructure at Work:
Introduction to the BlackBerry Push API
• Overview
• Architecture
• Implementation
• Security & Reliability
• Requesting Access
3. Why use Push?
• The data is on the device when the user needs it
• Data is delivered as soon as it is available
• Application is always actively listening for data arrival
• User can be immediately notified of new data
• Audio alert, vibration, blinking LED, pop-up dialog,
icon change, banner notification
• The user experience is that it just happened
• appearance of zero latency
4. Push Vs Poke-Pull
• Push
• Allows the delivery of content to a device without the device having to
request it
• The data is sent to a port on the device where an application is listening
for it
• Push is generally server based/mediated
• Push Initiator
• The Push Initiator submits a request to the Hosted Data Push Service
• Contains delivery instructions and the payload
– Delivery instructions describe where and how the data is to be
sent
– The payload may be any type of data
• Poke-and-Pull
• Poke: a notification and URL are pushed to a device
• Pull: the device fetches the content at the URL
• Less efficient than true push
5. BlackBerry Push API
• Compare to Polling
• Client periodically asks a server if an event of interest has
occurred
• Inefficient – increases OTA costs and traffic
• there may be many polling attempts to fetch a single
event
• Delays in getting data due to polling latency (interval)
• Depending on polling interval, received data may be
outdated
• Wastes battery life checking whether an event of interest has
occurred
• Generates extra server traffic and load for your application
• 1,000,000 devices x 12 polls/hr x 24 hours =
288,000,000 requests per day
• Doesn’t scale
6. BlackBerry Push API
• Provides a transport infrastructure for Server to Device pushed
data
• Primary focus on consumer applications
• Alerts
• Replace polling to improve performance & reduce costs
• Poke-Pull model
• Event driven systems
• Near real-time notifications
• Can be used for enterprise deployments
• Cross company applications
• Enterprises without a BlackBerry Enterprise Server
7. Benefits
• Provides information immediately
• Optimizes network efficiency
• Preserves the battery life
• Reduces complexity for developers
• Improves developer margins
8. Architecture
• Pushes are initiated on the Server
• Server side application is required
• Server to Server interface for the Push Initiator
• BlackBerry Infrastructure is the middleware
• Sends data to a specified port on the Device
• Client side Java application required to receive the push
• Uses PAP 2.2 Standard push protocols
• OMA-WAP-TS-PAP-V2_2-20071002-C
• Requests are HTTP XML requests
• Supported requests:
• Submit Push
• Cancel Push
• Query for Status
• Response:
• Result notification
10. Push Workflow
Mobile Client
Push Request
Response BlackBerry
Infrastructure
1
2
3
4
5
6
Push
Push
Initiator
1. Server sends PAP Push which
contains a list of specified devices
2. BlackBerry Infrastructure sends
response to Server and queues
request
3. BlackBerry Infrastructure pushes data
to specified devices
4. Each device sends ACK to
BlackBerry Infrastructure
5. BlackBerry Infrastructure sends
notification to Server
6. Server sends Read notification to
BlackBerry Infrastructure
11. About the Push
• Push sent to user’s PIN
• Maximum payload is 8 KB
• Types of Push:
• Point to Point (Single PIN)
• Multicast (List of PINs)
• Broadcast (All PINs by application)
• BlackBerry Infrastructure will attempt to deliver the
message until expiry time
• Automatic retries if device is out of coverage
• Expiry time can be configured to a maximum of 8 hours
12. Sample Push Request
--PMasdfglkjhqwert
Content-Type: application/xml
<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 2.1//EN"
"http://www.openmobilealliance.org/tech/DTD/pap_2.1.dtd">
<pap>
<push-message push-id="999999999"
source-reference="AAAAAAAAAAAA"
deliver-before-timestamp="2008-09-31T13:30:00Z"
ppg-notify-requested-to="notify_url_path">
<address address-value="PIN00001"/>
<address address-value="PIN00002"/>
<address address-value="PIN00003"/>
<quality-of-service delivery-method="confirmed"/>
</push-message>
</pap>
--PMasdfglkjhqwert
Content-Encoding: binary
Content-Type: text/html
Text or binary content to be delivered to BlackBerry device goes here.
--PMasdfglkjhqwert--
14. Sample Code: Push Request (2 of 2)
String papPush = “…”; //push message
outs = mdsConn.getOutputStream();
copyStreams(new ByteArrayInputStream(output.getBytes()), outs);
mdsConn.connect();
ins = mdsConn.getInputStream();
ByteArrayOutputStream response = new ByteArrayOutputStream();
copyStreams(ins, response);
int httpCode = mdsConn.getResponseCode();
if( httpCode != HttpURLConnection.HTTP_ACCEPTED && httpCode != HttpURLConnection.HTTP_OK )
{
//Push failed
}
else
{
//HTTP Connection successful
//Parse the response notification message to confirm successful push (not shown here)
}
} catch(Exception ex)
{
errorCode = ex.getClass().getName();
} finally { /* close input and output streams and close the connection */ }
15. Sample Cancel Request
• Any queued pushes can be cancelled
• Previously pushed content cannot be recalled
• Result notification sent from BlackBerry Infrastructure
– Confirms for which devices the pushes were and
were not cancelled
• Uses WAP PAP <cancel-message> element
16. Sample Cancel Request
Content-Type: application/xml
<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 2.1//EN"
"http://www.openmobilealliance.org/tech/DTD/pap_2.1.dtd">
<pap>
<cancel-message push-id="999999999">
<address address-value="PIN00001"/>
<address address-value="PIN00002"/>
<address address-value="PIN00003"/>
</cancel-message>
</pap>
17. Status Request
• Query for the status of a submitted request
• Status is maintained for 24 hours
• If multiple recipients
• response will contain a status for all of them
• Status is a snapshot
• i.e. reflective only of the current moment in time
• Uses WAP PAP <statusquery-message> element
18. Sample Status Request
Content-Type: application/xml
<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 2.1//EN"
"http://www.openmobilealliance.org/tech/DTD/pap_2.1.dtd">
<pap>
<statusquery-message push-id="999999999">
</statusquery-message>
</pap>
19. Response Notifications
• Sent to the Server URL if specified, none otherwise
• Be prepared to handle these – there will be many of
them
– Quality of Service Levels
• Application
– Message reached the application
• Transport
– Message reached the device
• None
– Fire and forget
20. Listening for Push
• User installs mobile application
• On first run, mobile application registers with
BlackBerry Infrastructure
– Creates HTTPS connection to Infrastructure URL
• Headers identify PIN and PSID
• BlackBerry Infrastructure validates the mobile
application
• BlackBerry Infrastructure returns pass/fail to mobile
application
21. Sample Code: Listening for Push
StreamConnection stream;
InputStream ins;
MDSPushInputStream pushInputStream;
//use the port assigned to your application
StreamConnectionNotifier notifier = (StreamConnectionNotifier) Connector.open("http://:110");
while( !_stop )
{
stream = _notifier.acceptAndOpen(); //blocking operation
input = stream.openInputStream();
pushInputStream = new MDSPushInputStream((HttpServerConnection) stream, input);
DataBuffer buffer = new DataBuffer();
byte[] data = new byte[ 256 ];
int chunk = 0;
while( -1 != (chunk = input.read(data)) )
{
buffer.write(data, 0, chunk);
}
/* … process the data on the DataBuffer ... */
// Signal that we have finished reading.
pushInputStream.accept();
}
22. Security
• BlackBerry Infrastructure Authentication
• Push Initiator is authenticated to the BlackBerry Infrastructure
• Push Initiator can only push to its mobile application
• 1:1 relationship between Push Initiator and mobile application
• Push Initiator can only push to devices registered for their
application
• Each push request is authenticated to BlackBerry Infrastructure
• Unique listening port for each application
• BlackBerry Infrastructure does not encrypt data
• Expects that payload data will already be encrypted by Push
Initiator
• Content Provider Authentication
• Mobile application should be authenticated to the Push Initiator
23. Reliability
• Choose the appropriate QoS for your application
• There are tradeoffs for performance and battery life
• Be sure to handle all request failures in your application
• Result notifications
• Your server app must be prepared to handle these, if you
request them
• Server outages - RIM infrastructure will retry deliveries … for
a while
• Always provide an unsubscribe option in your device application
• Highest reliability can be achieved by application
acknowledgement direct to your server
24. Requesting Access
• Register at www.blackberry.com/pushapi
• Sample code provided on registration approval
• Content Provider tests the push service
• Given access to the evaluation infrastructure
• Research In Motion validates the Content Provider’s client and
server-side applications
• Ensuring development guidelines are met
• Service is moved into production
• Once all requirements are met
• Only available to ISV Alliance Partners
• To become an ISV Alliance partner visit
www.blackberry.com/allianceapplication
• Contact for service costs
