Geo-based Push Notifications with PhoneGap and Pushwoosh

December 11, 2012By 3 Comments

Recently I blogged about sending push notifications via the Pushwoosh service and specifically with PhoneGap applications. While working with the service I noticed it had something built in for setting up geozones for your push notifications (aka: geofencing). If you’re not familiar with this term, it’s basically the ability to send push notifications to a device when it’s in a certain location or zone. There’s a really great article about it here. This is something I’ve seen many real application uses for myself in my connections with people so I was particularly interested in trying out their service with it and sharing it.

If you haven’t looked at the previous post regarding the Pushwoosh service and push notifications, I suggest you do that first before continuing…

Overview

The way the Pushwoosh service implements geo-based notifications is by comparing the devices’ current location to the geographic zones that were defined for that application either through their web interface or their APIs to see if there’s a match. An example of the interface to define them on their website is shown below:

Notice the Find location link that brings up a map to help you find latitude/longitude more quickly and set it in your form as shown in the screenshot:

When a match is found, the notification text (and any additional settings including an HTML page or URL to open when the notification is clicked for advanced notifications) are then displayed.

Use with PhoneGap

Currently their sample PhoneGap applications show this implemented with a combination of the PhoneGap Geolocation API and the Pushwoosh APIs. So the PhoneGap Geolocation API is used to track the users location via the following functions, which may vary depending on exactly how you want your application to track, but you get the idea:

navigator.geolocation.getCurrentPosition(geolocationSuccess, geolocationError);
navigator.geolocation.watchPosition(geolocationSuccess, geolocationError, { maximumAge: 3000, enableHighAccuracy: true });

and when the device location changes, the following Pushwoosh PushNotification APIs are used to send the location (found in the PushNotification.js file under each of the Android-PhoneGap and iPhone-PhoneGap projects):

        //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----
	
	// Call this to send geo location for the device
	PushNotification.prototype.sendLocation = function(config, success, fail) {
		cordova.exec(success, fail, "PushNotification", "sendLocation", config ? [config] : []);
	};

	PushNotification.prototype.onDeviceReady = function() {
		cordova.exec(null, null, "PushNotification", "onDeviceReady", []);
	};

	// Call this to get a detailed status of remoteNotifications
	PushNotification.prototype.getRemoteNotificationStatus = function(callback) {
		cordova.exec(callback, callback, "PushNotification", "getRemoteNotificationStatus", []);
	};

	// Call this to set the application icon badge
	PushNotification.prototype.setApplicationIconBadgeNumber = function(badge, callback) {
		cordova.exec(callback, callback, "PushNotification", "setApplicationIconBadgeNumber", [{badge: badge}]);
	};

	// Call this to clear all notifications from the notification center
	PushNotification.prototype.cancelAllLocalNotifications = function(callback) {
		cordova.exec(callback, callback, "PushNotification", "cancelAllLocalNotifications", []);
	};

An example of how this might look in your applications’ JavaScript is below:

deviceready: function() {
    navigator.geolocation.getCurrentPosition(geolocationSuccess, geolocationError);
    navigator.geolocation.watchPosition(geolocationSuccess, geolocationError, { maximumAge: 3000, enableHighAccuracy: true });

    function geolocationSuccess(position) {
        pushNotification.sendLocation({lat:position.coords.latitude, lon:position.coords.longitude},
        function(status) {
           console.warn('sendLocation success');
        },
        function(status) {
           console.warn('sendLocation failed');
    });
    function geolocationError(error) {
	alert('code: '    + error.code    + '\n' +
	'message: ' + error.message + '\n');
    }
};

Download the complete sample for Android and iOS with PhoneGap here for more details.

Additionally there are obviously some differences in the native code between iOS and Android and how things are handled, but I won’t go into detail about that here. One thing you should be aware of though is that on Android you need to call the following to start and stop receiving geo-based push notifications:

pushNotification.startGeoPushes();
pushNotification.stopGeoPushes();

Refer to the sample Android-PhoneGap project for more details…

iOS Handling

As some may be thinking, on iOS the location updates will stop as soon as the application goes to the background. However, there is a flag you can set on your application to allow it to continue to receive location updates so you will still receive your notifications. The flag is set in the application .plist file to set the background mode (UIBackgroundModes is the official name of the key). Note that this .plist is different from the Cordova.plist, and is typically named as YourAppName-Info.plist.

Keeping the application in the background and performing continuous location pinging will use up the battery more quickly. On iOS there is a native low-power significant change location API available that could be used instead (as opposed to the standard location API that the PhoneGap geolocation APIs use). I found a PhoneGap Geofencing plugin available that appears to do this but I haven’t tried it yet myself. Feel free to give it a try and post back :)

Additional Notes and Links

Note that the geozones are only available on memberships above the free level. View the plans here.

Filed in: CordovaHTML/JSiOSMobile DevelopmentPhoneGap Tags:

About the Author ()

Comments (3)

Trackback URL | Comments RSS Feed

  1. Nate says:

    This is great info, I see endless possibilities with this service. Beyond instant coupons there are hundreds of uses for this sort of service.

  2. Vasilis says:

    Hello Holy!
    I would like some clarifications on geo-based push notifications. In order to work does the app need to run in the background at least? I mean if the app is killed is it possible to make use of the GPS coordinates and compare to the ones you need the push to be sent? I am pretty sure that in iOS at least this in not possible. I ve heard though that you can make use of the GPS coordinates on android even when the app is killed. Do you know something about it?

Leave a Reply