Developing a push-enabled app in C++

You can use our sample application to learn how to develop your own push-enabled application. Our 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.

Our sample application accepts push messages with the following types of content and content-type HTTP headers. 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).

  • 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 our sample application for testing purposes. You just need to indicate that you're not subscribing with the Push Service SDK when you configure our sample application. For details, see Configure our sample application.

Requirements

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, you must register with BlackBerry. 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 Enterprise Service only, you don't need to sign up to use the Push Service.

Client-side library

BlackBerry 10 Native SDK

BlackBerry device
  • BlackBerry 10 OS
  • 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 Native SDK

Download and build our sample application

To download our sample application, visit the Cascades sample apps and look for the Push Collector application in the Device and Communication section. The .zip file that you download contains two folders: 10.0 and 10.2.

The 10.2 folder contains our headless sample application that runs on BlackBerry 10.2. Our application shows you how to use a headless application to receive and process a push message. The 10.2 folder contains three projects. The projects are bundled together into one .bar file to make the overall Push Collector application.

  • pushCollector: This project is the UI for our sample application, and contains the code which is responsible for configuring our application, creating and destroying channels, and displaying push messages.
  • pushCollectorCommon: This project builds a shared object library that contains common code used by both the UI part and the headless part of our sample application.
  • pushCollectorHeadless: This project is the headless application that runs in the background. It contains the logic to create and destroy channels, and receive and accept push messages.

The 10.0 folder contains our sample application that runs on BlackBerry 10.1 and earlier. Our application in the 10.0 folder also shows you how to receive and process a push message, but it's not a headless application.

The readme.txt file in the .zip file contains the instructions that you need to follow to build and deploy our sample application on a BlackBerry device.

Configure our sample application

When you run our sample application for the first time, you need to specify some configuration information, including the information from the confirmation email message that you received if you signed up with BlackBerry 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.

You need to build and deploy our sample application to a BlackBerry device before you configure it. For information about building and deploying our application, visit the Cascades sample apps.

  1. Start our sample application.
    The configuration screen appears.
    Screen showing configuration options for our sample application.
  2. In the Mode drop-down list, perform one of the following actions:
    • Click Public/BIS if you're using the Push Service without the BlackBerry Enterprise Service.
    • Click Enterprise/BDS if you're using the Push Service with the BlackBerry Enterprise Service.
  3. 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.
  4. In the Application ID field, perform one of the following actions:
    • Type the application ID that is specified in the confirmation email message that you received from BlackBerry.
    • If you're using the Push Service with the BlackBerry Enterprise Service, and the Subscribe with Push Service SDK check box is selected, type a unique application ID of your choosing. If the Subscribe with Push Service SDK isn't selected, you can't type an application ID. In this case, the Push Service APIs create an application ID for you automatically.
    Our 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, use the providerApplicationID parameter of the PushService() constructor.
  5. In the PPG URL field, type the PPG base URL specified in the confirmation email message. If you're using the Push Service with the BlackBerry Enterprise Service, you don't need to type a URL.

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

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

  7. Click the Launch Application on New Push check box if you want to start our 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 our application when a new push message arrives. If the check box is unchecked, and our application isn't running, it won't receive the push message.
  8. Click Save.
    Our sample application stores the configuration in the database, and calls createSession() to create a push session. If the createSession() call is successful, our application calls registerToLaunch() or unregisterFromLaunch() 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 Starting our sample application in the background.

Update your bar-descriptor.xml file

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

  1. Add a permission statement for the Push Service so that your application can work with push messages. If you're using the Push Service with the BlackBerry Enterprise Service, you don't need to add the permission statement.
    <permission system="true">_sys_use_consumer_push</permission>
  2. Add the following permission statement so that your application can run as a headless application.
    <permission system="true">_sys_run_headless</permission>
  3. Add the following two entry points. The first entry point is used for the UI part of your application, and the second entry point is used for the headless part of your application.
    <entryPoint id="PushCollectorEP">
          <name>Push Collector</name>
          <entryPointType>Qnx/Elf</entryPointType>
    </entryPoint>
        
    <entryPoint id="PushCollectorHeadlessEP">
          <name>Headless</name>
          <entryPointType>Qnx/Elf</entryPointType>
     </entryPoint>
  4. Add your headless application as an asset in the configuration tags, and modify the entry points of the assets. The UI part of your application will refer to the entry point for the UI, and your headless application will refer to the entry point for the headless application.
    <configuration name="Default">
        <platformArchitecture>armle-v7</platformArchitecture>
        <asset entryPointId="PushCollectorEP" 
          path="arm/o.le-v7-g/pushCollector" 
          entry="true" type="Qnx/Elf">pushCollector</asset>
        <asset entryPointId="PushCollectorHeadlessEP" 
          path="${workspace_loc:/pushCollectorHeadless/arm/
            o.le-v7-g/pushCollectorHeadless}" 
          type="Qnx/Elf">pushCollectorHeadless</asset>
        <asset path="${workspace_loc:/pushCollectorCommon/arm/
            libpushCollectorCommon.so}" 
          type="Qnx/Elf">lib/libpushCollectorCommon.so.1</asset>
    </configuration>
  5. Add an entry for the invoke event that will be handled by the headless part of your application.
    <!-- Need to put an invoke entry here for push -->
    <!-- The id here must match the invokeTargetID in the PushService 
    <!-- constructor -->
    <invoke-target id="com.example.pushCollector.invoke.push">
       <invoke-target-type>application.headless</invoke-target-type>
       <invoke-target-name>Headless Application</invoke-target-name>
       <entry-point-id>PushCollectorHeadlessEP</entry-point-id>
       <filter>
          <action>bb.action.PUSH</action>
          <mime-type>application/vnd.push</mime-type>
       </filter>
       <filter>
          <action>bb.action.system.STARTED</action>
          <mime-type>application/vnd.blackberry.system.event.STARTED
          </mime-type>
          <property var="uris" value="data://local"/>
       </filter>
       <filter>
          <action>bb.action.START</action>
          <mime-type>*</mime-type>
          <property var="uris" value="headless:"/>
       </filter>
       <filter>
          <action>bb.action.COMMAND</action>
          <mime-type>text/plain</mime-type>
       </filter>
    </invoke-target>

    Note the values for the following tags:

    • invoke-target id: The value must match the invokeTargetID that's passed into the call to the PushService() constructor. For more information about the invokeTargetID and PushService() in our sample application, see Creating a PushService object.
    • invoke-target-type: The value must be application.headless for a headless application.
    • entry-point-id: The value must match the entryPointId for a headless application that you created in the previous step.

    Also note the following values for the action tags:

    • bb.action.PUSH: This value indicates that the invoke relates specifically to push messages. The onInvoked slot in our application uses the BB_PUSH_INVOCATION_ACTION #define (which is equivalent to bb.action.PUSH) to check that the invoke request is a push message. For more information about the push invoke request, see Receiving a push message.
    • bb.action.system.STARTED and bb.action.START: These values are used to start the headless application from the UI application.
    • bb.action.COMMAND: This value is used by the UI to send an invoke event to the headless application to perform an operation, such as createSession() and createChannel(). The headless application contains the logic to perform the operations.
  6. 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. -->
        <invoke-target id="com.example.pushCollector.invoke.open">
          <invoke-target-type>application</invoke-target-type>
          <entry-point-id>PushCollectorEP</entry-point-id>
          <filter>
             <action>bb.action.OPEN</action>
             <mime-type>text/plain</mime-type>
          </filter>
        </invoke-target>

    Note the values for the following tags:

    • invoke-target-type: The value must be application.
    • entry-point-id: The value must be PushCollectorEP so that the UI application is launched for this invoke request.
    • action: The value is set to bb.action.OPEN. This value indicates that the invoke relates to an open invoke request. In our sample application, an open invoke request occurs when a user taps a notification for a push message in the BlackBerry Hub. The onInvoked slot in our application uses the BB_OPEN_INVOCATION_ACTION #define (which is equivalent to bb.action.OPEN) to check that the invoke request is an open invoke request. For more information about the open invoke request, see Handling notifications in the BlackBerry Hub.

Last modified: 2014-09-30



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

comments powered by Disqus