Phonegap app for Android without Phonegap Build

Question

I've run into a lot of problems upgrading my PhoneGap 1.x app to Phonegap 3.0, at least for Android (I haven't even started on upgrade for the iOS version yet). I figured it might help a lot of folks if I combined all that stuff in a Q&A.

So the question is: what do you need to look out for when upgrading an existing app to Phonegap 3.0?

This is sort of a top-level manual that dives into a few details. I'm describing the process for Mac users, but although commands and tools may differ, the principles are the same for Windows.

Answer 1

Advance warnings...

First off, don't bother with the official docs upgrade manual. That only helps you upgrade from 1.0 to 1.1, then from 1.1 to 1.2, then from 1.2 to 1.3, etc. If you want to jump across a number of versions, you don't know if you're doing the right thing. So when you upgrade, create a new project from scratch.

Also, jumping way ahead to make sure you don't get stuck far into the process: if your pre-3.0 Phonegap app uses custom plugins, consider very carefully if you want to upgrade at all. Scroll ahead to the "Watch out with custom plugins" to see why.

Step by step

Having said that, this is the step by step process, separated by lines.

---

1. Command-line

Phonegap 3.0 is all about command-line tools. It looks a lot scarier than it really is. You just need to install a few tools you'll be using there (mostly by typing a command in the command line).

The most important general commands to know are:

//For Mac and Windows (on Windows, replace slashes by backslashes)
cd mySubfolder //Go to the subfolder "mySubfolder"
cd /MyTopLevelFolder/SomeOtherSubfolder //Go to any folder using the entire address

//Show a list of files and subfolders where you currently are
dir //On Windows
ls //On Mac

---

2. Be in the right place

The most crucial aspect of the command-line tool is that you always have to pay attention in which directory you currently are. Telling Phonegap to build and deploy your app will only work if you are in the main folder for that app.

Ususally, to do things with your Phonegap project, you need to navigate to the project's home directory using:

cd /Users/yourself/thePathToYourWorkspace/YourCurrentPhonegapProject //On Mac
cd D:\ThePathToYourWorkspace/YourCurrentPhonegapProject //On Windows

---

3. The path to enlightenment

PS: To make sure the tools you install run correctly, you sometimes need to tell the computer that it should look in a number of extra directories if it can't find a file in the current directory. You edit something called the path variable. Look that up elsewhere, it's not too hard but it's different for Windows and Mac.

---

4. Get the toolboxes' toolbox first

To get started, the basic docs are okay. You download and install node.js, which is a tool that the other tools will be using, then use it to install the phonegap/cordova command-line tool.

//Like so, for Mac
$ sudo npm install -g phonegap
//Note: the "sudo" bit is needed to install a number of necessary files in folders that Apple protects from direct user editing

From now on, you can use the 'phonegap' command to perform a number of tasks for your project.

---

5. Open a workspace

The first thing you need to do is create a workspace, which is a generic word for a master folder for all your projects (you can do this using Windows Explorer, Finder, or any other user-friendly too).

For Windows in particular, try to make sure that you can type the entire path to that folder without using spaces. So never put your workspace in a place like "My documents", especially since that's a subdirectory of C:\Documents and settings\John Doe\". Rather, try something like "D:\Workspace\".

If you're already using Dropbox for other purposes, and it's not too much of a hassle to change the location of the Dropbox folder, consider using it for automatic backup of your workspace. Just put the Dropbox folder in D:\ or some other disk's root directory. Then add Workspace as a direct subfolder of Dropbox.

Using Dropbox can very occasionally hinder you during development if it happens to be syncing files in your project. But the upshot is that you have automatic backup of many versions of your files: all versions in the current day, some versions for yesterday, one version for each day previously.

---

6. Create your project

Next, you go to your workspace directory in the command-line console using the cd command. When there, you tell Phonegap to put in place the basic structure of an empty app using the command

$ phonegap create hello com.yourCompanyName.yourAppName HelloWorld

This will create a folder HelloWorld and fill it with a number of subdirectories with files that are the backbone of your app.

---

7. Drape it on the scaffolding

Then you go about filling this structure. Mostly, your app will be a bunch of HTML,CSS and Javascript files. Those go in the main www folder. That folder also contains the config.xml file which contains a lot of settings for your app, like what icon to use, what name to show, whether or not to show the Android status bar, what domains to whitelist, etc.

Phonegap combines these files in the /www directory so you have all of your "editable" stuff together. If you don't your app to do anything fancy like with plugins, then you're good to go.

---

8. Whitelist the right way

If any part of your app actually accesses the internet, even if only for something like Google Analytics, you have to tell Phonegap to "whitelist" the appropriate domain names. As stated above, this is done using tags in MyProject\www\config.xml.

This is a tricky business, because Phonegap has trouble dealing with the differences between platforms on this issue.

For Android (using Google Analytics as an example), add your domains to the whitelist like so:

The reason you add this domain twice is that many online services begin with a simple unverified http:// protocol, but some of their functions may subsequently get or send code from/to a secure https:// address on the same domain.

The asterisk is important because you want to be able to download scripts and other stuff from**www.**google-analytics.com as well as from the main google-analytics.com or any subdomain.

---

9. Plug in the extras

If your app requires special functions (the stuff that Android would ask users permission for, like access your phone or contact book or camera or accelerometer), then you need to install plugins in your app project.

Look here in the docs to see how to do it.

Also, make sure that you add a line to config.xml that tells Phonegap not to ask for any unnecessary permissions:

    <preference name="permissions" value="none" />

The docs say that this means you're only asking for one permission (network access), but that's not quite true. Example: if you have installed the camera plugin, the app will ask the user for camera access permission, no matter if you added the above value=none preference tag. Same for all other functionalities/permissions.

---

10. Watch out with custom plugins

Also, and this seems to be a bug in Phonegap, no matter what your plugins and your permissions setting, the app will always try to get three other permissions: RECORD_VIDEO, ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION.

Phonegap just puts those in the Android manifest as if you specified that somewhere. When you build your app for actual release into the app store, you will need to fix this. How: you edit your AndroidManifest.xml right after your last build, but before signing and releasing the package.

That way you get these nasty permissions out. But you have to repeat this every time you upload a new app version to the app store!

---

Besides the standard plugins, Phonegap has always had a host of third-party custom plugins. The way those are installed in Phonegap 3.0 is totally different from before. The lazy specialists who already know the drill say that "it's just the same as installing the core plugins", but nobody bothers to give an example anywhere.

If you know how to translate a pre-3.0 plugin installation process to a 3.0+ process, please add a comment, and I'll copy-paste it in this manual.

---

When you are ready to start testing your app, connect your device (or install the emulator) first. These commands will be most useful, and not all are nicely documented...

$ phonegap build android //This builds a test app, but doesn't run it
$ phonegap run android //This builds the test app AND runs it on device/emulator

---

Then when the app does exactly what you want it to, and you're ready to put it in the app store, you will need to take a few last steps to create a store-ready app package (.apk).

You need to have 'ant' installed. In my case, installing all the other stuff has meant that ant was automatically installed too, and this is likely to be the case for you to. Ant is a tool to build packages (my dumb deduction, not a verified fact).

---

11. Go where the ant goes

Up till now, you have been shooting commands in the command-line console out of your project's home directory. Now, however, you will want to work with the Android apk that you created with those commands, and 'ant' doesn't know as 'phonegap' does where to find those.

So head on over to the subsubdirectory...

cd platforms/android //This is a subdir of blabla/workspaces/myproject.

This is the location of your Android app's java native "wrapper" for the HTML/CSS/Js stuff you made.

---

12. Prepare for release

If you need to make last-ditch modifications to the app (like removing strange permission requests from AndroidManifest.xml), do so now. Be sure to edit the AndroidManifest.xml in the folder /platforms/android, not the one in /platforms/android/bin.

Some modifications you maiy have to make because of bugs in Phonegap:

• remove unwanted permission requests
• set the version code manually (Phonegap sets it to 1 even if you specified differently in config.xml)

---

13. Release the ants

If you are truly ready to put your stuff in the app store, just fire off this command. Be ready to get errors: you dealing with those one step at a time is easier than me putting the whole if-then process in this manual.

ant release

When ant is done, you should find a file called YourAppName-release.apk in the folder /Platforms/Android/bin. This is the file you can upload to Google Play.

---

14. Likely problems with "ant release"...

A. You app needs a private key

The key is stored in a private keystore (file). If this is not your first app version, get that stuff from wherever you stored it and put it in a simple, easy-to-type location like D:\Developer\Keystores. If this is your first app version, create a key.

B. Ant cannot find your key

Ant doesn't know where to look for this keystore, so you need to edit a file in the platforms/Android directory to point it in the right direction. The file is called ant.properties. Add these properties using a plain text editor:

//Point it to the right directory:
key.store=/Users/Me/Dropbox/Developer/Keystores/keystoreForMyFirstApp //For Mac
key.store = D:\Dropbox\Developer\Keystores\keystoreForMyFirstApp //For Windows

//This describes the name of your signing key, as stored in the keystore
key.alias=FirstKey

---

You may now be ready to put an apk file in Google Play or some other Android store. I haven't been exhaustive, but these steps should get you a long way. Comments are welcome!