PhoneGap Overview

Quick Links

PhoneGap is Cordova? Wait…what?

PhoneGap is a native wrapper & web platform that exposes native mobile device APIs and data to JavaScript. There are many pros and cons to using a cross-platform solution like PhoneGap compared to writing native code, and those discussion points are outside of the scope of this documentation. You’re here because you’re planning on using PhoneGap and want to integrate push notifications to your application.

Just so you know, PhoneGap has been accepted into the Apache Software Foundation for incubation as Apache Cordova, where it will remain free and open source. This will ensure open, independent stewardship of the project over the long term. More information on the Apache Cordova project can be found here:

At the time of writing (July 2012), there is no difference between Cordova and PhoneGap, eventually the relationship between Cordova and PhoneGap will be analogous to WebKit and Chrome/Safari. Cordova (as an open source Apache project) will provide the core functionality and PhoneGap will extend it with other plugins and support, etc.

Tip: When searching for help with PhoneGap, try searching with PhoneGap in the query and then with Cordova.

PhoneGap Push Notification Plugin

An important point to understand is that when a push notification arrives to your device, it is delivered to the OS, and then delivered to your application. With PhoneGap, we need to take the push from the PhoneGap Native Wrapper and send it to your Javascript application inside PhoneGap. To do this, we wrote a PhoneGap Push Notification Plugin for iOS and Android. The next section will provide some more details into how a PhoneGap plugin works, and the specific implementations will be documented in their respective tutorials. In both platforms, a Javascript event is fired when a push arrives. If the application is open, then inAppPushReceived fires. If the application was closed when the push arrived, the outOfAppPushReceived event will fire as soon as the app was opened (this is useful to know that a user clicked on a notification, allowing you to go directly to the correct view inside the application).

PhoneGap Plugins

This section serves as a general background to PhoneGap plugins. It won’t tell you completely how to write a plugin on your own, but it will give you a good idea of how they work so you understand what the push plugin is doing for you.

There is a barrier between the native (Java/Objective C) and the PhoneGap (Javascript) applications. Plugins are the PhoneGap way of crossing that barrier.

Cordova.exec() is your core JS function. There are 5 parameters that are sent with the function call (in this order): the success callback, the error callback, the plugin name, the plugin action, and a dictionary of options. PhoneGap will call the execute() method in a plugin class on the native side, passing in the action, options, and callbackId. As suggested by the use of callbacks, the call is asynchronous. An immediate PluginResult is returned to indicate if the call was successful or not. When the call is complete, the PhoneGap plugin will return the results back to the JS side via the Success or Error callback.ier. The diagram below illustrates both scenarios, having the Javascript execute a native function, and the native function executing a javascript function.

If the native side wants to communicate with the JS, there is a method called sendJavascript that allows you send any arbitrary Javascript. In a PhoneGap plugin, we have already set up a target function in the window.plugins namespace, such as “window.plugins.pushNotification.notificationReceieved(data, inApp)” that is called when a push arrives.

Starting Your Application – Where to begin

The Apache Cordova project has a well documented API and reference for starting all forms of PhoneGap projects at The tutorial on this site will discuss only two platforms: iOS and Android. To get started, you should follow the detailed, step-by-step explanation (with screenshots) at the Apache Cordova site.

Adding Push to Your Application

You have made it this far, now it is time to actually implement push. We have documentation on both iOS and Android and code snippets ready to be copied into your project. We’ve tried to minimize the amount of native code you need to be exposed to.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s