Client-side apps

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.

Prerequisites

To develop and test a client-side push-enabled app, you need the following:

Item Details

Server-side push initiator

To test your client-side push-enabled app, you need a server-side push initiator. You can choose the library that you want to use to develop your server-side app. Some possibilities are: the Push Service SDK, NodeJS, and JavaScript.

The application ID and PPG URL for your server-side push iniator

After you register your push app with BlackBerry, you get this information by email. For more information about registering, see Push Service and the Push Service Evaluation Form.

If your app will send pushes only through BES10 or BES12, you don't need to register.

Client-side library

BlackBerry 10 WebWorks SDK 2.0 or later

BlackBerry device

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

Before you can use the Push Service APIs with your app, you need to add the following plugins to your project:
  • com.blackberry.push
  • com.blackberry.invoked

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:

  1. Open a command prompt in your app's project folder.
  2. Run the following commands:
    webworks plugin add com.blackberry.push
    webworks plugin add com.blackberry.invoked

To add the plugins using the SDK web tool:

  1. With your project open in the SDK web tool, in the navigation panel, click Plugins.
  2. In the Plugin Name or URL field, type com.blackberry.push and then click Add plugin.
  3. 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.

  1. Add an entry for the invoke events that your app receives for push messages.
    <!-- 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.

  2. 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



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus