A client-side push-enabled app runs on a device. It uses the Push Service to communicate with a server-side app, called a push initiator. Before you develop your own push-enabled app, you may find it helpful to try out the Push Capture sample app available on GitHub.
To develop and test a client-side push-enabled app, you need the following:
Server-side push initiator
The application ID and PPG URL for your server-side push iniator
If your app will send pushes only through BES10 or BES12, you don't need to register.
BlackBerry 10 WebWorks SDK 2.0 or later
A BlackBerry 10 device with access to a wireless network
Register to use the Push Service
You need to be registered to test your client-side push app. Fill out the BlackBerry Push Service Evaluation Form.
If you are creating an enterprise app that sends pushes only through BES10 or BES12, you don't need to register.
When your application is approved, you receive an email that confirms your registration details and provides the following information:
- Account Administration Portal
- Portal URL: https://cpadmin.pushapi.eval.blackberry.com/mss/CP_login
- Portal Username: <your email address>
- Portal Password
- Server Configuration Details
- Application ID
- Push Password
- Content Provider ID (CPID)
- Account Expiration Date
- Push URL: https://cp<your CPID>.pushapi.eval.blackberry.com
- Client Configuration Details
- Application ID
- Push Registration URL: http://cp<your CPID>.pushapi.eval.blackberry.com
- Push Port
The Application ID is the same for your server-side and client-side apps. You can ignore the Push Port because it is not required for BlackBerry 10 push apps.
Add the Push Service plugins to your project
You can add a plugin from the command line or using the SDK web tool. With either method, the plugin gets copied to your project's plugins folder and the required <feature> element gets added to your app's config.xml file. The next time you build your app, the contents of the plugin are packaged together with your other app resources.
To add the plugins from the command line:
- Open a command prompt in your app's project folder.
- Run the following
webworks plugin add com.blackberry.push webworks plugin add com.blackberry.invoked
To add the plugins using the SDK web tool:
- With your project open in the SDK web tool, in the navigation panel, click Plugins.
- In the Plugin Name or URL field, type com.blackberry.push and then click Add plugin.
- Repeat the previous step for the com.blackberry.invoked plugin.
Update your config.xml file
Before you can use the Push Service APIs with your app, you also need to update your app's config.xml file with the following statements.
Add an entry for the invoke events that your app receives for push
<!-- config.xml --> <!-- Need to put an invoke entry here for push. The ID here must match the invokeTargetId that is passed 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 Push Service object.
The action tag is set to bb.action.PUSH. This value indicates that the invocation relates specifically to push messages. The event listener in the sample app 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.
To allow your app to be opened from BlackBerry Hub
notifications, add the following statements.
<!-- config.xml --> <!-- Have an invoke entry here for when a user taps a notification in the BlackBerry Hub. This will cause the app to open. --> <rim:invoke-target id="sample.pushcapture.invoke.open"> <type>app</type> <filter> <action>bb.action.OPEN</action> <mime-type>text/plain</mime-type> </filter> </rim:invoke-target>
The action tag is set to bb.action.OPEN. This value indicates that the invocation relates to an open invoke event. In the sample app, 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 app 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.
Last modified: 2015-06-11