Cordova Plugin for the IBM Bluemix Mobile Services Push SDK
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.
Below videos demonstrate how to install and use the Cordova Plugin for the IBM Bluemix Mobile Services Push SDK in iOS and Android applications.
-
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} -
Edit
config.xmlfile and set the desired application name in the<name>element instead of a default HelloCordova. -
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>
-
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="23" /> <!-- 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.
Run the following commands according to which platform you want to add to your Cordova application
cordova platform add ios@3.9.0
cordova platform add androidIMPORTANT: Make sure you use this iOS version for the cordova platform. It is required for the cordova app to build.
From your Cordova application root directory, enter the following command to install the Cordova Push plugin.
cordova plugin add ibm-mfp-pushThis also installs the Cordova Core plug-in, which initializes your connection to Bluemix.
From your app root folder, verify that the Cordova Core and Push plugin were installed successfully, using the following command.
cordova plugin list-
Follow the
Configuring Your iOS Development Environmentinstructions from Bluemix Mobile Services Core SDK plugin -
Uncomment the following Push import statements in your bridging header. Go to
[your-project-name]/Plugins/ibm-mfp-core/Bridging-Header.h:
//#import <IMFPush/IMFPush.h>
//#import <IMFPush/IMFPushClient.h>
//#import <IMFPush/IMFResponse+IMFPushCategory.h>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:
// Register device token with Bluemix Push Notification Service
- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken{
[[CDVMFPPush sharedInstance] didRegisterForRemoteNotifications:deviceToken];
}
// Handle error when failed to register device token with APNs
- (void)application:(UIApplication*)application
didFailToRegisterForRemoteNotificationsWithError:(NSError*)error {
[[CDVMFPPush sharedInstance] didFailToRegisterForRemoteNotifications:error];
}
// Handle receiving a remote notification
-(void)application:(UIApplication *)application
didReceiveRemoteNotification:(NSDictionary *)userInfo
fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
[[CDVMFPPush sharedInstance] didReceiveRemoteNotification:userInfo];
}
// Handle receiving a remote notification on launch
- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions {
[[CDVMFPPush sharedInstance] didReceiveRemoteNotificationOnLaunch:launchOptions];
}// Register device token with Bluemix Push Notification Service
func application(application: UIApplication,
didRegisterForRemoteNotificationsWithDeviceToken deviceToken: NSData) {
CDVMFPPush.sharedInstance().didRegisterForRemoteNotifications(deviceToken)
}
// Handle error when failed to register device token with APNs
func application(application: UIApplication,
didFailToRegisterForRemoteNotificationsWithError error: NSErrorPointer) {
CDVMFPPush.sharedInstance().didFailToRegisterForRemoteNotifications(error)
}
// Handle receiving a remote notification
func application(application: UIApplication,
didReceiveRemoteNotification userInfo: [NSObject : AnyObject], fetchCompletionHandler completionHandler: ) {
CDVMFPPush.sharedInstance().didReceiveRemoteNotification(userInfo)
}
// Handle receiving a remote notification on launch
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
CDVMFPPush.sharedInstance().didReceiveRemoteNotificationOnLaunch(launchOptions)
}Android development environment does not require any additional configuration. You can open the Android Project generated by Cordova in [your-app-name]/platforms/android directory with Android Studio or use Cordova CLI to build and run it.
The following MFPPush Javascript functions are available:
| Javascript Function | Description |
|---|---|
| registerDevice(settings, 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 |
|---|---|
| CDVMFPPush. 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. |
var settings = {
ios: {
alert: true,
badge: true,
sound: true
}
}
var success = function(response) { console.log("Success: " + response); };
var failure = function(response) { console.log("Error: " + response); };
MFPPush.registerDevice(settings, success, failure);The settings structure contains the settings that you want to enable for push notifications. You must use the defined structure and should only change the boolean value of each notification setting.
Android does NOT make use of the settings parameter. If you're only building Android app, pass an empty object, e.g.
MFPPush.registerDevice({}, success, failure);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:
MFPPush.unregisterDevice(success, failure);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:
MFPPush.retrieveSubscriptions(function(tags) {
alert(tags);
}, failure);To retrieve an array of tags that are available to subscribe, use the following Javascript function:
MFPPush.retrieveAvailableTags(function(tags) {
alert(tags);
}, failure);var tag = "YourTag";
MFPPush.subscribe(tag, success, failure);
MFPPush.unsubscribe(tag, success, failure);var handleNotificationCallback = function(notification) {
// notification is a JSON object
alert(notification.message);
}
MFPPush.registerNotificationsCallback(handleNotificationCallback);The following table describes the properties of the notification object:
| 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>
}Copyright 2015 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.