Lately I’ve been working with Phonegap a lot for my new project AppPresser.

Phonegap is a great product, and it’s pretty easy to use once you get the hang of it. The problem is that there are quirks that can hang you up as a beginner.

This is the stuff no one tells you until you encounter the problem, and search for the solution on stack overflow. I hope it helps!

1. Phonegap and Cordova in the CLI

$ phonegap build ios

There are 2 different commands to build phonegap, ‘phonegap’ and ‘cordova’. They both do similar things, but you have to install them to your command line separately.

The phonegap command is used for phonegap build, to build your app remotely. You can also use it to build locally, I found that using ‘phonegap build ios’ and ‘cordova build ios’ do the same thing. You just have to use ‘phonegap remote build ios’ if you are using phonegap build.

Note: I made a video about my workflow with the Phonegap CLI here.

Adding Plugins

As of Phonegap 3.0, all of the features like the camera and contacts are in plugins. That means a fresh phonegap project does nothing by itself. Yay.

If you add a plugin for a local build, you have to use the CLI.

If you are using the phonegap command, it looks like this:

$ phonegap local plugin add

Hint: ignore the $ if you are typing this into terminal, and make sure you cd (change directory) into your phonegap project folder before running that command.


If you are using the cordova command, it looks like this:

$ cordova plugin add org.apache.cordova.device


(That’s a link to version 3.1. Make sure you change the docs to whatever version you are using, it’s a dropdown at the top right of the docs site)

Adding plugins for phonegap build is a totally different process, see my notes on that below.

Hint: if you are trying to do something and it’s not working, make sure you have the correct plugins installed. For example, if you want to use the offline event listener, you have to have the connection plugin already installed. Splash screens won’t work without the plugin, even if the images are in your project, etc.

2. iOS7 and Phonegap

iOS7 killed a lot of my joy with phonegap, mostly because of the status bar, but it’s getting better.

When I first started building projects, it defaulted to phonegap 2.9, which did not have the updated iOS7 UI. It took me countless hours to figure out that I just had to update to phonegap 3.1 to fix the status bar issue.

You’ll see all kinds of javascript hacks for the status bar issue around the web, don’t bother with those. Just update your version of phonegap, and use the status bar plugin. I can’t tell you how many hours I wasted on this.

3. Building locally vs using Phonegap Build

There are 2 ways to build (compile) a Phonegap app, locally or through Phonegap build.

Phonegap build is great if you don’t have a super custom project, it allows you to just upload a .zip of web files (javascript, html, css, etc) which they compile into an app for you. We exclusively use Phonegap Build for AppPresser.

A local build and a phonegap remote build require different config.xml setups and project structures.

For example, using a plugin for a local build, you have to install it via the command line, and it adds something like this to your config file:

<feature name="StatusBar">
  <param name="ios-package" value="CDVStatusBar" onload="true" />

To use that same plugin with phonegap build, you do not need to install it via command line, you also don’t need to add any files to your project. You simply add this line to your config file:

<gap:plugin name="com.phonegap.plugin.statusbar" />

Phonegap build does the rest.

Project structure


When building locally, you have a master folder that contains a www folder, plugins, etc. After you build for your platforms, you have a platforms folder with ios and android and all the files and folders for those projects. Basically one big project.

When using phonegap build, you don’t need all that stuff, just the www folder. You can just compress the www folder into a .zip file and upload that to, or use the command line to push it up. Phonegap build takes care of everything else.

Hint: If you build your project locally using the CLI, the only files you should modify are in the main www folder. When you run ‘cordova build’ or ‘phonegap build’ it copies all your changes into the ios and android folders. Don’t go into the platforms folder and edit those config files manually.

4. Apple developer certificates

Apple has made this part of the process a huge pain (thanks Apple!)

Here’s a great tutorial for getting what you need for phonegap build:

I also did a screencast on the whole process of building the app to submitting it, you can find that on the AppPresser youtube channel here.

Things to note:

  • Make sure the app ID in your config.xml file is the same one in your provisioning profile. If you use a wildcard app ID this is not as much of a problem.
  • Devices that are not attached to your provisioning profile will not be able to test your app.
  • This is random, but changing the app ID in your config.xml file DOES NOT change the app ID for your phonegap build project. You have to create a new project via the command line. I noticed this because it was overwriting my apps even though I changed the app ID in config.xml.

5. Push notifications and APNS certificates

Oh man, this one took us weeks to figure out!

First, go through these great tutorials:

I’m not going to rehash generating all of your certificates, but here’s where we got stuck…

Apple Push Notifications CertificateWhen you create an app ID with push notifications enabled, you create an SSL certificate. I naturally thought that’s the certificate you’d use to generate your .p12 file. But my app wouldn’t build, it was giving me an error. I was wrong!

To build your app, you don’t need the cert with push notifications on it, you just use your normal developer cert and generate your .p12 file from that. You use the provisioning profile with your APNS app ID along with your normal developer cert.

Also, I use everything in Distribution/Ad Hoc mode, not developer mode.

That’s all I’ve got for now, happy building!

7 thoughts on “Beginner Stumbling Blocks in Phonegap & Cordova

  1. The status bar plugin looks good! The problem that I’m having now is when my app loads the screen fades to white (it’s pretty quick though and looks like a flash), and then my app is shown – having lots of problems getting it to work. BTW AppPresser is a cool idea 🙂

    • Hi, the white flash might be because you aren’t leaving the splash screen up long enough. You can configure that in your config.xml preferences, see if that works 🙂

  2. I had a problem with compiling locally vs Phonegap Build. We are using LocalStorage with Lawnchair.js. When we build the application through Phonegap Build the LocalStorage works fine. When we build the app locally however it does not work, the localStorage breaks. It seems there is an issue with it updating keys between pages. We have no idea why it works for Phonegap Build and not when compiled locally. Any ideas?

    • Hi Bob, I don’t have any experience with this specific issue, sorry. You could check that your Phonegap plugins are installed correctly, it is a different process for local vs. PG build.

  3. You sir are completely right about upgrading to PG 3.1. Spent a while day trying to fix the statusbar issue while on PG 2.9 and then just upgraded to 3.1… (sigh). Thanks!

  4. Hi Bob,
    wish I’d come across your post sooner – could write my own at this point having gone through almost exactly the same pain points as you have. We’re using Azure Mobile Web Services (yes, we’re sadists!) just to, you know, add some extra abstraction.
    Agreed Phonegap is good but the initial slopes are treacherous and the docs should really be overhauled and dead links pruned.
    Again, thanks for the post,

  5. Hello,

    After spending around three days trying to figure out why my app wasn’t working, your post saying to upload only the www folder made me figure it out.

    Thank you so fucking much, you’re a fucking legend, I can now finish my thesis app.

Leave a Reply

Your email address will not be published. Required fields are marked *