개발 이야기: Easy PhoneGap Push Notifications with Pushwoosh

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 thePushwoosh 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:

<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:

...

    // Call this to register for push notifications and retreive a deviceToken

    PushNotification.prototype.registerDevice = function(config, success, fail) {

        cordova.exec(success, fail, "PushNotification", "registerDevice", config ? [config] : []);

    };

    // Call this to set tags for the device

    PushNotification.prototype.setTags = function(config, success, fail) {

        cordova.exec(success, fail, "PushNotification", "setTags", config ? [config] : []);

    };

    //Android Only----

    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", []);

    };

    //Android End----

    //iOS only----

    // Call this to send geo location for the device

    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:

There’s a guide to specifically getting the certificate and key set up through Apple here, or you can also visit my Push Notifications for iOS post.

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:

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:

//uncomment this code if you would like to receive the notifications in the app bypassing notification center if the app is in the foreground

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

Stats
The Pushwoosh web client also has a Stats page to help you determine how many messages you’ve pushed etc. You can also determine if the messages were successful or potential errors by combining data here along with the Pushes page. Here are a couple of screenshots from Stats andPushes pages respectively:
Advanced Notifications
You can configure more advanced notifications that can have the notification open a URL or custom page when clicked containing HTML content and images etc. You can also set a special sound for iOS and Android, a badge (iOS), and options in the advanced notifications options.
Here’s a screenshot of how you can use their website to create a new page to be shown upon notification click:

And here it is when opened on iOS from clicking the notification:
Geozones
You can set up locations as zones to automatically push messages to the device when it has entered that zone through their Geozones feature. This is very useful for geofencing type apps. More to come in a further blog post on that!
Tags
Use their API’s for setting tags to identify different types of users or preferences etc. More information about Pushwoosh and using tags can be found here.

The PhoneGap plugins for Pushwoosh include support for this as well .
Great Support
I was very impressed with the support I received while trying out this service. They were quick to respond with meaningful information and went out of their way to add some additional code to aid in some specific testing I was doing to try out their geozones offering which I will be posting about specifically next.
New Features Coming…
In my exchanges I was also informed of some cool new features in the works and big enhancements to their Stats and website overall so it definitely seems like a great option to check out! Keep up with the latest happenings on their blog here.