Developing a push-enabled application

You can use the sample application to learn how to develop your own push-enabled application. The sample application shows you how to use the Push Service APIs to connect with the Push Initiator, and receive push messages on a BlackBerry device.

The sample application accepts push messages with the following types of content. If you're using the Push Service SDK as the server-side library, the SDK automatically specifies the type of content in the header of the push message. In your application, you can send up to 8 KB of any type of content (images, text, or audio).

Type of content	Content-type HTTP header
Text	text/plain
HTML	text/html
XML	application/xml
Image	image/jpeg, image/gif, image/png

If you implemented a Push Initiator that doesn't use the Push Service SDK, or your Push Initiator only uses the low-level APIs without subscription support from the SDK, you can still use the sample application for testing purposes. You just need to indicate that you're not going to subscribe with the Push Service SDK when you configure the sample application. For details, see Configure the sample application.

Requirements

Item	Requirement
Server-side library	We recommend using the Push Service SDK with our sample push-enabled application, and with push-enabled applications that you develop. To use the Push Service with the BlackBerry Internet Service, you must register with Research In Motion. When you sign up, you receive a confirmation email message that contains information that your application uses to create a session and create a channel. For more information about signing up, visit Push Service. If you plan to develop a push solution that delivers content using the BlackBerry Device Service only, you don't need to sign up to use the Push Service.
Client-side library	BlackBerry 10 WebWorks SDK
BlackBerry device	BlackBerry 10 OS BlackBerry Internet Service Data plan with your wireless service provider that provides a connection to the Wi-Fi network or mobile network
Sample push-enabled application	BlackBerry 10 WebWorks SDK

Download and build the sample application

To download the sample application, visit the samples repository. The repository contains the source code and associated files for the application. The README.md file in the repository contains the instructions that you need to follow to build and deploy the sample application on a BlackBerry device.

The repository contains the following folders:

Folder	Description
Images	This folder contains the images for the sample application.
Scripts	This folder contains the JavaScript files for the sample application.
Styles	This folder contains the CSS files for the sample application.

Configure the sample application

When you run the sample application for the first time, you need to specify whether the PPG is the BlackBerry Internet Service or the BlackBerry Device Service. If you're using the BlackBerry Internet Service as the PPG, you also need to provide the information from the confirmation email message that you received when you signed up with Research In Motion to use the Push Service. When you develop your application, you can code this information into your application instead of displaying it in a configuration screen and requiring the user to type the information.

Before you begin: You need to build and deploy the sample application to a BlackBerry device before you configure it. For information about building and deploying the application, visit the samples repository.

Start the sample application.
The configuration screen appears.
Click Public/BIS if the PPG is the BlackBerry Internet Service or Enterprise/BDS if the PPG is the BlackBerry Device Service.
Clear the Subscribe with Push Service SDK check box if one of the following is true:
- You implemented a Push Initiator that doesn't use the Push Service SDK.
- Your Push Initiator only uses the low-level APIs without subscription support from the Push Service SDK.
- You’re using the low-level sample Push Initiator that comes with the Push Service SDK.
If the Subscribe with Push Service SDK check box is selected, in the Application ID field, perform one of the following actions:
- If you use the BlackBerry Internet Service as the PPG, type the application ID that is specified in the confirmation email message that you received from RIM.
- If you use the BlackBerry Device Service as the PPG, type a unique application ID of your choosing. If you clear the Subscribe with Push Service SDK check box, you can't type an application ID. In this case, the Push Service APIs create an application ID for you automatically.
The sample application uses the application ID when it creates the PushService object to perform push-related operations. To specify the application ID in your application, you use the appId field of the options object that is passed into the call to the static PushService.create() function.
If you use the BlackBerry Internet Service as the PPG, in the PPG URL field, type the PPG base URL specified in the confirmation email message. The sample application uses this URL to create a channel to the PPG. For an evaluation environment, the URL is http://cp<cpid>.pushapi.eval.blackberry.com, where <cpid> is your content provider ID. For a production environment, the URL is http://cp<cpid>.pushapi.na.blackberry.com.
If the Subscribe with Push Service SDK check box is selected, in the Push Initiator URL field, type https://<server_address>/high-level-sample, where <server_address> is the address of the server where the high-level sample Push Initiator is deployed. The Push Service SDK includes the high-level sample Push Initiator that is deployed on the Apache Tomcat server. The URL must be accessible from the Internet.
Depending on how you implemented your Push Initiator, you might want to use your own Push Initiator that handles subscriptions instead of using one of our sample Push Initiators.
Click the Launch Application on New Push check box if you want to start the sample application if it isn't already running when a new push message arrives. Leave the check box unchecked if you don't want to start the sample application when a new push message arrives. If the check box is unchecked, and the application isn't running, it won't receive the push message.
Click Save.
The sample application stores the configuration in the database, and calls the static PushService.create() function to attempt to create a PushService object. If the PushService.create() call is successful, the application calls launchApplicationOnPush() with true or false depending on the selection you made for the Launch Application on New Push option on the configuration screen. For details about these calls, see Creating a PushService object and Start the sample application in the background.

Register the sample application

After you configure the sample push-enabled application, you need to register the application to create a push channel to the PPG to receive push messages.

If you chose to subscribe with the Push Service SDK when you configured the sample application, the Push Initiator requires a username and password that it authenticates before allowing the subscription. The sample application provides a Register dialog box where you can type any username and password.

To see the code in the sample push-enabled application that creates the channel and handles the subscription, see Creating a push channel.

Tap Register at the bottom of the device screen.

The Register screen appears.
If you chose to subscribe with the Push Service SDK, type any username and password in the Register screen.
Tap Submit.

Update your config.xml file

Before you can use the Push Service APIs with your application, you need to update your application's config.xml file with the following statements. The sample application already has these statements, so you don't need to add them before using the sample application.

Add a reference to the blackberry.push feature.
```
<feature id=”blackberry.push” />
```
Add a feature tag for blackberry.invoked. This feature tag relates to the handling of invoke events. A push message arrives at your application as an invoke event.
```
<feature id=“blackberry.invoked” />
```
If you are using the Push Service with the BlackBerry Internet Service, add a permission statement for the Push Service so that your application can work with push messages.
```
<rim:permissions>
   <rim:permit system=”true”>_sys_use_consumer_push</rim:permit>
</rim:permissions>
```
Add an entry for the invoke events that your application receives for push messages.
```

     

     
 <rim:invoke-target id="sample.pushreceiver.invoke.push">       
 <type>APPLICATION</type>       
 <filter>        
   <action>bb.action.PUSH</action>
   <mime-type>application/vnd.push</mime-type>       
 </filter>     
 </rim:invoke-target>
```
Note the value for the invoke-target id. This value must match the invokeTargetID that's passed into the call to the PushService.create() function. For more information about the invokeTargetID and PushService.create(), see Creating a PushService object.

Also note that the action tag is set to bb.action.PUSH. This value indicates that the invoke relates specifically to push messages. The event listener in the sample application also uses this value to check that the invoke event is a push message. For more information about the event listener and the push invoke event, see Receiving a push message.
Add an entry for an open invoke event that your application receives.
```

   
 <rim:invoke-target id="sample.pushcapture.invoke.open">
 <type>APPLICATION</type>
 <filter>
   <action>bb.action.OPEN</action>
   <mime-type>text/plain</mime-type>
 </filter>
 </rim:invoke-target>
```
Note that the action tag is set to bb.action.OPEN. This value indicates that the invoke relates to an open invoke event. In the sample application, an open invoke event occurs when a user taps a notification for a push message in the BlackBerry Hub. The event listener in the sample application also uses this value to check that the invoke event is an open invoke event. For more information about the event listener and the open invoke event, see Handling notifications in the BlackBerry Hub.