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 which includes values for the message to be displayed or the values can be included in the URL.

Note, for SMP servers that are on a network that uses a proxy, the proxy settings in the server's props.ini file should be configured so that the SMP server can access the GCM and APNS servers.

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

Follow the instructions at Getting Started with GCM to create an API project, receive a project ID (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 Cockpit to 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
```
Fill in the Push settings for the application.

Create the project.

cordova -d create C:\Kapsel_Projects\PushDemo com.mycompany.push PushDemo
cd PushDemo
cordova -d platform add android

cordova -d create ~/Documents/Kapsel_Projects/PushDemo com.mycompany.push PushDemo
cd ~/Documents/Kapsel_Projects/PushDemo
cordova -d platform add ios

Add push plugin.

cordova -d plugin add C:\SAP\MobileSDK3\KapselSDK\plugins\push

cordova -d plugin add ~/SAP/MobileSDK3/KapselSDK/plugins/push

Replace www\index.html with index.html. Update index.html and enter the serverHost(line 16) and sender ID(line 75).
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 and download Extras > [Deprecated] Google Cloud Messaging for Android Library

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

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.

Restart the SMP 3.0 server.
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.
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
```
X-SMP-GCM-DATA: {"dispmsg":"Hello Kapsel"}
```
If prompted to 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.
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().
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, if the Kapsel app is force stopped, it will no longer receive notifications until it is restarted.

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 eclise, 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.