The Guide for using Push technology in your Enterprise Apps, now with an exciting Video!

Enterprise

John Mutter and Brent Thornton, of the BlackBerry Enterprise Developer Partnerships team, have contributed this post for the Inside BlackBerry for Business Blog.

Enterprise apps are changing the way that we work, undoubtedly for the better. Access to behind-the-firewall data for a workforce that is constantly on the move provides increased productivity, can reduce the margin of error in reporting, fosters collaboration, and the list goes on.

Building push technology into your enterprise apps takes things to a whole new level. Push is an essential component of the real-time, always-on experience of BlackBerry devices. It offers an incredibly efficient and reliable way of sending information to your users in real time. Check out the video below for our take on push technology in enterprise apps:

[ YouTube link for mobile viewing ]

Let’s take a look at how you can build push technology into your enterprise apps.

Before I begin I have to pass mad props to Garett Beukeboom here at BlackBerry who wrote the original Simple Push Sample. I took his code and modified it for use with enterprise applications.

Getting the sample client that we used in the video to get up and running is nice and easy. Follow these steps to get started:

  1. Download the ServerNotify sample (Note: Client and Server code is located here)
  2. Import the project in to Cascades
  3. Modify the bar-descriptor.xml file:
  4. <invoke-target id="com.abccompany.servernotify">
         <type>APPLICATION</type>
         <filter>
              <action>bb.action.PUSH</action>
              <mime-type>application/vnd.push</mime-type>
         </filter>
    </invoke-target>
    

    The Key piece is the invoke-target id. Set this to something unique to your company and app.

  5. Next, open up PushManager.cpp
  6. Modify the following line to match the invoke target id you used in your bar-descriptor
  7. const QString PushManager::BLACKBERRY_INVOKE_TARGET_ID = 
         "com.abccompany.servernotify";
    
  8. Modify the following application ID to match the application ID you use in the server code
  9. const QString PushManager::BLACKBERRY_PUSH_APPLICATION_ID = "bb_server_notify";
  10. Package and sign your application.
  11. IMPORTANT: Do not load the app by side loading as it loads to the personal space. Your application needs to be deployed from BlackBerry Enterprise Service 10 in order to make use of enterprise push. This way the app will appear in the work space and can be received through BlackBerry World for Work.
  12. Once deployed, launch your application (You must run your application at least once to have it register with the push service).
  13. Start pushing :)

Breaking it down – The Important Stuff

Taking a look at PushManager.cpp, here is what happens in the code:

You kick off by registering your application with the Push Service using your Application ID and Invoke-target ID.

const QString PushManager::BLACKBERRY_PUSH_APPLICATION_ID = "bb_server_notify";
const QString PushManager::BLACKBERRY_INVOKE_TARGET_ID = "com.abccompany.servernotify";
m_pushService = new PushService(BLACKBERRY_PUSH_APPLICATION_ID, BLACKBERRY_INVOKE_TARGET_ID);
m_pushService->createSession();

When the session is completed successfully you need to create a channel. You will notice that we pass a URL to the createChannel function. For enterprise we are passing the empty string.

const QString PushManager::BLACKBERRY_PUSH_URL = "";
m_pushService->createChannel(QUrl(BLACKBERRY_PUSH_URL));

Once the channel is completed successfully, push is ready to go. There are a few additionally items you will want to take care of. In our code you will see:

m_pushService->registerToLaunch();

This tells the push service to launch the application when a push arrives. This needs to happen if you plan on processing the push. If you only want to see push data when the app is open, this step is not needed.

Now for the most important piece of the puzzle, what to do with the push payload? When a push arrives on the device the Push Service checks what Application ID in the push header matches an application on the device that has registered with the same Application ID. It then invokes the application associated with that ID.

In the constructor of the PushHandler class we registered the invoked SIGNAL with an invoked SLOT function.

invokeManager = new InvokeManager(this);
     connect(invokeManager,
          SIGNAL(invoked(const bb::system::InvokeRequest&)), this,
          SLOT(invoked(const bb::system::InvokeRequest&)));

The void PushManager::invoked(const InvokeRequest& request) function takes in the invoke request that includes the push payload and processes it like so:

  • Check the invoke came from the push service:
  • if (request.action().compare("bb.action.PUSH") != 0)
  • Convert the request to a payload object now that we know it’s from push
  • PushPayload payload(request);
  • Check that the payload is valid.
  • if (payload.isValid()) {
  • If you require notification that the push has been received (via the Notify URL) you need to acknowledge the push.
  • if (payload.isAckRequired()) { 
              m_pushService->acceptPush(payload.id());
         }
    
  • Finally, grab the push data
  • //Read all the push data from the payload
    QString message = payload.data();
    

You can choose to process the data however you like. In our case we interpret the priority and update the UI and notifications accordingly.

Common Push issues in the Enterprise:

  1. If you have any other samples that were built in cascades and aren’t working: Make sure you remove the following from the bar-descriptor.xml file. It is for public push only.
  2. <permission system="true">_sys_use_consumer_push</permission>
  3. If you have read about the Push Service SDK anywhere for the server, you can use this in the enterprise, but it is not necessary. It is much easier to build the HTTP POST yourself on the server. The Push Service SDK is a great tool for consumer push.
  4. Make sure your invoke-target id’s are unique and match between the code and the bar-descriptor.xml file.

Fun Fact of the day

You can register an app target with multiple application ID’s if you like. That way, a different Push transaction can perform different tasks within the same application.

m_pushService1 = newPushService(BLACKBERRY_PUSH_APPLICATION_ID1, BLACKBERRY_INVOKE_TARGET_ID);
m_pushService2 = newPushService(BLACKBERRY_PUSH_APPLICATION_ID2, BLACKBERRY_INVOKE_TARGET_ID);

The Push Server

Building applications that leverage Enterprise Push is easier than you think. The process involves a server-initiated HTTP POST transaction to the BlackBerry Enterprise Service hosted by your company. Before you begin, you need a few details from your BlackBerry Server Administrator to be successful.

  1. BlackBerry Enterprise Service Host Name
  2. BlackBerry Enterprise Service Push Port
  3. E-Mail Address or PIN of the Application User (Although the E-Mail address is recommended)

You will also need the following details from the Developer of the client application on the BlackBerry.

  1. The unique BlackBerry Application ID from the BlackBerry Application you are pushing to
  2. The format of the data payload you intend to push (e.g. JSON, XML, Text, etc…)

Once you have obtained this information, I have written a C# sample Method that will complete the HTTP POST transaction for you. Keep in mind, there are a lot of additional options and headers you can find on the BlackBerry Developer Website.

public boolean pushData(String besName, String besPushPort, String recipientEMail, String appIdOnBlackBerry, String pushPayload)
     {
          Boolean result = false;
          // Examples of Data format
          //String besName = "myServer.abcCompany.net”;
          //String besPushPort = "8080";
          //String recipientEMail = "my.address@abcCompany.com";
          //String appIdOnBlackBerry = "bb_server_notify";
          // Please note the appIdOnBlackBerry can
          // be the PORT for previous implementations
          // of the Push Initiator.
          //String pushPayload = "Data that is sent to the Push Application on the BlackBerry";

          // Now we are going to build the POST URL
          String httpURL = "http://" + besName
               + ":" + besPushPort
               + "/push?DESTINATION=" + recipientEmail
               + "&PORT=" + appIdOnBlackBerry
               + "&REQUESTURI=/";
          try
          {
               // Instantiate and define the Web Request
               HttpWebRequest HttpWReq = (HttpWebRequest)WebRequest.Create(httpURL);
               HttpWReq.Method = ("POST");
               HttpWReq.Headers.Add("ContentType", "text/plain");
               // Convert the payload to a Byte Array
               byte[] data = System.Text.ASCIIEncoding.UTF8.GetBytes(pushPayload);
               // Instantiating and writing the communication stream
               Stream requestStream = HttpWReq.GetRequestStream();
               requestStream.Write(data, 0, data.Length);
               HttpWebResponse HttpWRes = (HttpWebResponse)HttpWReq.GetResponse();
               if (HttpWRes.StatusCode == HttpStatusCode.OK)
               {
                    result = true;
               }
               requestStream.Close();
               HttpWRes.Close();
               }
                    catch (Exception err)
               {
               //Handle Exception here
          }
          return result;
     }

There you have it; the guide for using push technology in your enterprise apps. Have questions? Share in the comments below or head over to the BlackBerry Developer Support Forums.

About Luke Reimer

@Luke_Reimer is an Enterprise Marketing Manager at BlackBerry helping to design, launch, and manage enterprise marketing programs - particularly concerning content across digital mediums. Beyond spreading BlackBerry goodness in enterprise communities, you can find Luke cooking up a storm, out on his motorcycle (when Canadian weather allows), or digging into a good science fiction book.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus