Child pages
  • Push Notification Framework
Skip to end of metadata
Go to start of metadata

Downloads

RAMP push notification service

The RAMP push notification service jar can be downloaded here: ramp-pns-1.0.1.jar

Note that this jar has the following dependencies:

iOS push notification plug-in

The iOS push notification plug-in can be downloaded here: ios_notification_plugin.zip

Windows Phone push notification plug-in

The Windows Phone push notification plug-in can be downloaded here: WP7ToastPushNotificationPlugin.dll

Platform requirements

Each platform requires certain setup to allow one to send push notifications. This section describes the setup required for each platform.

Apple

The Apple documentation for provisioning and developing for push notifications is available here: https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ProvisioningDevelopment.html#//apple_ref/doc/uid/TP40008194-CH104-SW1

Here is a summary of the setup that is required:

  • An explicit app ID (not a wildcard) which has push notifications enabled, configured using an Apple developer account

  • An Apple Push Notification service certificate created using an Apple developer account and exported to a .p12 file

  • The password used when exporting the certificate to file

Android

The Google Cloud Services documentation is available here: http://developer.android.com/google/gcm/gs.html#create-proj

Here is a summary of the setup that is required:

  • A Google account with Google Cloud Services activated.

  • A sender ID (same as project number) and API key obtained as follows

BlackBerry

  • Register to evaluate the BlackBerry Push Service here: http://developer.blackberry.com/services/push/. When your application is ready to be launched you will need to register to launch your application in production.
  • When your registration is approved you will be given an Application ID, a password, a Content Provider ID, PPG Base URL (which includes the content provider ID) and a Push Port. The app and the server use the same PPG Base URL, except the app uses http and the server uses https.


BlackBerry registration

Registration with BlackBerry can take a few days to be approved.

Windows Phone

None

Enabling a RAMP app to receive push notifications

Apple

Include the iOS Push Notification plug-in in the project

 The  RAMP iOS Push Notification plug-in (ios_notification_plugin.zip) must be included in the iOS template project. To do this:

  • Copy NotificationPlugin.h to plugins/headers and notificationplugin.a to plugins/libraries in the iOS template project
  • Open the project in Xcode and add notificationplugin.a to the project
  • Add "NotificationPlugin" to plugins.txt

Edit AppDelegate.m

 Edit the AppDelegate.m file in the RAMP iOS template project in the Classes folder as follows:

//
//  rampVmAppDelegate.m
//  rampVm
//
//  Created by Virtual Mobile Technologies VMT on 2010/02/25.
//  Copyright VMT 2010. All rights reserved.
//
#import "AppDelegate.h"
#import "AppLoadingViewController.h"
#import "NotificationPlugin.h"
@implementation AppDelegate

- (RampLoadingViewController*) rootViewController;
{	
	if (rootViewController == nil)
		rootViewController = [[[AppLoadingViewController alloc] init] autorelease];
	
	return rootViewController;
}
- (void)application:(UIApplication *)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)devToken
{
    NotificationPlugin* notifPlugin = [NotificationPlugin getInstance];
    if (notifPlugin != nil)
        [notifPlugin application:app didRegisterForRemoteNotificationsWithDeviceToken:devToken];
}
- (void)application:(UIApplication *)app didFailToRegisterForRemoteNotificationsWithError:(NSError *)err
{
    NotificationPlugin* notifPlugin = [NotificationPlugin getInstance];
    if (notifPlugin != nil)
        [notifPlugin application:app didFailToRegisterForRemoteNotificationsWithError:err];
}
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
{
    NSLog(@"didReceiveRemoteNotification");
    NotificationPlugin* notifPlugin = [NotificationPlugin getInstance];
    NSLog(@"notifPlugin = %@", notifPlugin);
    if (notifPlugin != nil)
        [notifPlugin application:application didReceiveRemoteNotification:userInfo];
}
- (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification
{
    NSLog(@"didReceiveLocalNotification");
    NotificationPlugin* notifPlugin = [NotificationPlugin getInstance];
    NSLog(@"notifPlugin = %@", notifPlugin);
    if (notifPlugin != nil)
        [notifPlugin application:application didReceiveLocalNotification:notification];
}

// not required since app fethces messages on restart anyway
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [super application:application didFinishLaunchingWithOptions:launchOptions];
    NSLog(@"didFinishLaunchingWithOptions, launchOptions = %@", launchOptions);
    
    NotificationPlugin* notifPlugin = [NotificationPlugin getInstance];
    if (notifPlugin != nil)
        [notifPlugin application:application didFinishLaunchingWithOptions:launchOptions];
    
    
    return YES;
}

@end

Android

  • The RAMP Android Push Notification Plug-in must be included in the VM config on the deployment platform.
  • The TemplateAndroidManifest.stg file in (project path)/archive/android must be edited to enable push notifications as follows:

group srcmanifest;
manifest(permissions) ::=
<<
\<?xml version="1.0" encoding="utf-8"?\>
\<manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="com.virtualmobiletech.coordination"
     android:versionCode="1"
     android:versionName="4.5.0"\>
     
	\<application android:icon="@drawable/icon" android:theme="@android:style/Theme.NoTitleBar" android:label="RAMP"\>
	
    	\<activity android:name=".LoadingActivity" android:label="Loading" android:configChanges="keyboardHidden|orientation"\>
        	\<intent-filter\>
            	\<action android:name="android.intent.action.MAIN" /\>
                \<category android:name="android.intent.category.LAUNCHER" /\>
            \</intent-filter\>
        \</activity\>
        \<activity android:name=".UxmlActivity" android:configChanges="keyboardHidden|orientation"/\>
        \<activity android:name=".ServiceFormActivity" android:configChanges="keyboardHidden|orientation"/\>
        \<activity android:name=".ErrorActivity" android:label="Fatal Error" android:configChanges="keyboardHidden|orientation"/\>
        \<activity android:name="com.virtualmobiletech.plugin.PluginActivity" android:configChanges="keyboardHidden|orientation"/\>		
        
        \<!--
	      BroadcastReceiver that will receive intents from GCM
	      services and handle them to the custom IntentService.
	
	      The com.google.android.c2dm.permission.SEND permission is necessary
	      so only GCM services can send data messages for the app.
	    --\>
	    \<receiver
	        android:name="com.vmt.notification.GCMReceiver"
	        android:permission="com.google.android.c2dm.permission.SEND" \>
	        \<intent-filter\>
	
	            \<!-- Receives the actual messages. --\>
	            \<action android:name="com.google.android.c2dm.intent.RECEIVE" /\>
	            \<!-- Receives the registration id. --\>
	            \<action android:name="com.google.android.c2dm.intent.REGISTRATION" /\>
	
	            \<category android:name="com.a{AppId}.coordination" /\>
	        \</intent-filter\>
	    \</receiver\>
	    
	    
	    \<!--
	      Application-specific subclass of GCMBaseIntentService that will
	      handle received messages.
	
	      By default, it must be named .GCMIntentService, unless the
	      application uses a custom BroadcastReceiver that redefines its name.
	    --\>
	    \<service android:name="com.vmt.notification.GCMIntentService" 
	        android:enabled="true"/\>
	    
	    \<activity android:name="com.vmt.notification.StatusBarNotifications"
	        android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen"
	        android:launchMode="singleTop"\>
	    \</activity\>
        
    \</application\>
	
    \<uses-sdk android:minSdkVersion="8" android:targetSdkVersion="16"/\>
    \<uses-permission android:name="android.permission.INTERNET" /\>
    
    \<!-- GCM requires a Google account. --\>
    \<uses-permission android:name="android.permission.GET_ACCOUNTS" /\>
    \<!-- Keeps the processor from sleeping when a message is received. --\>
    \<uses-permission android:name="android.permission.WAKE_LOCK" /\>
    
    \<!--
     Creates a custom permission so only this app can receive its messages.
     NOTE: the permission *must* be called PACKAGE.permission.C2D_MESSAGE,
           where PACKAGE is the application's package name.
    --\>
    \<permission
        android:name="com.a{AppId}.coordination.permission.C2D_MESSAGE"
        android:protectionLevel="signature" /\>
    \<uses-permission android:name="com.a{AppId}.coordination.permission.C2D_MESSAGE" /\>
    
    \<!-- This app has permission to register and receive data message. --\>
    \<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" /\>
    
    \<!-- required by HTC devices for notifications --\>
    \<uses-permission android:name="android.permission.VIBRATE" /\>
    
    <permissions; separator="\n">
	
\</manifest\> 
>>

Note the following changes to the standard file:

  • New block of code added inside the <application> tag
  • android:minSdkVersion changed to "8"

  • New permissions added
  • Note that wherever the string "com.a{AppId}.coordination" appears (3 occurrences), {AppId} must be replaced with the ID of your RAMP app.

BlackBerry OS 5.0 - 7.1

The RAMP app must be built off at least 4.6.0 of RAMP, which is already packaged with the RAMP BlackBerry Push Notification plug-in without needing to include it in the VM config.

Push notifications are only supported on BlackBerry OS 5 and up, and are therefore not enabled in the default BlackBerry download which supports BlackBerry OS 4.2 and up. To download the push enabled application you will need to select "This is not my phone..." and then either "Blackberry5_0", "Blackberry6_0" or "Blackberry7_0" depending on the OS version.

BlackBerry OS 10

To enable the Android app compiled for BlackBerry 10 to receive Push Notifications, see the following: https://developer.blackberry.com/android/apisupport/creating_push-enabled_android_apps.html

Windows Phone

The RAMP Windows Phone Push Notification Plug-in must be included in the RAMP Windows Phone template project. To do this:

  • Copy WP7ToastPushNotificationPlugin.dll to WindowsPhoneRampVM\plugins\libraries in the Windows Phone template project
  • Open the project in Visual Studio and add a reference to the plug-in DLL to the project
  • Add "WindowsPhoneRamp.PushNotificationPlugin.PushNotificationPlugin" to plugins.txt

Using the RAMP push notification plug-ins

Register function

All enabled platforms use the vmt_registerForPushNotifications function to register a RAMP app to receive push notifications. Each platform takes a different number of parameters, but the first 2 parameters on all platforms are as follows:

vmt_registerForPushNotifications(registerCallback, notificationCallback {, ...});
  • registerCallback - The name of a RAMP function as a string. The callback function takes 2 parameters, token and error. If registration was successful then token is the app's unique token and error is an empty string. If registration failed then token is an empty string and error is a string description of the reason for failure. 

    Terminology

    The term token is used above, but different terminology may be used on different platforms. E.g. on Android it is called the registration ID, on Windows Phone the channel URI and on BlackBerry the device ID.

  • notificationCallback - The name of a RAMP function as a string. The callback function takes 2 parameters, message and error. Message is the string message that was sent with the push notification from the server. If receiving the push notification failed, then message is an empty string and error is a string description of the reason for failure.

    Platform differences

    On all platforms push notification indicators are only shown in the respective notification areas when the application is not the current foreground app. If it is in the background or not running, the notification indicator will be shown.

    On Android, Windows Phone and BlackBerry if the app is running, either in the foreground or the background, the notificationCallback function is called the moment the push notification is received.

    On iOS if the app is running in the foreground, the notificationCallback function is called the moment the push notification is received, but if it is in the background the notificationCallback function is only called if and when the notification indicator is selected.

Apple register function

The Apple register function has no extra parameters and is called as follows:

vmt_registerForPushNotifications(registerCallback, notificationCallback);

Android register function

The Android register function is called as follows:

vmt_registerForPushNotifications(registerCallback, notificationCallback, senderId);

Parameters following the second parameter:

Windows Phone register function

The Windows Phone register function is called as follows:

vmt_registerForPushNotifications(registerCallback, notificationCallback, channelName);

Parameters following the second parameter:

  • channelName - An application developer selected unique channel name.

BlackBerry register function

The BlackBerry register function is called as follows:

vmt_registerForPushNotifications(registerCallback, notificationCallback, applicationId, ppgUrl, pushPort);

Parameters following the second parameter (details provided when registering for BlackBerry Push Notifications):

  • applicationId - The Application ID provided by BlackBerry e.g. 1234-T4BvmymSqEfeHKyDkTKiWnVZOdOlP0yoGCb
  • ppgUrl - The PPG Base URL (the http one) with Content Provider ID included e.g. e.g. http://cp1234.pushapi.eval.blackberry.com
  • pushPort - The Push Port provided by BlackBerry e.g. 33349

Additional BlackBerry functions

The following additional functions are available only on the BlackBerry platform:

vmt_setBBPushNotificationIcon

This function must be called otherwise no notification indicator will be shown on BlackBerry.

When push notifications are received on BlackBerry, a push notification application indicator is shown on the home screen. The app icon isn't used for this indicator like on other platforms. This function is used to set the push notification indicator icon. The icon should not be bigger than 32x32. Note that since the RAMP platform scales images for larger screens, if referencing an image src parameter from RAMP script, one must ensure that the scaled size is not bigger than 32x32. The best way to do this is to have a wide coverage of screen size folders and copy the image with the correct size into each of these folders to prevent scaling.

vmt_setBBPushNotificationIcon(pngImageByteArray)

Parameters:

  • pngImageByteArray - The PNG image byte array. Can be obtained from RAMP script by calling: imageName.src

vmt_setBBPushNotificationMessageFolderDetails (Only relevant to BB OS 6 and up)

When push notifications are received on BlackBerry OS 6 and up, as well as adding a push notification application indicator, a message item is added to a message folder belonging to the app. This ensures that a message item is shown when the push notification application indicator is selected. The message item will contain the text payload sent with the push notification by the server.

The message folder has various parameters which are configured using this function.

vmt_setBBPushNotificationMessageFolderDetails(folderId, folderName, contact, subject)

Parameters:

  • folderId - An application developer selected unique integer used by the BlackBerry OS to uniquely identify the message folder.

  • folderName - The folder name.
  • contact - The contact name.
  • subject - The subject of all messages received. BlackBerry push notifications contain only a message payload and no subject, therefore this configures the subject to be used for all push notifications.

RAMP Push Notification Plug-ins Example

Here is example RAMP script of how to register an app for push notifications across all supported platforms.

function main()
{
	if (funcSupported("vmt_setBBPushNotificationIcon") == 1)
	{
		vmt_setBBPushNotificationIcon(pnicon.src);
		vmt_setBBPushNotificationMessageFolderDetails(123456789, "My Folder", "RAMP", "Message");
	}
	
	if (funcSupported("vmt_registerForPushNotifications") == 1)
	{
		registerFunc = "onNotificationsRegister()";
		notificationFunc = "onNotification()";
		
		osName = rampGetProperty("config._os_name");
		
		if (osName == "blackberry")
		{
			vmt_registerForPushNotifications(
				registerFunc, 
				notificationFunc, 
				"1234-T4BvmymSqEfeHKyDkTKiWnVZOdOlP0yoGCb", 
				"http://cp1234.pushapi.eval.blackberry.com", 
				33349);
		}
		else if (osName == "ANDROID")
		{
			vmt_registerForPushNotifications(
				registerFunc, 
				notificationFunc, 
				"772365870"
			);
		}
		else if (osName == "Windows Phone")
		{
			vmt_registerForPushNotifications(
				registerFunc, 
				notificationFunc, 
				"RampAppWindowsPhonePushNotificationChannel"
			);
		}
		else // iOS
		{
			vmt_registerForPushNotifications(
				registerFunc, 
				notificationFunc
			);
		}
	}
}
 
function onNotificationsRegister(token, error)
{
	if (error != "")
		error(error);
}

function onNotification(message, error)
{
	if (error != "")
		error(error);
}

Sending Push Notifications

To send push notifications, create an instance of the relevant class, e.g. ApplePNS, AndroidPNS, BlackBerryPNS or WP7PNS and execute the pushNotification() method.

ApplePNS

The constructor takes the following arguments (obtained when setting up for Apple):

keyStoreFileName - The name of the .p12 keystore file containing the Apple Push Notification service certificate. The .p12 file must be in the classpath root.

keyStorePassword - The password used to export the .p12 file.

production - Whether to use the Apple production push notification server (true) or the sandbox server (false). Note that the server you need to use is dependent on what certificate you sign your app with. If signing with a development certificate, the sandbox server should be used, if signing with a distribution certificate, the production server should be used.

AndroidPNS

The constructor takes the following argument:

apiKey - The API key which was obtained when registering for Google Cloud Services.

BlackBerryPNS

The constructor takes the following arguments (obtained when registering for BlackBerry):

pushUrl - The PPG Base URL (the https one) with Content Provider ID included e.g. https://cp1234.pushapi.eval.blackberry.com

appId - The Application ID provided by BlackBerry e.g. 1234-T4BvmymSqEfeHKyDkTKiWnVZOdOlP0yoGCb

password - The password provided by BlackBerry

WP7PNS

Does not take any constructor arguments.

Push Notification Error Handling

Push Notification Errors generally occur when a Push Notification wasn't sent to a device which can be caused by specifying an invalid PNS (Push Notification Service) token or URI. These errors are returned to you to decide what to do with them. Each one of the platforms deals with Push Notification Errors differently however, for your convenience they are packaged together and returned in one PNSResult object to you. A PNSResult object consists of the following:

  • ResultCode
    • Property type: int
    • Expected value: 200 (all Push Notifications were sent successfully) or -1 (one or more Push Notifications weren't sent)
  • PNSErrors
    • Property type: List<Error>
    • Expected value: Empty list. If ResultCode is -1, this will be a List of Errors that explains the reason(s) for the Push Notification(s) that weren't sent.

The Push Notification Error object which can be expected in the PNSErrors List (see above) if any errors occurred, consists of the following:

  • RegistrationId
    • Property type: String
    • Expected value: The token or URI for the device that the Push Notification could not be sent to.
  • ErrorCode
    • Property type: String
    • Expected value: A unique code indicating the error that occurred eg. "InvalidTokenException"
  • ErrorDescription
    • Property type: String
    • Expected value: The detailed description thrown by the Push Notification Service eg. "Unable to send Push Notification due to invalid token specified"
  • Platform
    • Property type: String
    • Expected value: ANDROID, iPhone OS or Windows Phone

The ErrorCode found in the Error object (see above) may vary depending on which platform it occurred on. While iOS may have a "UnknownDeviceException" ErrorCode, Android may have a "NotRegistered" ErrorCode. For a list of different error codes per platform, see the links below:

Each Push Notification request returns a list of PNSResult objects. See the example below:

List<String> listOfWindowsPhoneURIs = new ArrayList<String>();
WP7PNS wp7PNS = new WP7PNS();

listOfWindowsPhoneURIs.add("http://My-First-Registered-Windows-Phone's-MicrosoftPushNotificationServer-URI");
listOfWindowsPhoneURIs.add("http://My-Second-Registered-Windows-Phone's-MicrosoftPushNotificationServer-URI");
listOfWindowsPhoneURIs.add("http://My-Fake-MicrosoftPushNotificationServer-URI");
 
PNSResult res = wp7PNS.pushNotification(listOfWindowsPhoneURIs, "My Subject", "My Message");
// NB* Two Push Notifications are expected to be delivered successfully while the third (fake uri) is expected to fail
// res is expected to have a ResultCode of -1 as I added a "fake" Microsoft Push Notification Server URI.
// res is expected to have a List of Errors containing one record with an explanation of why the "fake" Push Notification wasn't sent
  • No labels