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|
|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.
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.
BlackBerry 10 WebWorks SDK
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:
|Images||This folder contains the images for the sample application.|
|Styles||This folder contains the CSS files for the sample application.|
Configure the sample application
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
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, 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.
- 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.
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
<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
<!-- config.xml --> <!-- Need to put an invoke entry here for push. --> <!-- The id here must match the invokeTargetId passed in --> <!-- one of the ops to blackberry.push.PushService.create. --> <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.
<!-- bar-descriptor.xml --> <!-- Have an invoke entry here for when a notification is clicked on <!-- in the BlackBerry Hub. This will cause the application to be opened --> <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.