I already have the major software installed on my Windows machine from my last Eclipse build, detailed in http://iphonedevlog.wordpress.com/2012/11/20/building-a-phonegap-android-app-on-windows-cordova-2-2-0-with-eclipse/. If this is your first time with Eclipse and PhoneGap, follow the link above and pay careful attention to the following setup sections:
Install Eclipse Juno IDE
Install Java JDK
Install the Android SDK
Android SDK Manager
Set up your PATH environment variables
The steps following will take up where these left off.
For system requirements to build Android apps, see: http://developer.android.com/sdk/index.html
For best practices for Google Play apps, see:
For a FAQ and content guidelines on submitting apps to Amazon, see:
Download Cordova 2.7.0
1. From http://www.phonegap.com, I downloaded version 2.7.0.
2. It was downloaded to my Downloads folder as: phonegap-2.7.0 I extracted it to
3. In the phonegap.com download page, I clicked on Getting Started Guides, then chose Getting Started with Android. This tutorial will follow the Apache Cordova Getting started Guide steps outlined in: http://docs.phonegap.com/en/2.7.0/guide_getting-started_android_index.md.html#Getting%20Started%20with%20Android
Set Up Your Project’s Cordova Files
Cordova will create the core files for your project via the console.
1. Open a command prompt: Go to Start, Run. . ., and type cmd.exe to open the command prompt console window.
2. Get the address to the \bin directory within the Android subfolder of the Cordova distribution. In my case it was:
If you look in the /bin folder, you’ll see the “create” file there that will execute the following command.
3. Decide on:
a. the path where your project will reside (like D:\Android\RivalEssentials)
b. the package name (like com.stevehusting.RivalEssentials)
c. the project name (RivalEssentials; no dashes or spaces allowed).
Put all four pieces of information together:
create <Android_bin_path_to_create_file> <project_folder_path> <package_name> <project_name>
(Do not include the < or >, and put a space between each component.)
4. My phonegap files resided on my D: drive, so at the command prompt I entered D: to change to that drive. (If you were in My Computer, you could drag the D: icon to the command prompt screen, then hit Backspace to remove the slash, then hit Enter to change to that directory.)
5. Once the command prompt started with D:\>, I typed the change directory command (cd) as follows, then hit Enter (note that I used the normal forward slashes and not back slashes):
(If you get the message, “The system cannot find the path specified,” then you have a typo in your command.)
6. Then I followed the steps to create the project with:
create D:\Android\RivalEssentials com.stevehusting.RivalEssentials RivalEssentials
(You can type these long strings of text in a text editor and copy/paste them into the command prompt window. To paste, click on the icon at upper left of the command prompt window, then navigate: Edit > Paste.)
7. Shut down the command prompt window by clicking on the icon in the upper right.
8. When the command prompt finished, I found all the files set in the location I indicated.
Set Up Project in Eclipse
1. Start up Eclipse. You’ll see the progress bar in the lower right.
If you are impatient, skip all the notices saying that updates are available, and go right to step 2, then go back and do them at a more convenient time (by restarting Eclipse). Nevertheless, you are encouraged to keep the software up to date.
If you get a notice regarding updates available in the lower right of the screen, click on the notice’s box and a dialog will open with software checked for download. Hit Next then Next, then on the I Accept radio button, then on Finish. Watch awhile to click on any permission notices that require you to affirm. You’ll need to restart Eclipse to finish installation.
Upon restart, you may get a notice about updating the ADT. Click on Open SDK Manager in that popup. The Android SDK Manager will open and you’ll see in the Status column the updates available. Click on the Install X packages… button, Accept the license, and Install. Don’t let the progress bar fool you: it is per install, NOT the total install time. This can take a while!
2. Back in Eclipse: File > New > Project (if “Not Applicable” is seen instead of a list of items, check the upper right of the Eclipse screen and make sure Java is selected, not Java EE).
3. Click on the + button to the left of Android to show its contents if it’s not open already.
4. Choose “Android Project from Existing Code,” and hit Next. The “existing code” will be the files created by PhoneGap, NOT your own HTML code.
5. Click on the Browser button and select the folder you used for <project_folder_path>. Mine was D:\Android\RivalEssentials.
6. If you have a workspace already, check Copy projects into workspace; otherwise, leave it unchecked. Mine was left unchecked.
7. Hit Finish and wait.
8. Click on the + to the left of the project name in Eclipse to show the files.
9. Right-click on AndroidManifest.xml and select Open With > Text Editor. Remove or comment out all the permissions your app doesn’t need. To learn more about permissions, see:
Some explanatory notes on this page:
This is the first version of your app. Subsequent versions are always sequentially numbered. Not shown to the public.
This is the actual version shown to users.
The <uses-sdk> section: For the minSdkVersion, put the lowest version your app is designed to use, such as 8 for Android 2.2. For the targetSdkVersion, put the number for the highest device you’ve tested it against (my current “Nexus 7″ device would be “15.” If you see a maxSdkVersion, it’s recommended that you leave it blank (according to http://developer.android.com/guide/topics/manifest/uses-sdk-element.html).
If you started clicking around in Eclipse like I did, and you are unfamiliar with the IDE (integrated development environment with its myriad of views), you may lose the Project Explorer view. Just go to Window > Show View > Project Explorer to bring it back. You may have to first go to Window > Show Perspective > Other… and click on the line with (default). Mine was “Java EE (default).” Learn more: http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.user%2Fconcepts%2Fcprbview.htm
Test in the Emulator
Let’s test PhoneGap’s sample page in the emulator.
1. Click on Project > Clean…, make sure your project name is selected, then OK. Right-click on the project name, then on Validate. The progress bar appears in lower right, and a popup should announce no errors.
2. Right-click on the project name again, then Run As > Android Application. The emulator should start (consuming 669MB, according to the Windows Task Manager in my case). It usually takes a long wait before your application appears on the screen. You can look at the Console view at the bottom of the Eclipse window to see the progress of the emulator. When the messages stop, switch to the LogCat view to see the progress as it loads in the emulator.
After I did a recent update, the emulator would no longer run. The console complained that there was no apk file. When I attempted to create an unsigned apk directly (steps are further down this page), I got the error: “No Build Tools installed in the SDK.” Evidently, the recent update did not complete.
I shut down Eclipse, went to my \android-sdks SDK folder, and double-clicked on the “SDK Manager.exe” file. I noticed the icon for the program at the bottom of the screen and opened it. The Android SDK Manager opened, showing me that there were 4 packages to install. After that install, I started Eclipse again and the emulator launched successfully. The problem was that Eclipse was locking a file, preventing a file from downloading and making changes; shutting down Eclipse and running the Manager again solved the problem.
3. If all goes well, the Android device screen will appear with an icon in the middle. Drag the icon to one side to unlock, then PhoneGap sample page should start up on the emulator screen. The emulator should display the one-page starting screen that Cordova PhoneGap created. Nothing more.
If it does not display, check the Console for reasons why it failed to launch. If you don’t understand the output, copy and paste one of the final lines into a search engine for solutions. That’s how I’ve resolved a majority of problems.
Add Your Project’s Assets
1. In Eclipse, open assets > www and look at the files there. PhoneGap provided these files to build a sample output for the emulator so that you’ll know it’s working. You can remove all those files, except cordova-2.7.0.js, and replace them with yours; let’s follow those steps next. Right-click on each folder in www and select Delete. Also delete index.html, main.js, master.css, and spec.html.
2. Make sure your index.html file references cordova-2.7.0.js before other JS scripts:
4. Do a Project > Clean.
5. Right-click on the project name and select Validate. If it mentions that it found a few errors, then look at the folder structure. You’ll see icons over the upper left corners. Open those and open the files with those icons. When you open one of the files, you’ll see a yellow marker (like a thick minus sign) to the right. Click on that marker and it’ll jump to the error and tell you the problem. In this way, I fixed 9 errors with my HTML files that I failed to find earlier. Shame on me!
You can also find the list of errors by: Window > Show View > Other… > General > Problems. In addition to Problems, click on Error Log. Learn more: http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.user%2Fconcepts%2Fcprbview.htm
If you have external links, you’ll want to change them to the following format. Without the InAppBrowser, your external links will open in a browser outside the app. You would then hit the back button on your Android device. But with the InAppBrowser, one needs only tap on a Done button at bottom to return right to the app.
<a href="#" onclick="window.open('http://iphonedevlog.wordpress.com', '_blank', 'location=no');">without location bar</a> <a href="#" onclick="window.open('http://iphonedevlog.wordpress.com', '_blank');">with location bar</a>
Use location=no to refrain from showing the location bar with the external page’s URL. It is shown by default, so you can leave off location=no or location=yes and the path URL will be shown above the Done button at bottom.
Home Screen Icon Name
1. Specify the name you want to appear under the icon on the device’s home screen. Open res/values/strings.xml with the Text Editor and edit as shown below. Keep the text short, like 20 characters or fewer. Unlike the iPhone, long titles will wrap, which is nice.
<string name=”app_name”>App Title Here With Spaces</string>
2. Save the page.
Debugging your Project
1. The validator in Eclipse validates your HTML and CSS, giving filename, nature of problem, and line number of its location in the file, for all the HTML files in the app. In Eclipse, select the project name in the Package Explorer and refresh the project (File > Refresh). Watch the progress bar in the lower right. Right-click on your project name again, and select Validate. Again, watch the progress bar in the lower right. An alert will give you a quantity of problems found. To read a listing of those problems, Window > Show View > Other… > General > Problems. In addition to Problems, click on Error Log. Learn more: http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.user%2Fconcepts%2Fcprbview.htm
(If you don’t see the validation option, you’ll need to download the WTP (Eclipse Web Tools Platform). The instructions on this page will tell you how to get them: http://wiki.eclipse.org/WTP_FAQ#How_do_I_install_WTP.3F Pay special attention to the paragraph, “How do I install WTP?”)
2. Debug by using the app in a virtual device onscreen with an emulator. Back in the Project Explorer view, right-click on your project name, and select Debug As > Android Application. You’ll see the Console screen at the bottom of the Eclipse environment record the activity prior to appearing in the emulator.
When the emulator starts in a separate window, though, the Console will stop recording; at that point, to the right, click on the LogCat tab to see it start displaying the emulator activity. (So when you post a problem for other developers to help, this is where you’ll copy/paste from: the “LogCat” tab.)
If you have a working emulator installed, then it will launch and you’ll see the home screen. (Mine took more than a minute before it displayed, so you may need to be patient. Some have had to wait 5-10 minutes!) Drag the emulator window out of the way so you can see all the entries in LogCat. In the emulator, drag the “lock” to the side and the app will launch after a while, if all is well. Again, be patient.
“Failed to install app_name.apk on device ‘emulator-5554!'”
“Unfortunately, launcher has stopped.”
Here are some of the ways I’ve tried to solve problems with the app not appearing in the emulator:
a. Pay attention to the logcat text, and see if any of it points to problems you recognize.
b. Go to Eclipse’s Window > Preferences, then Android > Launch, add “-partition-size 1024? on the Default emulator options field, then click Apply, and use your emulator as usual.
c. Create and use a new AVD.
d. Shut down Eclipse, then shut down and restart adb (Android Debug Bridge) with these steps:
1. Open command prompt (Start > Run > cmd).
2. Type adb kill-server and then hit Enter.
3. Type adb devices and then hit Enter.
4. Exit command prompt and start up Eclipse again, Project > Clean, and test.
e. Open AndroidManifest.xml in a text editor and change the “17” to “16” or “15” at:
f. Unplug device to prevent confusion, and test again.
g. Post the logcat to a forum and give details about the app. For instance, one poster pointed out that I neglected to include a needed permission.
h. Run the debugging steps above if you haven’t already, and fix the errors.
i. If you are making new apks again and again to test in the same device, remember to select the app name in Settings on the device, then select to Clear Cache, Clear Data, Force Stop, and Uninstall. Then install the newest version of the app for testing.
Even after all these steps and more, it may fail to load in the emulator, but work fine when testing in the device.
3. Right-click on the project name, choose Android Tools > Run Lint. This will show you, in the Lint Warnings view, problems in the Android system. I wrote an article where I cover common and not-so-common Lint problems I’ve encountered when using PhoneGap: http://iphonedevlog.wordpress.com/2013/06/26/fixing-android-lint-warnings-found-when-building-a-phonegap-project/
4. A fourth and essential way to debug is to test the app on an actual device. Follow the next steps to do so.
Sign the App
Apps in the app store must be “signed” with keys. Here are the steps to accomplish this. These steps create the “apk” file that is uploaded to the app store for purchasers’ download.
1. Right-click on the project name in Eclipse, then click on Android Tools > Export Signed Application Package.
2. “Project Checks” dialog:
This screen will tell you if you have serious errors that need to be fixed before you can go further. If you have problems, copy the error into Google and search for resolutions if you are unfamiliar with these problems.
3. “Key selection” selection dialog:
Create the key using the app name, no spaces, ending in “.keystore”. WARNING: if this is an upgrade, use the same name as the earlier version! Browse to the location to save the keystore and in the same box give the name of the keystore. Back in the Keystore selection dialog, add the password twice and hit Next.
4. Key ["Private Key"] Creation dialog:
Alias: same as app_name, no spaces.
password of keystore.
validity: 50 [meaning, good for 50 years].
First and Last name:
Organizational unit: [division of company, or leave blank]
Organization: [use no punctuation - only letters and numbers, or you'll get an "keytool error" notice later.]
State: [2-letter abbr. is fine.]
Country: 01. [which is U.S.]
Destination APK file: This is the hard disk location where Eclipse will save the program’s .apk file that you will later upload to Google Play or other app store. Browse, then click Finish when done.
Write down the above Key Creation information, passwords, and APK destination and keep it safe for later retrieval and app updates. If it is lost, you can’t upgrade the app any further. To release the app after this file has been lost, you’ll have to create a whole new app and release it separately, making your customers ineligible for any updates.
Perhaps make a separate private key for each app, especially if you expect to sell the rights to an app to someone else. Save the keystore and apk files to a separate location for safety.
If you get: “keytool error: java.io.IOException: Incorrect AVA format,” then an invalid character was used in one of the previous screens. Solution: remove any punctuation so only letters, spaces, and numbers remain.
Test the apk File in Device
1. Check with your device as to how to install the apk file. In my defunct eLocity tablet, it was s a simple matter of copying the file to the SD card, navigating to it from Settings, and selecting and choosing to install it. My Google/Asus Nexus 7 does not include an SD card. So I downloaded DropBox.com software to the computer and the DropBox app to the Nexus. Once I signed up for a Dropbox account, I copied the apk file to the computer’s DropBox, then it was accessible on the Nexus. Then I tapped on the file and it asked if I wanted to install. Simple.
2. Once installed, you’d click on Open, and you should see it on the home screen. If not, tap the middle button at the bottom of the screen to see all the installed apps and look for your icon. Check your app title underneath to make sure it is not truncated.
3. Tap the icon and check out your work.
4. Make changes to the files as necessary and redo.
Prepare Promotional Artwork
You’ll want to include screen captures for upload to the app store of your choice. Choose screens carefully to present your app in its best light. What if your device doesn’t take screen captures? My now-defunct eLocity tablet and Google Nexus 7 did not have this native functionality, nor did I find apps made for those devices that performed this function. All is not lost, though; here is what I’ve done as a hobbyist. If you’re a pro, you really should invest in several physical devices.
A. First method
1. Just double-click the app’s index.html file in Windows Explorer to open it in Google Chrome, then narrow the browser window to approximate the device’s screen proportion.
2. Use your favorite screen grab utility (or tap on your keyboard’s PrtScn key) to get the picture.
3. Use GIMP (download free at gimp.org) or other photo-retouching program to crop and resize appropriately. Screen sizes follow.
B. Second Method
1. Plug in your device, set it for debugging, and in Eclipse, go to Window > Open Perspective > DDMS. To the left of Devices you’ll see an icon of a camera. Click on that and it’ll take a screenshot. Click on Save to save to file.
2. Use a photo-retouching program to crop and resize appropriately.
See my Google Play App Publisher’s Template for the assets you’ll need to have on hand before you upload: http://iphonedevlog.wordpress.com/google-play-app-publishers-template-22013/. It covers the screenshots and other graphics needed. If you are submitting to Amazon, you may need different assets or different sizes.
Add icons of these sizes into these folders. According to http://developer.android.com/design/style/iconography.html, Google wants the icons to be a distinct silhouette, and not to fill the entire field. Delete the current icons, then just drag yours from Windows Explorer right into the folder in Eclipse and select checkbox to copy:
res/drawable: 96×96 (icon.png)
res/drawable-hdpi: 72×72 (ic_launcher.png)
res/drawable-ldpi: 36×36 (ic_launcher.png)
res/drawable-mdpi: 48×48 (ic_launcher.png)
res/drawable-xdpi: 96×96 (ic_launcher.png)
Preparing for Google Play Launch
When you are ready for release, open Eclipse, and in AndroidManifest.xml, turn off debugging. Remove the text:
You’ll want to move the closing “>” symbol at the end of that line to the previous line.
Remove or comment out any other debugging in your HTML files, such as alert messages or log output. Do a Project > Clean.
Prepare Copy for Google Play Store
1. Fill out the information on this template for the app assets for the Google Play store so you’ll have the information at hand when you go to the Developer Console: http://iphonedevlog.wordpress.com/google-play-app-publishers-template-22013/ Of course, if you are releasing to Amazon or another store, the asset requirements may vary.
2. Back up your keystore off your development computer, if you don’t have regular backups.
Ready For Public Release
Congratulations! You are now ready to show off your baby to the world!
To register as a Google Play developer and set up your publisher account, visit the Google Play publisher site: https://play.google.com/apps/publish/Home
My Helpful Links page gives a small listing of other sites where you can list your apps. Visit http://iphonedevlog.wordpress.com/phonegapcordova-crib-sheet/ and look under “App Stores.”