I recently posted regarding the use of Push Notifications on both
iOS and
Androidwith
PhoneGap. Both of those addressed sending push notifications from a general 3rd party server where you write the server side push code. However, there are many services out there you can leverage for sending push notifications as well and this post will address
Pushwoosh in particular.
What’s nice about Pushwoosh is they have a free offering with basic push features to get you started and their service applies to multiple platforms in general as well as offering plugins and samples for PhoneGap applications targeting
iOS,
Android, and
Windows Phone 7. I noticed there also appears to be a
plugin available and supported with PhoneGap Build. With all the PhoneGap support it seemed like a great service to blog about in addition to my recent push notification posts.
Overview
To use Pushwoosh, your PhoneGap application uses a
PushNotification plugin to communicate with the
Pushwoosh APIs. You configure this plugin just like any other. For iOS you add it to the Cordova.plist and put the classes in the plugins folder. Below is an example of how the plugin looks in the Cordova.plist.
For Android you include the jars/java files and add the plugin to the list of plugins for your app (usually in config.xml or cordova.xml), for instance:
1
2
3
4
5
6
7
|
< plugins >
...
< plugin name = "Camera" value = "org.apache.cordova.CameraLauncher" />
< plugin name = "Contacts" value = "org.apache.cordova.ContactManager" />
< plugin name = "PushNotification" value = "com.pushwoosh.test.plugin.pushnotifications.PushNotifications" onload = "true" />
...
</ plugins >
|
For both platforms you’ll see a PushNotification.js file in the samples that has a set of calls for registering/unregistering for push notifications, as well as some other nice functions (sending current location, getting status etc), an excerpt is shown below:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
|
...
PushNotification.prototype.registerDevice = function (config, success, fail) {
cordova.exec(success, fail, "PushNotification" , "registerDevice" , config ? [config] : []);
};
PushNotification.prototype.setTags = function (config, success, fail) {
cordova.exec(success, fail, "PushNotification" , "setTags" , config ? [config] : []);
};
PushNotification.prototype.unregisterDevice = function (success, fail) {
cordova.exec(success, fail, "PushNotification" , "unregisterDevice" , []);
};
PushNotification.prototype.startGeoPushes = function (success, fail) {
cordova.exec(success, fail, "PushNotification" , "startGeoPushes" , []);
};
PushNotification.prototype.stopGeoPushes = function (success, fail) {
cordova.exec(success, fail, "PushNotification" , "stopGeoPushes" , []);
};
PushNotification.prototype.sendLocation = function (config, success, fail) {
cordova.exec(success, fail, "PushNotification" , "sendLocation" , config ? [config] : []);
};
..
|
Actual example usage of the PushNotification.js calls from JavaScript can be found under the Android Setup section further on in this post…
Getting Started
It will save you time to keep
this link open in a browser for the Pushwoosh documentation reference.
- Go to the Pushwoosh website, click on Start Now and sign up for a free account/
- Once logged in, you will be taken to an applications page.
- Create a new application and name it something meaningful to you. The name doesn’t have to match anything in particular, but you will use the associated app id (more to come on that).
- Once created, configure the different platforms your application will run on. In my case I just configured iOS and Android for use with a PhoneGap application.
- Android Configuration requires a Google Cloud Messaging API Key (see below for more setup details):
- iOS Configuration requires your Apple certificate (.cer file) and key (.p12) if you’re using the manual and free service:
Be sure to use the exact app ID and package name chosen in the Apple Developer Portal in your iOS application in XCode as well. If you’ve ever done push notifications with iOS this should be a familiar process to you.
If you have a premium account much of this manual configuration work can be done for you by just entering your Apple credentials in the Auto tab above.
Android Application Setup
Requirements
- Google Cloud Messaging (GCM) Project Number
It can be found in the URL after the #project, for example my GCM console URL is: https://code.google.com/apis/console/#project:824842663931, so my GCM project # is 824842663931.
- Pushwoosh App ID
This is found when you click on any of the applications defined within Pushwoosh, such as circled in the screenshot below:
Steps
- Download the Pushwoosh Android for PhoneGap sample either from the Pushwoosh applications page by hovering over the platform such as shown in the screenshot below, or go to this link to always grab the latest (be sure to pick the Android-PhoneGap link).
- Now follow these instructions to make your application work with Pushwoosh. Step 6 is where you need to use your own GCM project number and Pushwoosh app id as noted in the requirements. Here’s an example of some code to register the device and listen for push notifications:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
initPushwoosh: function () {
var pushNotification = window.plugins.pushNotification;
pushNotification.registerDevice({ projectid: "824842663931" , appid : "A49E7-43076" },
function (status) {
var pushToken = status;
console.warn( 'push token: ' + pushToken);
},
function (status) {
console.warn(JSON.stringify([ 'failed to register ' , status]));
}
);
document.addEventListener( 'push-notification' , function (event) {
var title = event.notification.title;
var userData = event.notification.userdata;
if ( typeof (userData) != "undefined" ) {
console.warn( 'user data: ' + JSON.stringify(userData));
}
navigator.notification.alert(title);
});
},
|
By default you will not see notifications while the application is running or in the foreground. If you would like to still receive them while the application is open on Android, uncomment the following line in the
PushNotification.java code:
1
2
|
cordova.getActivity().registerReceiver(mReceiver, intentFilter);
|
iOS Application Setup
- Retrieve your Pushwoosh App ID. As above, this is found when you click on any of the applications defined within Pushwoosh, such as circled in the screenshot below:
- Next simply follow the in-depth instructions here.
Other Cool Stuff
Pushwoosh Plans
Here’s a quick summary page of the options available through Pushwoosh currently: