IBM Cloud Mobile Services - Cordova Plugin Push SDK

Cordova Plugin for the IBM Cloud Mobile Services Push SDK

Installation

Installing necessary libraries

You should already have Node.js/npm and the Cordova package installed. If you don't, you can download and install Node from https://nodejs.org/en/download/.

The Cordova library is also required to use this plugin. You can find instructions to install Cordova and set up your Cordova app at https://cordova.apache.org/#getstarted.

Installing the Cordova Plugin for IBM Cloud Mobile Services Push SDK

Creating a Cordova application

1. Run the following commands to create a new Cordova application. Alternatively you can use an existing application as well.

   cordova create {your_app_name}
   cd {your_app_name}

2. Edit config.xml file and set the desired application name in the <name> element instead of a default HelloCordova.

3. Continue editing config.xml. Update the <platform name="ios"> element with a deployment target declaration as shown in the code snippet below.

   <platform name="ios">
   	<preference name="deployment-target" value="8.0" />
   	<!-- add deployment target declaration -->
   </platform>

4. Continue editing config.xml. Update the <platform name="android"> element with a minimum and target SDK versions as shown in the code snippet below.

   <platform name="android">
   	<preference name="android-minSdkVersion" value="15" />
   	<preference name="android-targetSdkVersion" value="26" />
   	<!-- add minimum and target Android API level declaration -->
   </platform>

   The minSdkVersion should be above 15.

   The targetSdkVersion should always reflect the latest Android SDK available from Google.

Adding Cordova platforms

Run the following commands according to which platform you want to add to your Cordova application

cordova platform add ios

cordova platform add android

IMPORTANT: Make sure you use this iOS version for the cordova platform. It is required for the cordova app to build.

Adding the Cordova plugin

From your Cordova application root directory, enter the following command to install the Cordova Push plugin.

cordova plugin add bms-push

This also installs the Cordova Core plug-in, which initializes your connection to IBM Cloud.

From your app root folder, verify that the Cordova Core and Push plugin were installed successfully, using the following command.

cordova plugin list

Note: Existing 3rd party push notification plugins (e.g., phonegap) may interfere with bms-push. Be sure to remove these plugins to ensure proper funcitonality.

Configuration

Configuring Your iOS Development Environment

1. Follow the Configuring Your iOS Development Environment instructions from IBM Cloud Mobile Services Core SDK plugin

Updating your client application to use the Push SDK

By default, Cordova creates a native iOS project built with iOS, therefore you will need to import an automatically generated Swift header to use the Push SDK. Add the following Objective-C code snippets to your application delegate class.

At the top of your AppDelegate.m:

#import "[your-project-name]-Swift.h"

If your project name has spaces or hyphens, replace them with underscores in the import statement. Example:

// Project name is "Test Project" or "Test-Project"
#import "Test_Project-Swift.h"

Add the code below to your application delegate:

Objective-C:

// Register device token with IBM Cloud Push Notification Service
- (void)application:(UIApplication *)application
	 didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken{

	   [[CDVBMSPush sharedInstance] didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}

// Handle error when failed to register device token with APNs
- (void)application:(UIApplication*)application
	 didFailToRegisterForRemoteNotificationsWithError:(NSError*)error {

	  [[CDVBMSPush sharedInstance] didFailToRegisterForRemoteNotificationsWithError:error];
}

// Handle receiving a remote notification
-(void)application:(UIApplication *)application
	didReceiveRemoteNotification:(NSDictionary *)userInfo
	fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {

	[[CDVBMSPush sharedInstance] didReceiveRemoteNotificationWithNotification:userInfo];
}

// Handle receiving a remote notification on launch
- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions {

  -----------
    if (!launchOptions[UIApplicationLaunchOptionsRemoteNotificationKey]) {
        [[CDVBMSPush sharedInstance] didReceiveRemoteNotificationOnLaunchWithLaunchOptions:launchOptions];
    }
  -----------
}

//HNADLE THE NOTIFICTAION CLICK
- (void)application:(UIApplication *)application handleActionWithIdentifier:(NSString *)identifier forRemoteNotification:(NSDictionary *)userInfo completionHandler:(void (^)())completionHandler{
    
    NSMutableDictionary *userInf = [[NSMutableDictionary alloc] init];
    [userInf addEntriesFromDictionary:userInfo];
    [userInf setValue:identifier forKey:@"identifierName"];
    [[CDVBMSPush sharedInstance] didReceiveRemoteNotificationWithNotification:userInf];
    completionHandler();
    
}

Swift:

// Register device token with IBM Cloud Push Notification Service
func application(application: UIApplication,
	didRegisterForRemoteNotificationsWithDeviceToken deviceToken: NSData) {

	CDVBMSPush.sharedInstance().didRegisterForRemoteNotificationsWithDeviceToken(deviceToken)
}

// Handle error when failed to register device token with APNs
func application(application: UIApplication,
	didFailToRegisterForRemoteNotificationsWithError error: NSErrorPointer) {

	CDVBMSPush.sharedInstance().didReceiveRemoteNotificationWithNotification(error)
}

// Handle receiving a remote notification
func application(application: UIApplication,
	didReceiveRemoteNotification userInfo: [NSObject : AnyObject], 	fetchCompletionHandler completionHandler: ) {

	CDVBMSPush.sharedInstance().didReceiveRemoteNotificationWithNotification(userInfo)
}

// Handle receiving a remote notification on launch
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {

  ----------
  let remoteNotif = launchOptions?[UIApplicationLaunchOptionsKey.remoteNotification] as? NSDictionary

  if remoteNotif != nil {
    CDVBMSPush.sharedInstance().didReceiveRemoteNotificationOnLaunchWithLaunchOptions(launchOptions)
  }
  --------
}

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
 
    var userIf:[AnyHashable : Any] = userInfo
    userIf["identifierName"] = identifier
    CDVBMSPush.sharedInstance().didReceiveRemoteNotificationWithNotification(userInfo)
}

Configuring Your Android Development Environment

Download your Firebase google-services.json for android, and place them in the root folder of your cordova project: [your-app-name]/platforms/android

Go to [your-app-name]/platforms/android,

1.) Open file build.gradle (Path : platform > android > build.gradle)

2.) find buildscript text in build.gradle file.

3.) There you will find one classpath line, after that line, please add this line :

classpath 'com.google.gms:google-services:3.0.0'

4.) Then find "dependencies" .Select that dependencies where you have text compile and where that dependecies is getting ended, just after that, add this line :

apply plugin: 'com.google.gms.google-services'

5.) Prepare and build your cordova Android project

cordova prepare android
cordova build android

6.) Run your Cordova android project either opening in android studion or using cordova CLI

cordova run android

For Android Studion 3.+ users, update the build.gradle file with the folowing -

Change the,

debugCompile project(path: 'CordovaLib', configuration: 'debug') 
releaseCompile project(path: 'CordovaLib', configuration: 'release')

to

compile project(':CordovaLib')

Usage

The following BMSPush Javascript functions are available:

Javascript Function	Description
initialize(pushAppGUID, clientSecret,category)	Initialize the Push SDK.
registerDevice(options, success, failure)	Registers the device with the Push Notifications Service.
unregisterDevice(success, failure)	Unregisters the device from the Push Notifications Service
retrieveSubscriptions(success, failure)	Retrieves the tags device is currently subscribed to
retrieveAvailableTags(success, failure)	Retrieves all the tags available in a push notification service instance.
subscribe(tag, success, failure)	Subscribes to a particular tag.
unsubscribe(tag, success, failure)	Unsubscribes from a particular tag.
registerNotificationsCallback(callback)	Registers a callback for when a notification arrives on the device.

Android (Native) The following native Android function is available.

Android function	Description
CDVBMSPush. setIgnoreIncomingNotifications(boolean ignore)	By default, push notifications plugin handles all incoming Push Notification by tunnelling them to JavaScript callback. Use this method to override the plugin's default behavior in case you want to manually handle incoming push notifications in native code.

Examples

Using BMSPush

Register for Push Notifications

// initialize BMSCore SDK
BMSClient.initialize("Your Push service region");

// initialize BMSPush SDK
var appGUID = "Your Push service appGUID";
var clientSecret = "Your Push service clientSecret";

// Initialize for normal push notifications
var options = {}
BMSPush.initialize(appGUID,clientSecret,options);

// Initialize for iOS actionable push notifications, custom deviceId and varibales for Parameterize Push Notifications 
var options ={"categories":{
                      "Category_Name1":[
                        {
                          "IdentifierName":"IdentifierName_1",
                          "actionName":"actionName_1",
                          "IconName":"IconName_1"
                        },
                        {
                          "IdentifierName":"IdentifierName_2",
                          "actionName":"actionName_2",
                          "IconName":"IconName_2"
                        }
                      ]},
                    "deviceId":"mydeviceId",
                    "variables":{"username":"ananth","accountNumber":"536475869765475869"}
                  };

BMSPush.initialize(appGUID, clientSecret, options);


var success = function(response) { console.log("Success: " + response); };
var failure = function(response) { console.log("Error: " + response); };


// Register device for push notification without UserId
var options = {};
BMSPush.registerDevice(options, success, failure);

// Register device for push notification with UserId
var options = {"userId": "Your User Id value"};
BMSPush.registerDevice(options, success, failure);

IMPORTANT: Deprecated this way of adding Category in the Initialize method :- var category = {"Category_Name":[{"IdentifierName_1":"actionName_1"},{"IdentifierName_2":"actionName_2"}]} .

You can access the contents of the success response parameter in Javascript using JSON.parse:

var token = JSON.parse(response).token

Available keys
token
userId
deviceId

To unregister for push notifications, simply call the following:

BMSPush.unregisterDevice(success, failure);

Retrieving Tags

In the following examples, the function parameter is a success callback that receives an array of tags. The second parameter is a callback function called on error.

To retrieve an array of tags to which the user is currently subscribed, use the following Javascript function:

BMSPush.retrieveSubscriptions(function(tags) {
	alert(tags);
}, failure);

To retrieve an array of tags that are available to subscribe, use the following Javascript function:

BMSPush.retrieveAvailableTags(function(tags) {
	alert(tags);
}, failure);

Subscribe and Unsubscribe to/from Tags

var tag = "YourTag";
BMSPush.subscribe(tag, success, failure);
BMSPush.unsubscribe(tag, success, failure);

Receiving a Notification

var handleNotificationCallback = function(notification) {
	// notification is a JSON object
	alert(notification.message);
}

BMSPush.registerNotificationsCallback(handleNotificationCallback);

Receiving a Notification Status

 var showNotification = function(notif) {
          alert(JSON.stringify(notif));
        };
 BMSPush.setNotificationStatusListener(showNotification);

The following table describes the properties of the notification object:

Handling Notification Actions Click

To identify which action clicked use the following,

var showNotification = function(notif) {
    var identifierName = notif["identifierName"];
    alert(identifierName);
};

Parameterize Push Notifications

To enable the Parameterize IBM Cloud Push Notifications, do the following ,

1. Add the variables key vaue pair in the BMSPush.initialize options

   var options ={"categories":{
                       "variables":{"username":"ananth","accountNumber":"536475869765475869"}
                   };
   BMSPush.initialize(appGUID, clientSecret, options);
   
   

2. While sending push notification add the varibale key in {{}}

{
    "message": {
        "alert": "hello {{username}} , balance on your account {{accountNumber}} is $1200"
    }
}

Note: If the iOS app is force killed , the Parameterize based notifications may not appear in the device

Property	Description
message	Push notification message text
payload	JSON object containing additional notification payload.
sound	The name of a sound file in the app bundle or in the Library/Sounds folder of the app’s data container (iOS only).
badge	The number to display as the badge of the app icon. If this property is absent, the badge is not changed. To remove the badge, set the value of this property to 0 (iOS only).
action-loc-key	The string is used as a key to get a localized string in the current localization to use for the right button’s title instead of “View” (iOS only).

Example Notification structure:

// iOS
notification = {
	message: "Something has happened",
	payload: {
		customProperty:12345
	},
	sound: "mysound.mp3",
	badge: 7,
	action-loc-key: "Click me"
}

// Android
notification = {
	message: "Something has happened",
	payload: {
		customProperty:12345
	},
	id: <id>,
	url: <url>
}

Adding Auto signing in iOS

To set signing credentials iOS create file build.json in your app root. Follow the below patter,

Xcode 8 and iOS 10:

{
    "ios": {
        "debug": {
            "codeSignIdentity": "iPhone Developer",
            "developmentTeam": "FG35JLLMXX4A",
            "packageType": "development",
            "buildFlag": [
                "EMBEDDED_CONTENT_CONTAINS_SWIFT = YES",
                "ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES=NO",
                "LD_RUNPATH_SEARCH_PATHS = \"@executable_path/Frameworks\""
            ]
        },
        "release": {
            "codeSignIdentity": "iPhone Developer",
            "developmentTeam": "FG35JLLMXX4A",
            "packageType": "app-store",
            "buildFlag": [
                "EMBEDDED_CONTENT_CONTAINS_SWIFT = YES",
                "ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES=NO",
                "LD_RUNPATH_SEARCH_PATHS = \"@executable_path/Frameworks\""
            ]
        }
    }
}

Earlier versions:

{
    "ios": {
        "debug": {
            "codeSignIdentity": "iPhone Development",
            "provisioningProfile": "926c2bd6-8de9-4c2f-8407-1016d2d12954",
            "developmentTeam": "FG35JLLMXX4A",
            "packageType": "development"
        },
        "release": {
            "codeSignIdentity": "iPhone Distribution",
            "provisioningProfile": "70f699ad-faf1-4adE-8fea-9d84738fb306",
            "developmentTeam": "FG35JLLMXX4A",
            "packageType": "app-store"
        }
    }
}

Change teh bundle identifier in config.xml file. After that to build ios use the --buildConfig flag in cordova build command

  cordova build ios --buildConfig

Release Notes

Copyright 2016-17 IBM Corp.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.