If you attended our JavaScript Frameworks session at Adobe MAX 2013 and would like the session resources, you can find them here:

1) The presentation slides
2) The AngularJS sample Wine Cellar application
3) The Ember.js sample Wine Cellar application

Also see Christophe’s blog for the links to his github account where you can find the Backbone.js and jQuery Mobile versions of the wine cellar applications.

Thanks so much to everyone that attended (especially since it was 8am after the MAX Party ) – we hope it was worth your while

I will post the link to the session recording for anyone else interested as soon as I can find that as well…

1. Simple ToDo’s App
2. Simple Twitter Search App

Part of the reason I personally may have been hooked initially could be due to my Adobe Flex background. There’s a reminiscent feel with AngularJS to Flex in the two-way binding, HTML extension etc so I could see how a lot of Flex developers might feel at home with this framework. The framework is built on the idea that declarative programming should be used for building the UI and imperative programming for your business logic. With AngularJS you can do quite a bit with a small amount of code due to the built-in features that will be explained further in this post. It also relies on dependency injection throughout as well as the separation of the model/view/controller. Here’s a nice illustration from the AngularJS site that helps explain more:

Disclaimer

My intention is not to incite a frameworks war here. I know there are a myriad of JavaScript frameworks available that people are passionate about. I’m simply sharing my thoughts and observations .

After watching the videos above, I moved on to the tutorial, which was very easy to follow and I thought it was especially cool how they introduced testing your AngularJS app while building it using Jasmine and Testacular. I had previously only heard of those but got a much better idea of how to use them from the tutorial. It’s obvious they kept testing in mind while creating this framework.

I then decided to build myself a web application with what I had learned. I’m a big music fan, always downloading from iTunes for my running playlists etc, so I thought I’d build a simple web app that interfaced with the iTunes Search API. The resulting application is here. You can grab the project from my github account here. This was my first newbie attempt so I’m open to critique and feedback on how I could make it better. I noticed there are often multiple ways to do the same thing using AngularJS, so I’m still in the learning process of when to use what. Overall though I was impressed by how fast I was able to make it all work and how much the framework provides for you. From my Media Explorer application you can enter a search term for anything media related (artist, song name or part, video etc). Once you get the results back, try out the sort and filter to see the returned results sort and filter accordingly. The filter field will filter results as you type into it. This is all built into the array filtering mechanism in AngularJS. Currently the max number of results returned defaults to 50.

Hitting the play button on the far left of any row will bring up an overlay to play the sample media as shown below:

In the next sections I’ll cover some of the main AngularJS concepts that seem important to understand.

Data Binding

One of the first things I was most excited to see with AngularJS is that it has built-in support for two-way data binding similar to Flex (yay)! This is a big deal for data-driven applications in particular and can save you a TON of time coding. Below are two images from the AngularJS site that I think illustrate this point so well:

If you want to try a very basic example of the two-way data binding in action, I found this live sample here. If you look at the source code you’ll see how simple it is:

<div>
    Binding the value in the text field to the model name.
    <br/><br/>
    <input type="text" ng-model="name" placeholder="Enter a name here"/>
    <span ng-show="name"><h4>Hello {{name}}></h4></span>
</div>

As you type into the input field it will show up next to the ‘Hello’ string since the name field is referenced there and is also the bound model object on the HTML input (with ng-model=”name”).

Model

The model is simply a plain old JavaScript object, does not use getter/setter methods or have any special framework-specific needs. Any changes are immediately reflected in the view via the two-way binding feature. There’s a concept of scope in the AngularJS framework, where all model objects stem from. I recommend seeing the AngularJS Scope documentation for more information on this topic. Typically your model objects are initialized in your controller code with syntax like:

$scope.searchTerm = "Alicia Keys";

But in the HTML template, that model variable would be referenced in curly braces such as: {{searchTerm}} without the $scope prefix.

View

The view is the rendered HTML that contains the transformed DOM resulting from a combination of the HTML template along with the AngularJS model and controller. The AngularJS View is aware of the controller and model, and accesses it through annotated HTML directives specific to AngularJS. For example, an ng-click AngularJS ‘directive’ can be applied to a button element to call a specific method in the controller when clicked. More on directives below…

Controller

The controller is used to provide the business logic behind the view and construct and value the model. The goal is to not manipulate the DOM at all in the controller, which is something to get used to if you’ve been using other frameworks.

Filters

AngularJS filters are used to modify data in some way, similar to formatters in Flex. For instance, a built-in filter called uppercase would look like this when applied to the name string from the model in order to uppercase it upon display.

<td>{{name|uppercase}}</td>

You’re welcome to write your own filters as well. I included a custom one for fun in my application called capitalize that will simply capitalize the first letter of a string.

mediaApp.filter('capitalize', function() {
    return function(input, scope) {
        if (input!=null)
            return input.substring(0,1).toUpperCase()+input.substring(1);
    }
});

You can see it applied here:

There’s also an array filtering feature which is really cool, and you can see an example of it in the Media Explorer app. When you specify a filter string on an array in the Angular ng-repeat directive it will automatically filter the matching results into a new array.

For instance, here’s the code from the Media Explorer that specifies the filterTerm (the model object bound to the filter input HTML element) to your results list as you type (automatically applied do to the two-way data binding on the model data):

<label>Filter by
     <input type="text" ng-model="filterTerm" class="input-small"/>
</label>
...
<tr ng-repeat="item in mediaResults | filter:filterTerm | orderBy:sortProp">
     <td><button id="playBtn" class="btn" ng-click="playVideo(item)"><i class="icon-play"></i></button></td>
     <td><a href="{{item.previewUrl}}"><img ng-src="{{item.artworkUrl60}}"></a></td>
     <td>{{(item.trackName != null) item.trackName || item.collectionName}}</td>
     <td>{{item.kind | capitalize}}</td>
     <td>{{item.artistName}}</td>
     <td>{{item.collectionName}}</td>
     <td>{{item.trackPrice}}</td>
     <td>{{item.collectionPrice}}</td>
     ...

Directives

Directives are ways to transform the DOM through extended HTML. The add additional behavior. If you happen to have done Flex, it’s similar to adding a property like itemRenderer to an MXML component, or specifying click to call a function. In AngularJS there are a bunch of built-in ones you can use, most with a prefix of ‘ng’ (ng-click, ng-show, ng-change, ng-app etc). They’re actually defined with camelCase in the JavaScript, but applied with a dash to the HTML. You can also define your own directives and apply them in a similar fashion. In my Media Explorer application I wrote a couple of directives you could see for more examples. I used them to manipulate DOM elements since it’s not good practice to do so in the controller code. One called videoLoader is used to play and stop the video in the modal when the play button is clicked:

mediaApp.directive('videoLoader', function(){
    return function (scope, element, attrs){
        console.log(scope.url);
        scope.$watch("url",  function(newValue, oldValue){ //watching the scope url value
            element[0].children[0].attributes[3].value=newValue; //set the URL on the src attribute
            element[0].load();
            element[0].play();
        }, true);
        scope.$watch("showFlag",  function(newValue, oldValue){
            if (!newValue) // if the showFlag is false, stop playing the video (modal was closed)
                element[0].pause();
        }, true);
    }
});

Then to apply this videoLoader directive to my video control, I add it as an attribute with a dash, such as:

<video id="vid" width="320" height="240" video-loader="item.previewUrl" autoplay controls>
     {{url}}
     <source id="vidsrc" ng-src="url" type="video/mp4">
</video>

Services

Services are provided in AngularJS to help you do common task. For instance, there’s a built-in $http service that gives you access to make http or JSON requests etc, there’s also a $location service that gives you access to the browser location URL and helps you parse it etc. There are a bunch of others built-in and once again you can also write your own. You may write your own in the case where there’s something you know you’re going to use more than once in your application. In my application I did write a service just to try it out and use it to call the iTunes API with the $resource service, which allows you to interact with RESTful services and provides higher level behavior over the $http service (but is dependent on the $http service). My service looks like this:

mediaApp.factory('MediaService', function($resource){
    return $resource('https://itunes.apple.com/:action',
        {action: "search", callback: 'JSON_CALLBACK'},
        {get:  {method: 'JSONP'}
    });
});

Routes

You typically configure routes in your main or app.js file for an AngularJS app. For instance, mine is very basic since I’m not using multiple views and looks like this:

mediaApp.config(['$routeProvider', function($routeProvider) {
    $routeProvider.when('/', {templateUrl: 'views/media-list.html',   controller: 'MediaListCtrl'});
}]);

You can specify multiple paths for different URLs as well as a fallback. More on route configuration can be found here.

Quick Start

You can use the AngularJS seed project, or if you’re familiar with Yeoman, there’s a whole option to generate an AngularJS-based project as well as additional commands that can be run to add new routes, views, controllers etc. It’s actually really cool and easy to use, check out this article for an awesome walkthrough of it. It will even generate your stubbed out tests for testing with Jasmine / Testacular. They can’t make it much easier for us than that ! I didn’t discover this until after I created my application so my project structure doesn’t follow the Yeoman structure, but instead mirrors the AngularJS seed project structure. There are also seed projects available for using AngularJS on the front-end and Express+Node on the backend here, as well as AngularJS on the front-end, and Socket.io+Express+Node here if that fits your needs.

I’ve only scratched the surface of what this framework is about. Below is a list of resources that can be used to follow-up with more in-depth information for those interested. The AngularJS documentation is good and the community support as well from my experience. Next I plan to turn my Media Explorer web application into a mobile application using PhoneGap and will post it here so check back soon!

Useful Resources

• 5 Awesome AngularJS Features
• @briantford on Building huuuuuuge Angular apps
• AngularJS Batarang – Chrome Extension for Debugging
• AngularJS Forum
• AngularJS on Google+
• AngularJS Cheat Sheet
• AngularJS Docs
• AngularJS Blog
• @briantford on Brian Ford on AngularJS with PhoneGap
• @simpulton on The AngularJS Scope LifeCycle
• AngularJS for jQuery Developers
• @simpulton blog – lots of useful articles on AngularJS
• Dean Sofer – AngularJS Tips and Tricks

The details are all outlined well here with some sample code but I also created a quick sample project you can use for a reference that will work for both iOS and Android. I put the whole project including the XCode project in github, but you really only need the www folder for PhoneGap Build. There’s also a config.xml included you can use that includes the plugin reference there and is required for the native code to be added when built through PhoneGap Build. You will just need to change the application name, author and personal information in there to match your own You will also need to change the GCM id to match your sender id in the index.js file. Also, see my previous tutorials on push notifications for iOS and Android to get some sample code in PHP or node.js to send a push notification quickly for testing so you can see it all in action. Those posts used the previous plugins available however, you should use the most currently supported PushPlugin one now. Those posts also talk in-depth about signing up for GCM and how to use APNS as well.

I will also be holding two webinars on push notifications in February via Adobe TechLive, so come check those out for a walkthrough of how to get started with adding push notifications to your application for iOS and Android. I will talk more about the APIs and how to use them at that time as well. The PhoneGap Build team is busy working on additional support for more plugins. The currently supported ones can be found here: http://build.phonegap.com/docs/plugins.

The important parts of the code are outlined in the PushPlugin documentation but I’m also showing them from my sample here. It’s easier to see quickly how this new plugin could be used to register your device to receive notifications, and how you might handle the incoming message simply in the following:

    receivedEvent: function(id) {
        var pushNotification = window.plugins.pushNotification;
        if (device.platform == 'android' || device.platform == 'Android') {
            pushNotification.register(successHandler, errorHandler,{"senderID":"834841663931","ecb":"onNotificationGCM"});
        }
        else {
            pushNotification.register(this.tokenHandler,this.errorHandler,   {"badge":"true","sound":"true","alert":"true","ecb":"app.onNotificationAPN"});
        }
...
    }

   // iOS
    onNotificationAPN: function(event) {
        var pushNotification = window.plugins.pushNotification;
        console.log("Received a notification! " + event.alert);
        console.log("event sound " + event.sound);
        console.log("event badge " + event.badge);
        console.log("event " + event);
        if (event.alert) {
            navigator.notification.alert(event.alert);
        }
        if (event.badge) {
            console.log("Set badge on  " + pushNotification);
            pushNotification.setApplicationIconBadgeNumber(this.successHandler, event.badge);
        }
        if (event.sound) {
            var snd = new Media(event.sound);
            snd.play();
        }
    },
    // Android
    onNotificationGCM: function(e) {
        switch( e.event )
        {
            case 'registered':
                if ( e.regid.length > 0 )
                {
                    // Your GCM push server needs to know the regID before it can push to this device
                    // here is where you might want to send it the regID for later use.
                    alert('registration id = '+e.regid);
                }
            break;

            case 'message':
              // this is the actual push notification. its format depends on the data model
              // of the intermediary push server which must also be reflected in GCMIntentService.java
              alert('message = '+e.message+' msgcnt = '+e.msgcnt);
            break;

            case 'error':
              alert('GCM error = '+e.msg);
            break;

            default:
              alert('An unknown GCM event has occurred');
              break;
        }
    }

Please see the sample for the rest of the code.

Check out the site and to join a session live, simply click on the event and you will see a Join the Live Event blue button at the top that will take you into it. If you miss a session, you can still watch the recorded version after the fact in the archives. Also, feel free to provide feedback for sessions or topics you might want to see covered in the future .

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

• Check out the Pushwoosh documentation for more information.
• Intro to geofencing on iOS article
• Easy PhoneGap Push Notifications with Pushwoosh

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:

<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] : []);
	};
..

Getting Started

• 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

1. 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).



2. 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);
   	});
       },
   

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

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

   

2. 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 and Pushes 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.

Pushwoosh Plans

Here’s a quick summary page of the options available through Pushwoosh currently:

Steps to Embed Cordova WebView

Below are detailed steps on including PhoneGap/Cordova as a web subview in your native application. At the end of this section I show screenshots from a sample application I made available on my github account for you to try this out yourself or refer to things as needed.

1. Create your base native iOS application in XCode (version 4.5 recommended) unless you just plan to add to an existing native application.

In my case I chose to create a new Single View Application in XCode such as the following:



2. Download and extract the Cordova source to a permanent folder location on your hard drive (for example: ~/Documents/Cordova).
You’ll need this for copying Cordova resources into your native application.
3. Close any other Cordova projects and exit XCode (XCode can be quirky, a restart often clears up potential or possible errors).
4. Navigate to the directory where you put the downloaded Cordova source above and copy the Cordova.plist file into your native application folder on the file system (at same level as the AppDelegate files etc, see picture below). Note: you could also use a Cordova.plist from a newly created Cordova application.

   

   This file contains specific Cordova property settings and plugins required for your application to use Cordova.
5. Drag and drop the Cordova.plist file into the Project Navigator of Xcode
6. Choose the radio-button “Create groups for any added folders”, select the Finish button
7. Go to the downloaded source from the previous step above and locate the CordovaLib.xcodeproj in the CordovaLib sub-folder. Drag and drop the CordovaLib.xcodeproj file into the Project Navigator of XCode (at the same level as the .plist file copied in above – again choosing ‘Create groups for any added folders‘)
8. Select CordovaLib.xcodeproj in the Project Navigator
9. Open the File Inspector with Option-Command-1 or by going to View | Utilities | Show File Inspector
10. Ensure that it says “Relative to Group” in the File Inspector for the Location drop-down menu similar to below:



11. Select the project icon in the Project Navigator, select your application under “TARGETS” (should have an A next to it), then select the “Build Settings” tab as shown below:



12. Locate the setting for “Other Linker Flags” (under the Linking section) and double-click the value text field to bring up the box to enter the flags -all_load and -Obj-C as shown here:



13. Select the project icon in the Project Navigator, select your target, then select the “Build Phases” tab.
14. Expand “Link Binaries with Libraries”. Select the “+” button, and add these frameworks (and optionally in the Project Navigator, move them under the Frameworks group):

    AddressBook.framework
    AddressBookUI.framework
    AudioToolbox.framework
    AVFoundation.framework
    CoreLocation.framework
    MediaPlayer.framework
    QuartzCore.framework
    SystemConfiguration.framework
    MobileCoreServices.framework
    CoreMedia.framework



15. Now expand “Target Dependencies”
    Select the “+” button, and add the CordovaLib build product



16. Expand “Link Binaries with Libraries” again and add libCordova.a
17. Go to “Xcode Preferences -> Locations -> Derived Data -> Advanced…” and ensure it is set to “Unique”
18. Go back to Build Settings and locate the Header Search Paths and ensure the following properties are set (including the quotes):
    “$(TARGET_BUILD_DIR)/usr/local/lib/include”
    “$(OBJROOT)/UninstalledProducts/include”
    “$(BUILT_PRODUCTS_DIR)”
    

The result should look like the following:

Code Additions

To actually use the subview, you need to add the following Objective-C code where you want to include it.
Import the following header

#import <Cordova/CDVViewController.h>

Instantiate a new CDVViewController

CDVViewController* viewController = [CDVViewController new];

Set up the view frame

viewController.view.frame = CGRectMake(0, 0, 320, 480);

Lastly, add to your view as a subview

[myView addSubview:viewController.view];

You could optionally set the www folder, start page or option to show the splash screen to something other than the default (default folder is www, start page is index.html and splash screen is no) on that CDVViewController as well with the following lines:

viewController.wwwFolderName = @"myfolder";
viewController.startPage = @"mystartpage.html";
viewController.useSplashScreen = YES;

Here’s an example of actually implementing those lines above in my ViewController.m class that is created with a new native XCode Single View project like discussed above (the added code is in the viewDidLoad function):

#import "ViewController.h"
#import <Cordova/CDVViewController.h>

@interface ViewController ()

@end

@implementation ViewController


- (void)viewDidLoad
{
    [super viewDidLoad];
    CDVViewController* viewController = [CDVViewController new];
    viewController.view.frame = CGRectMake(0, 40, 320, 450);
    [self.view addSubview:viewController.view];
}

- (void)viewDidUnload
{
    [super viewDidUnload];
    // Release any retained subviews of the main view.
}

- (BOOL)shouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)interfaceOrientation
{
    if ([[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPhone) {
        return (interfaceOrientation != UIInterfaceOrientationPortraitUpsideDown);
    } else {
        return YES;
    }
}

- (void)dealloc {
    [super dealloc];
}
@end

In my sample application you can see it when you press the Open a new Cordova WebView button. You could choose to add this code wherever you need it, this is just one example for simple illustration.

Sample Application

In the first screenshot below, the header navigator and tab bar at the bottom (with badge), and the second view with all the text and controls are actually native iOS controls, whereas the middle embedded view with the button list is an embedded Cordova WebView containing HTML/JS to interact with the native Cordova/PhoneGap APIs to retrieve contacts, use the camera, etc.

If you’re familiar with Storyboarding in XCode for iOS, the Storyboard shows an overview and flow of the application from the native perspective, so you can see the parts which are iOS Native controls versus the other buttons etc that were included from the HTML/JS as part of the Cordova WebView:

In the next screenshot you can see how we can interact with the Cordova/PhoneGap APIs for native functions like grabbing contacts right there inside our native application:

This next view is all native iOS controls (see storyboard), but includes a button to pop up a new view that uses the same ViewController class and will have the embbeded Cordova subview:

And lastly is our next view from the button pop-up that shows how another view will also have the embedded Cordova WebView:

Grab the sample application from my github account and give it a whirl.

There’s an advanced tutorial dedicated to embedding PhoneGap for Android here, so be sure to check that out too!

Google Cloud Messaging

Android push notifications are available via the Google Cloud Messaging – GCM service (similar to Apple’s Push Notification Service). Previously they were supported through C2DM (Cloud to Device Messaging framework) but that API has since been deprecated and the Google Cloud Messaging services adds enhancements above and beyond what C2DM offered. There’s a Cordova/PhoneGap plugin available to aid in working with the Google Cloud Messaging service. The message size allotment for the GCM payload is 4kb (String data only), noticeably bigger than the Apple Push Notification requirements of 256 bytes. There’s an article about the types of messages that can be sent in detail here. Also, I suggest you look over the documentation for using this service in general here when building your application, there are a lot of details I will not cover in this post. Some points I wanted to highlight from that article are:

• GCM makes no guarantees about delivery or the order of messages.
• An Android application on an Android device doesn’t need to be running to receive messages. The system will wake up the Android application via Intent broadcast when the message arrives, as long as the application is set up with the proper broadcast receiver and permissions.
• It does not provide any built-in user interface or other handling for message data. GCM simply passes raw message data received straight to the Android application, which has full control of how to handle it. For example, the application might post a notification, display a custom user interface, or silently sync data.

Steps

The steps for setting up push notifications in your Android application are:

1. Create a new Android Cordova project either via the command line tools or Eclipse (command line recommended)
2. Download the GCM Cordova Plugin
3. Follow the steps in the plugin’s Readme
   • Don’t forget to setup your Google Cloud Messaging Account as noted in the readme and note your project id located in the URL. For instance the number in bold below is the id you need to send in the register() function:

     https://code.google.com/apis/console/?pli=1#project:824841663942

   • Don’t forget to change the following to use your GCM project id (from the step above)

                                window.GCM.register("your_sender_id", "GCM_Event", GCM_Success, GCM_Fail );
                            

     becomes

                                window.GCM.register("824841663942", "GCM_Event", GCM_Success, GCM_Fail );
                            

4. Add code handling for the actions to take when the application receives a message while open or not (ie: display a popup alert, status bar notification etc).
   Note: The plugin handles registering with GCM and has methods for receiving a message, however it does not actually provide the notification code itself, this is something you need to add. Read on further for how to add native code to produce a status bar notification.

If you need more information about GCM project creation, specific steps can be found here.

If you prefer to use Eclipse for your editing, you can simply import your existing Android project that you just created above (or the sample included in the plugin) and start working from there. Choose File | New | Project, then you will see the following dialog, where you will select Android Project from Existing Code as follows:

Running the Sample Application

When you run the sample code from the plugin, it will automatically try to register your device. If registration is successful, you should see a message containing the registration token id as I circled below in the screenshot of mine running on my Galaxy Tablet:

You should also see the following trace in your console:

10-24 18:24:20.720: V/GCMReceiver:onRegistered(21989): Registration ID arrived!
10-24 18:24:20.730: V/GCMReceiver:onRegisterd(21989): {"regid":"APA91bFobAwM7P3Okxy2al8RI12VcJFUS-giXWTOoWXIObtSPOE1h7FuH1VPLBPgshDI_Fp7aIYVET-ssvGUErlWYA0cKPGhoXT1daqyDsEfem9ZtgZNRhQFv7kLCIVSigYlpMluToPiSHSsFSEdtCDfKoOZqNPsfg","event":"registered"}
10-24 18:24:20.730: V/GCMPlugin:sendJavascript(21989): javascript:GCM_Event({"regid":"APA91bFobAwM7P3Okxy2al8RI12VcJFUS-giXWTOoWXIObtSPOE1h7FuH1VPLBPgshDI_Fp7aIYVET-ssvGUErlWYA0cKPGhoXT1daqyDsEfem9ZtgZNRhQFv7kLCIVSigYlpMluToPiSHSsFSEdtCDfKoOZqNPsfg","event":"registered"})

Once you have obtained a registration id as above, you can write server code (see the section below on using Node.JS code to send a message to your application) or use a service like Urban Airship or PushWoosh to start sending notifications. When a message is received, you will see additional text displayed as shown in the screenshot below:

At this point though, the plugin does not contain anything more to actually show a status bar notification or otherwise notify you. The next section covers how you can add some additional code to it for showing a status bar notification when the message is received.

Status Bar Notification

Since the plugin simply receives the message (whether running or not) but doesn’t do anything with it from there, you have various choices for what you could do with it. One common thing is to show a message in the native status bar. Note that on iOS the process is different and the notification is automatically shown, but on Android you have to explicitly code for it. You could use the Cordova StatusBarNotification plugin along with this one, or if you want a faster solution, you could simply add the following native Java code into your GCMIntentService.java onMessage() function:

          String message = extras.getString("message");
    	  String title = extras.getString("title");
    	  Notification notif = new Notification(android.R.drawable.btn_star_big_on, message, System.currentTimeMillis() );
    	  notif.flags = Notification.FLAG_AUTO_CANCEL;
    	  notif.defaults |= Notification.DEFAULT_SOUND;
    	  notif.defaults |= Notification.DEFAULT_VIBRATE;

    	  Intent notificationIntent = new Intent(context, TestSampleApp.class);
    	  notificationIntent.addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP);
    	  PendingIntent contentIntent = PendingIntent.getActivity(context, 0, notificationIntent, 0);
    	  
    	  notif.setLatestEventInfo(context, title, message, contentIntent);
    	  String ns = Context.NOTIFICATION_SERVICE;
          NotificationManager mNotificationManager = (NotificationManager) context.getSystemService(ns);
          mNotificationManager.notify(1, notif);

Also, don’t forget to add these imports at the top of the file to support the above code:

import android.app.Notification;
import android.app.NotificationManager;
import android.app.PendingIntent;

The above code sets the notification to include a star icon, vibration and the default sound. An example of it running on my Android Galaxy Tablet is shown below (circled in red).

When you click on the notification, the app will open and look like the following, showing that a message was in fact received:

Sending a message with node-gcm

There’s a Node.js library for sending notifications through Google Cloud Messaging as there was for Apple’s Push Notification Service as I showed in my last post. It’s called node-gcm, and below is the code I used to send my device a message (keys changed ). In the Sender parameter you need to specify the API key that Google gave you when you registered for the Google Cloud Messaging service. You received two API keys, a browser and server key, either should work here, but if one does not, try the other ! You also need to specify the token returned to your application when you registered using the plugin above. This is the registration id that was printed to the screen and console when you ran the application and called the GCM register function.

var gcm = require('node-gcm');

var message = new gcm.Message();
var sender = new gcm.Sender('AIzaSyCDx8v9R0fMsAsjoAffF-P3FCFWXlvwKgL');
var registrationIds = [];

message.addData('title','My Game');
message.addData('message','Your turn!!!!');
message.addData('msgcnt','1');
message.collapseKey = 'demo';
message.delayWhileIdle = true;
message.timeToLive = 3;

// At least one token is required - each app will register a different token
registrationIds.push('APA91bFobAwN7P3Okxy2al8RI12VcJFUS-giXWTOoWXIObtSPOE1h7FuH1VPLBPgshDI_Fp7aIYVET-ssvGUErlWYA0cKPGhoXT1daqyDsEfem9ZtgZNRhQFv7kLCIVSigYlpMluToPiSHSsFSEdtCDfKoOZqNPgfs');

/**
 * Parameters: message-literal, registrationIds-array, No. of retries, callback-function
 */
sender.send(message, registrationIds, 4, function (result) {
    console.log(result);
});
/** Use the following line if you want to send the message without retries
sender.sendNoRetry(message, registrationIds, function (result) { console.log(result); });
**/

Bundle extras = intent.getExtras();
    if (extras != null) {
        try {
          String title = extras.getString("title");
          String message = extras.getString("message");
          ....
        }
     }

Collapse Key
According to the Android developer documentation, when you define a collapse key, it will only deliver the last one with a given collapse key, therefore saving the user from becoming ‘over-notified’ such as in the case of sports scores for example.

Also, note that these status bar notifications will be shown in the expanded list (if not dismissed yet) such as in the following:

Other Plugin Options

Lastly, I wanted to point out that if you are googling about Cordova push notification plugins for Android, you may also come across another one here. This one is supposed to be more specific to using notifications from PushWoosh, which I will cover in a future post with a sample. The plugin API more closely resembles the iOS Cordova PushNotification plugin, and interestingly enough still worked in receiving push notifications from my Node.js service completely outside of the PushWoosh service when I tested it (and I did not have to add the native Java code shown above to show the status bar notification) so I wanted people to be aware of it in case they wanted to try this plugin as well.

This is part 1 of a new series to help explain how to set up and use Apple Push Notifications (APNs) in your mobile applications. Push notifications are different than local notifications in that they are coming from a 3rd party server to inform the user of something, versus a local notification which is scheduled by the application to run on the device itself without any server interaction. For instance you may receive a push notification from Facebook notifying you that someone has added you as a friend, or if you are a Words With Friends player you may receive a push notification indicating it’s your turn. An example of a local notification would be an alert popping up at a certain time or interval as a reminder from a to do application where you set a date/time to a task and the alert pops up to remind you at that specified time. To the end user they may appear the same in that they both pop alerts, can have sounds associated etc, but they are very different from a development perspective.

There are Cordova/PhoneGap plugins to do both local and push notifications for iOS, but this series will focus on push notifications. If you’re wondering about Android, there is a concept of push notifications but the setup and process is a bit different and will be covered in a later post.

The process to get started with setting up APNs can be a bit intimidating initially but it’s worth taking the time to do so as the use cases are endless. This series is intended to help you understand the whole process including setup and what is occurring on both the application and server-side with sample code to get you started quickly.

Explanation of Workflow

• Upon launch, your application communicates with the Apple Push Notification Service to authorize it to receive push notifications.
• Apple responds with a unique token that must be used in all future communications to receive push notifications.
• Your application sends that token to a 3rd party server (your own or some other provider like Urban Airship for instance), that will store it for later events when the application needs to be notified.
• When an event occurs where your application needs to receive a notification, the server script reads in the unique device token and sends a message with a pre-defined structure to the Apple Push Notification Services which then securely sends to your device. The structure may include a message, sound and badge number to display on the application launch icon or any combination of the three.

High Level How-To (details to follow):

1. iOS Provisioning Portal
• Create a new App ID with push notifications enabled and an SSL Certificate associated
• Create a new provisioning file for the above App ID and download it
• Drag new provisioning file into XCode (or via XCode Organizer)
• Associate new provisioning file with your Project in the Code Signing Options
2. Cordova/PhoneGap Plugin Setup
• Download Cordova Plugin for PushNotifications
• Add PushNotification plugin key and value to Cordova.plist
• Drag PushNotification folder to XCode Plugins Folder (create groups for any added folders) – only the PushNotification.m and PushNotification.h are needed here for the native, see next step for the PushNotification.js client side
• In Finder, copy the PushNotification.js file from your downloaded plugin into the existing www folder
• Add a script tag to refer to the new PushNotification.js
• Add methods to the AppDelegate.m (under Classes) to handle push notification events and code for handling launch of application from a push notification
3. Client Side Application Handling
• Add code to register the user’s device
• Add code to listen for notification events when app is active
• Add code for badge management (clear on relaunch from notification etc)
• Add code to check user’s notification status – which options do they have set for this application specifically (they can control notification type, badge/alert/sound)
• Add code to get pending notifications (ie: if app is opened from the push notification, we need to access that notification to get the data passed in to see if updates are needed etc)
• Include resources in your project for custom sounds or launch images to be associated with your push notification
4. Server Side Handling (Optional)
• Specify the URL to the Apple Push Notification Service gateway (sandbox or production)
• Ensure proper certificates available on server
• Specify any custom sounds
• Special any launch images
• Save registered device id’s in a database

SSL Certificates and Provisioning

The first thing you need to do is set up certificates and provisioning to provide a secure connection for communication between servers and your application. Don’t let this step scare you, it’s not that bad once you do it . There’s a great article here that documents this process with screenshots and details that you should use for this step. In the next paragraph I attempt to put words to exactly what it is you’re doing and why for those that want to understand better, but feel free to skip that paragraph if you just want to go through the setup using the article.

Setting up your Application

Now that you’re ready to start coding your HTML/JavaScript/PhoneGap application, go through the following steps to set it up:

1. Get the latest PhoneGap Push Notifications plugin from GitHub.
2. Drag and drop the PushNotification folder to the Plugins folder in XCode and select the “Create groups for any added folders” as the copy option as shown in the screenshot.



3. Go out of XCode and into Finder and copy the PushNotification.js file into your www folder (or in a subfolder called plugins underneath the www folder to keep it cleaner). It will automatically show up in XCode for you. You cannot drag a file into XCode into this folder because of the way that it’s set up as a folder reference (icon is blue). See the sample project for further reference.
4. Add a script tag to refer to the PushNotification.js file in your HTML file such as:

   <script src="js/PushNotification.js"></script>
   

   Rather than adding the PushNotification.js file directly into the www root folder in your Finder, you may want to create a plugins subfolder to contain them in case you end up using others. If you do create that subfolder than your script tag needs to reference the file as below in your HTML instead:

   <script src="js/plugins/PushNotification.js"></script>
   

5. Add the plugin key and value to your Cordova.plist (found under your project root Resources folder)

The Cordova PushNotification plugin gives you a nice JavaScript API you can use from your HTML/JS files to interact with the underlying native code for handling the registration and receiving of push notifications. Some of the functions provided are listed here:

To use it though, you first need to add some things to the native application code to bridge to the specific push notification code. The AppDelegate class for an application (located under your project Classes folder) implements the handlers for application-wide events, such as application launch, termination and more. There are also events available for handling notifications. A list of them can be found here in the Handling Notifications reference. These methods are not implemented by default though, so in order to support them we need to add the code handlers and have them delegate to our included PushNotification.m class in our plugin code. The code to add is shown in the README for the plugin but I’ll paste it here as well for further reference. You’re basically handling three events with it:

Add the following code block to your AppDelegate.m class before the @end to handle the notification events:

/* START BLOCK */
#pragma PushNotification delegation

- (void)application:(UIApplication*)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken
{
    PushNotification* pushHandler = [self.viewController getCommandInstance:@"PushNotification"];
    [pushHandler didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}

- (void)application:(UIApplication*)app didFailToRegisterForRemoteNotificationsWithError:(NSError*)error
{
    PushNotification* pushHandler = [self.viewController getCommandInstance:@"PushNotification"];
    [pushHandler didFailToRegisterForRemoteNotificationsWithError:error];
}

- (void)application:(UIApplication*)application didReceiveRemoteNotification:(NSDictionary*)userInfo
{
    PushNotification* pushHandler = [self.viewController getCommandInstance:@"PushNotification"];
    NSMutableDictionary* mutableUserInfo = [userInfo mutableCopy];

    // Get application state for iOS4.x+ devices, otherwise assume active
    UIApplicationState appState = UIApplicationStateActive;
    if ([application respondsToSelector:@selector(applicationState)]) {
        appState = application.applicationState;
    }

    [mutableUserInfo setValue:@"0" forKey:@"applicationLaunchNotification"];
    if (appState == UIApplicationStateActive) {
        [mutableUserInfo setValue:@"1" forKey:@"applicationStateActive"];
        [pushHandler didReceiveRemoteNotification:mutableUserInfo];
    } else {
        [mutableUserInfo setValue:@"0" forKey:@"applicationStateActive"];
        [mutableUserInfo setValue:[NSNumber numberWithDouble: [[NSDate date] timeIntervalSince1970]] forKey:@"timestamp"];
        [pushHandler.pendingNotifications addObject:mutableUserInfo];
    }
}
/* STOP BLOCK */

The above code essentially creates a reference to our PushNotification class, sets or reads some values (not going into detail here to keep this less complicated), and calls different methods with parameters depending on the event that occurred.

The last thing you need to do is add a code fragment into the didFinishLaunchingWithOptions method in that same AppDelegate.m class to handle opening the application from a notification (and adding the received object to the pendingNotifications for later retrieval). Add this block right before the end return YES:

    /* Handler when launching application from push notification */
    // PushNotification - Handle launch from a push notification
    NSDictionary* userInfo = [launchOptions objectForKey:UIApplicationLaunchOptionsRemoteNotificationKey];
    if(userInfo) {
        PushNotification *pushHandler = [self.viewController getCommandInstance:@"PushNotification"];
        NSMutableDictionary* mutableUserInfo = [userInfo mutableCopy];
        [mutableUserInfo setValue:@"1" forKey:@"applicationLaunchNotification"];
        [mutableUserInfo setValue:@"0" forKey:@"applicationStateActive"];
        [pushHandler.pendingNotifications addObject:mutableUserInfo];
    }
/* end code block */

PushNotification Plugin – JavaScript APIs

Now that you have the project setup complete including the native Objective-C handlers above, you can actually start coding with the Cordova PushNotification JavaScript interfaces. Below is further detail about some of them and examples of interacting with then in your code. Note: there are others that are available but not covered specifically yet in this post.

Register Device
The PhoneGap PushNotification plugin offers a registerDevice() API to register your application with Apple’s Push Notification Service to receive push notifications. In the function you specify exactly which types of notifications are enabled (alerts/badges/sounds). The result is a unique device token that can then be used by the server-side to send the notification to that device.

An example of using the registerDevice() function is included in the sample project and is also shown below:

        var pushNotification = window.plugins.pushNotification;
        pushNotification.registerDevice({alert:true, badge:true, sound:true}, function(status) {
            app.myLog.value+=JSON.stringify(['registerDevice status: ', status])+"\n";
            app.storeToken(status.deviceToken);
        });

Once the above code is in place and your application is run, you will receive an alert like the following prompting if it’s ok to receive push notifications (this results in a setting that can be modified in your device settings as needed):

Get Pending Notifications
Pending notifications are those notifications that are received while the application was not active. When the application is launched you will want to retrieve them so you can handle the data sent to you as needed. The getPendingNotifications() function is available in the API for that purpose. Below is some example code:

        var pushNotification = window.plugins.pushNotification;
        pushNotification.getPendingNotifications(function(notifications) {
            app.myLog.value+=JSON.stringify(['getPendingNotifications', notifications])+"\n";
            console.log(JSON.stringify(['getPendingNotifications', notifications]));
        });
        

Get Notification Status
This method will return type and which notifications are enabled (alert, sound, badge).

        var pushNotification = window.plugins.pushNotification;
        pushNotification.getRemoteNotificationStatus(function(status) {
            app.myLog.value+=JSON.stringify(['Registration check - getRemoteNotificationStatus', status])+"\n";
        });
        

Set Badge Number
You will likely need to set the badge number on the application icon as you process the notifications, for instance if you open from a push notification just received, you may want to decrement or clear it. Setting the badge number to 0 will remove or clear the badge as shown below.

        var pushNotification = window.plugins.pushNotification;
        app.myLog.value+="Clear badge... \n";
        pushNotification.setApplicationIconBadgeNumber(num);
        

Anatomy of an Apple Push Notification

The maximum size for a notification payload is 256 bytes. If that limit is exceeded, it will be refused. Also note the delivery of notifications is “best effort” and not guaranteed, according to the Apple documentation, so you should not use it for sending critical or sensitive data, only to notify that new data is available. The notification payload is a JSON dictionary object that needs to contain another dictionary identified by the key aps. The aps dictionary then will contain one or more properties that would specify an alert to display, a number badge to set on the application icon and/or a sound to play when the notification occurs. It’s also possible to create a custom payload but that is beyond the scope of this post. The alert object itself can contain just a string of text to display, OR a dictionary object with keys for a body, custom action button text to display and a custom launch image that can be set. More specific details about the payload can be found here.

Here’s an example of a simple payload in bytes:

A typical aps dictionary object will contain 3 properties; alert, badge and sound, such as shown in the following output:

applicationLaunchNotification = 0;
applicationStateActive = 0;
aps = {
alert = {
“action-loc-key” = Play;
body = “Your turn!”;
“launch-image” = “mysplash.png”;
};
badge = 5;
sound = “notification-beep.wav”;
};
messageFrom = Holly;
timestamp = “1350416054.782263″;

Server-Side Code Handling

Simple Server

Listening for device registration token with Node.js
Below is example code you could use to get started with a server-side solution to handling device token registration which I currently call from my application sample to show how and at which point you might want to communicate with a 3rd party server to store device tokens after receiving the device token from Apple. Currently it doesn’t do anything with the token other than show that it and the message were received, but the next step would be to store the users’s device token and any other information in a database for later use when a push notification needs to be sent (such as shown in the next example). I plan to do a Part 2 series on integrating with MongoDB so check back soon!

var http = require('http');
var apn = require('apn');
var qs = require('querystring');

var server = http.createServer(function (req, res) {
	if(req.method === "POST") {
		var fullBody="";
	
		req.on('data', function(chunk)	
		{
			fullBody += chunk;
			console.log("Full body " + fullBody);
		});

		req.on('end', function()
		{
			var data = qs.parse(fullBody);
			console.log("Token " +data.token);
			console.log("Message " + data.message);
			var myDevice = new apn.Device(data.token);
			// Now we need to store it! Add code to interface with a db below...

			res.writeHead(200, {"Content-Type": "text/plain"});
			res.end("Thank you for registering\n");
			res.end();
		});
	}
}).listen(8888);
console.log("Server running at http://127.0.0.1:"+server.address().port);

Note: I’m simply running this script using Node.js on my localhost. When testing from your actual device (since push notifications are not supported in the emulator), you can set up a Manual HTTP Proxy in your device’s Wi-Fi settings to point to the IP Address of your computer. Go to your Wi-Fi network and scroll to the bottom of the settings to set the Manual Proxy server and port. Here’s an example of mine:

Sending a Notification with Argon (Node.js API)

Below is an example of some simple code to show how you could use the argon open source Node.js API to send a push notification to a users device. I simply hard-coded my device tokens in for quick testing, but ultimately you would be retrieving them from a database (after being stored above) to use for sending the push notifications.

var http = require('http');
var apn = require('apn');
var url = require('url');

var myPhone = "d2d8d2a652148a5cea89d827d23eee0d34447722a2e7defe72fe19d733697fb0";
var myiPad = "51798aaef34f439bbb57d6e668c5c5a780049dae840a0a3626453cd4922bc7ac";

var myDevice = new apn.Device(myPhone);

var note = new apn.Notification();
note.badge = 1;
note.sound = "notification-beep.wav";
note.alert = { "body" : "Your turn!", "action-loc-key" : "Play" , "launch-image" : "mysplash.png"};
note.payload = {'messageFrom': 'Holly'};

note.device = myDevice;

var callback = function(errorNum, notification){
	console.log('Error is: %s', errorNum);
	console.log("Note " + notification);
}
var options = {
	gateway: 'gateway.sandbox.push.apple.com', // this URL is different for Apple's Production Servers and changes when you go to production
	errorCallback: callback,
	cert: 'PushNotificationSampleCert.pem',                 
	key:  'PushNotificationSampleKey.pem',                 
	passphrase: 'myPassword',                 
	port: 2195,                       
	enhanced: true,                   
	cacheLength: 100                  
}
var apnsConnection = new apn.Connection(options);
apnsConnection.sendNotification(note);

Sample Project

I’ve included a link to a sample project on GitHub that I created for a reference application since it includes everything discussed above already in place. You can’t actually use this project out of the box because you have to have your own uniqe App ID and Provisioning files set on your project for it so you are better off starting your own project from scratch and using mine for reference only. I created this project to eventually be cross-platform using the cordova-client tool, but currently only iOS is setup so refer to the PGPushNotificationSample/platforms/ios path for the iOS specific code. You’ll find all of the JavaScript functions in the PGPushNotificationSample/platforms/ios/www/js/index.js file. I chose straight JavaScript in favor of simplicity. It also does an XMLHttpRequest to my simple server code (example shown above) and sends the device token received from the registration.

Check back soon for more posts to come related to this topic!

Related Links

Local versus Push Notifications (in-depth explanation from Apple)
Apple Push Service Details
Apple Push Notification Services Tutorial by Ray Wenderlich
Apple Push Notifications Provider Server Tutorial
Argon – Apple Push Notifications API in Node.js
APNS-PHP – Apple Push Notifications API for PHP