Getting Started with Kapsel - Part 4 -- Push

[Dan_vL]

         

Push

Push messages provide a way to inform or remind a user that an action should be taken by delivering a short message that appears as a notification on the device.  When clicked on, the app that is associated with the message is opened.  The Kapsel push plugin provides an abstraction layer over the Google Cloud Messaging for Android (GCM) and Apple Push Notification Service (APNS).  A notification can be sent to a device registered with an application via a REST call to

http://SMP_3.0_SERVER:8080/Notifications/application_registration_id

The REST call should either contain a header named X-SMP-DATA or X-SMP-GCM-DATA which includes values for the title and message content to be displayed or the values can be included in the URL.

Note, for SMP servers that are on a network that use a proxy ensure that the proxy settings are set for the SMP server under Settings > System > HTTP Proxy Settings so that the SMP server can access the GCM and APNS servers.
Note, if you have proxy setting set and are not on a network that uses a proxy, the proxy settings should be removed or the host for the GCM or APNS server should be added to the non-proxy hosts field.

Note that both GCM and APNS require open ports that may be blocked on some corporate networks or routers.  GCM uses ports between 5228 and 5230.  APNS uses the ports described here.

For additional details see the JavaScript file in a project that includes this plugin at

project_name\www\plugins\com.sap.mp.cordova.plugins.push\www\push.js

or the JS Documentation at Kapsel Push API Reference.

The following steps will demonstrate this plugin using Google Cloud Messaging.  Note, it requires either an Android device or an Android emulator that targets the Google API's.


The process for iOS and Windows is covered by others.  Here are a few posts to check out. 
Apple Push Notification Services in iOS 6
[Kapsel] How to use the Push plugin on iOS
[Kapsel] How to use the Push plugin on Windows

• Follow the instructions at Getting Started with GCM to create an API project, receive a project number (sender ID), enable the GCM service for the project and to obtain an API key.
  
  
• Follow the steps shown in Configuring a Kapsel App in the Management Cockpitto create an Application with the application id of

  com.mycompany.push

    This app does not use an OData endpoint so the endpoint can be set to a dummy URL such as

  http://mycompany.com

  and add the Basic SSO mechanism and the default security provider.
  
  
• Fill in the Push settings for the application. 
  
  
  
• Edit the Notification security provider and add a System Login (Admin Only) authentication provider.  Set the user name and password to a value like smpPushUser and smpPushPwd and the role Notification User.  Note this user name and password will need to be entered later when we send a notification to the device using the Advanced REST client.
  
  
  Restart the SMP 3.0 server.
  
  
• Create the project.

  cordova -d create C:\Kapsel_Projects\PushDemo com.mycompany.push PushDemo "{\"plugin_search_path\":\"C:/SAP/MobileSDK3/KapselSDK/plugins/\"}"
  
  cd PushDemo
  
  cordova -d platform add android
  
  

• Add push plugin.

  cordova -d plugin add com.sap.mp.cordova.plugins.push
  
  

• Replace www\index.html with index.html.
  Update index.html and enter the serverHost(line 15) and sender ID(line 62).
  
  
• Copy the files to the platform directory by running

  cordova -d prepare
  
  

• Use the Android IDE to open the project.
  
  
• Open the Android SDK Manager click on the Obsolete checkbox and download Extras >Google Cloud Messaging for Android Library (Obsolete)
  
  
• Copy the below jar into the libs folder of the PushDemo project.

  C:\Android\adt-bundle-windows-x86_64-20130522\sdk\extras\google\gcm\gcm-client\dist\gcm.jar

• Use the Android IDE to deploy and run the project.
  
  
• Click on the Register For Push button
  
  
  Note that when reopening the app, the Register For Push button must be pressed again or in a non-sample app, it should be called in the logonSuccessCallback method which would be called each time the application starts.
  
  
• Send a REST request to send a notification to a Kapsel app.  The registration id can be copied from Management Cockpit. 
  
  
  
  For additional details on the headers see Notification Data Sent Through HTTP Headers and as of SMP Server SP04 Notification Data Sent Using Push API.
  
  The below are a few different ways to send a notification.

  X-SMP-DATA: {"alert":"New Vacation Approval Request", "dispmsg":"For (i826565) request ID[7]"}
  X-SMP-GCM-DATA: {"alert":"New Vacation Approval Request", "dispmsg":"For (i826565) request (7)"}
  x-sap-poke-title: New Vacation Approval Request
  x-sap-poke-data: {"dispmsg":"For (i826565) request (7)"}
   
  http://127.0.0.1:8080/Notification/59a72605-2a64-4778-953d-c215a7d565eb?alert=New Vacation Approval Request&data={"dispmsg":"For (i826567) request (7)"} 

  When prompted for a User Name and Password enter smpPushUser and smpPushPwd.
  
  
  
  
  
  The following are a few examples using the new restnotification API.

  http://127.0.0.1:8080/restnotification/application/com.mycompany.push/
   {"alert":"New Vacation Approval Request", "data":"For (i826565) request (7)" } 
  
  http://localhost:8080/restnotification/registration/59a72605-2a64-4778-953d-c215a7d565eb
   {"alert":"New Vacation Approval Request", "data":"For (i826565) request (7)" }
   
  http://localhost:8080/restnotification/application/com.mycompany.push/user/nosec_identity
   {"alert":"New Vacation Approval Request", "data":"For (i826565) request (7)" } 

  Note, the first example may not work if the forward slash is missing from the end of the URL. 
  An example using the Advance REST Client
  
  
  An example using Postman.
  
  
  When prompted for a User Name and Password enter smpPushUser and smpPushPwd.
  
  If the status is 403, this indicates a permission problem.  Double check that that the correct user id and password for the Notification security profile were correctly entered.  Also double check that the correct role name of Notification User was assigned to the Roles of the authentication provider for the Notification security profile.
  
  If the status is 404, this may indicate that the app did not successfully register for notifications.  Try pressing the Register for Push button again and verify that the Successfully registered alert displays.
  
  If the status is 200, this may indicate that the app has not registered and received a registration id from Google or perhaps that there is some issue reaching the Google GCM service.  Double check that the sender ID was added to the index.html.
  
  
• The notification will be processed by the app if it is running in the foreground.
  
  
  
• Now press the back button to exit the app and send the notification again from the Advanced Rest Client.  The notification should appear on the device or simulator and clicking on it will open the app.  Notice that a custom icon was used by replacing the file

  C:\Kapsel_Projects\PushDemo\platforms\android\res\drawable-hdpi\icon.png

  
  
  
  If the app is not in the foreground when a notification arrives, the details of the notification can be accessed by calling sap.Push.checkForNotification(processMissedNotification).
  
  Note the notification shown will be for the notification that was selected from the notification bar.
  
  Also note that it may appear as the Kapsel app is opened multiple times after selecting a notification from the notification bar when the app is in the foreground due to issue 162504. 
  
  
• A logcat filter using the log tag value of PUSH will filter out the messages sent from the Kapsel push plugin.  Note, this filter will not show the messages displayed using console.log().
  
  
  
• On some Android devices there is an error while registering for notification.

  java.lang.UnsupportedOperationException: Device does not have package com.google.android.gsf

  This occurs since Google Services Framework is missing. There is no solution or workaround for this limitation.
  
  
• Push notifications can be disabled on Android and iOS.
  On iOS open Settings > Notifications > PushDemo
  On Android open Settings > Apps > PushDemo > Uncheck Show Notifications
  
  
• On Android, there are separate volume controls for the notifications and alarms.  If you do not here a notification sound check the volume level for Notifications. Settings > Sound > Volumes > Notifications.
  
  
• On Android, the sound played when a notification arrives can be selected.  Settings > Sound > Default notification.
  
  On an Android emulator, the sound file first needs to be copied onto the device.  Open the DDMS perspective in eclipse, select the File Explorer and copy C:\adt-bundle-windows-x86_64-20130917\sdk\platforms\android-19\data\res\raw\fallbackring.ogg to storage\sdcard\Notifications.  Restart the emulator.  Fallbackring should now be accessible in the settings.
  
  

Note, there is an open source push plugin that is described at Cordova Push Notifications Plugin.

The following post describes some items to keep in mind once your push enable app is ready for release.  Keeping Google Cloud Messaging For Android Working Reliably.

Back to Getting Started With Kapsel