Building a PhoneGap Android App in Windows: Cordova 2.3.0 with Eclipse 4.2.1


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 ADT
Install the Android SDK
Android SDK Manager
Set up your PATH environment variables

For system requirements to build Android apps, see: http://developer.android.com/sdk/index.html

For best practices for Google Play apps, see:
http://support.google.com/googleplay/android-developer/bin/topic.py?hl=en&topic=2364761&parent=2365624&ctx=topic

For a FAQ and content guidelines on submitting apps to Amazon, see:
https://developer.amazon.com/help/faq.html

Download Cordova 2.3.0

1. From http://www.phonegap.com, I downloaded version 2.3.0. A list of its upgrade changes can be found here: http://phonegap.com/blog/2013/01/07/phonegap-230/.
2. It was downloaded to my Downloads folder as: phonegap-2.3.0 I extracted it to D:/PhoneGap/phonegap-2.3.0
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.3.0/guide_getting-started_android_index.md.html#Getting%20Started%20with%20Android in conjunction with my previous article here: http://iphonedevlog.wordpress.com/2012/11/20/building-a-phonegap-android-app-on-windows-cordova-2-2-0-with-eclipse/ We will follow those steps in the next section.

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:
D:\PhoneGap\phonegap-2.3.0-0\lib\android\bin
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\newProject)
b. the package name (like com.stevehusting.newProject)
c. the project name (newProject; no dashes 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 >.)
My phonegap files resided on my D: drive, so I entered D: to change to that drive.
4. Once the command prompt started with D:\>, I typed the change directory command (cd), then the entire path to the “create” file (from step 2):

cd D:\PhoneGap\phonegap-2.3.0\lib\android\bin

5. Then I followed the steps to create the project with:

create D:\Android\newProject com.stevehusting.newProject newProject

7. 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.
2. File > New > Project
3. Click on the + button to the left of Android to show its folder if its not open already.
4. Choose Android Project from Existing Code, and hit Next.
5. Click on the Browser button and select the folder you used for <project_folder_path>. Mine was D:\Android\newProject
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.

————————–

Warning Encountered

The project has a warning after step 7 above: “The import android.app.Activity is never used.”

a. To resolve, navigate in the Package Explorer at left through src > com.<project info> > newProject.java, right-click on the latter, and choose Open with > Text Editor.
b. Change the following to comment out the line:

import android.app.Activity;

to . . .

/* import android.app.Activity; */

c. Project > Clean should make the warning go away.

—————————-

9. In Eclipse, 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:
http://developer.android.com/guide/topics/manifest/uses-feature-element.html
http://developer.android.com/guide/topics/manifest/uses-permission-element.html
http://developer.android.com/reference/android/Manifest.permission.html

Some explanatory notes on this page:

android:versionCode=”1″>
This is the first version of your app. Subsequent versions are always sequentially numbered. Not shown to the public.

android:versionName=”1.0″>
This is the actual version shown to users.

Below this is 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 “Jelly Bean” 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.

Add Your Project’s Assets

1. Open the folder containing your already-created www “assets” in Windows Explorer (your project’s HTML, CSS, Javascript, videos, images, etc., files). Copy all those files to the Android project’s /assets/www folder in Windows Explorer.
2. Make sure you reference the cordova-2.3.0.js file in index.html. Also, you can safely delete the following files that PG generated to display its test screen:

js/index.js
spec.html
www/spec folder

You can also delete the assets/www/res folder in Windows Explorer (not in Eclipse). It contains all the icons and artwork depicting the PhoneGap logo.

InAppBrowser

If you have external links, you’ll want to change them to the following format. Without the InAppBrowser (IAB), your external links will open in a browser and there would be no way to get back to the app but to shut down the browser and tap on the app icon on the home screen. With the IAB, 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&#8217;, ‘_blank’, ‘location=no’);”>without location bar</a>

<a href=”#” onclick=”window.open(‘http://iphonedevlog.wordpress.com&#8217;, ‘_blank’);”>with location bar</a>

Look at my separate article for the six steps you need to incorporate the IAB: http://iphonedevlog.wordpress.com/2013/06/27/implementing-inappbrowser-into-a-cordova-phonegap-project/

Splash Screen

You may want to add a splash screen to your app. Here are the three steps in a separate article: http://iphonedevlog.wordpress.com/2013/07/02/creating-and-installing-a-splash-screen-for-android-using-eclipse-and-phonegap/

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. Make sure to check this later in your device or emulator.

<string name=”app_name”>App Title Here With Spaces</string>

2. Save the page.

Debugging your Project in 4 Phases

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, click on the Problems tab. (You can ignore the “No grammar constraints” warnings: http://argillander.wordpress.com/2011/06/14/no-grammar-constraints-dtd-or-xml-schema-detected-for-the-document/). Resolve these HTML errors before proceeding.

2. To validate the Android files, look at the row of icons under Eclipse’s top menu bar and find the Android Lint’s “checkbox” icon. Click on that. The tab Lint Warnings will show you all the problems with the Android files (which are not in your HTML project files). You may need to post the errors in Google Search to find solutions.

3. 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, the Console will stop recording (at “Waiting for HOME”), then, a few tabs 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 it 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.

When my app did not appear, I clicked on the Console tab and found the reason displayed in red on three separate lines: “Installation error: INSTALL_FAILED_INSUFFICIENT_STORAGE. Please check logcat output for more details. Launch canceled!” Check your Console for reasons and Google for solutions.

———————-

“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. Window > Android Virtual Device Manager, Select device, Edit…: Internal Storage of 500, SD Card of size 1024, no camera. Click on OK to return, select device AVD, Start… then scroll down and select Wipe User Data, then Launch.

d. Create and use a new AVD.

e. 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. Start up Eclipse again, Project > Clean, and test.

f. Open AndroidManifest.xml in a text editor and change the “17″ to “16″ or “15″:
android:targetSdkVersion=”16″/>

g. Unplug device to prevent confusion, and test again.

h. 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.

i. Run the debugging steps above if you haven’t already, and fix the errors.

j. 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.

———————-

4. The fourth step to debug is to test the app on an actual device. Follow the next steps to do so.

Sign the App for the App Store

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.
3. Key alias 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!] (A later version of Eclipse has the dialog named Keystore selection. 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.]
City:
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 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 and numbers remain.

Test the apk File in Device

1. Check with your device as to how to install the apk file. In my eLocity tablet, it’s a simple matter of copying it to the SD card, navigating to it from Settings, and selecting and choosing to install it. The Google/Asus Nexus 7 does not include an SD card. I downloaded DropBox.com software to the computer and the DropBox app to the Nexus. Once I signed up for an 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 should see it on the home screen. If not, tap the middle button to see all the installed apps and look for your icon. Check the 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.

For another source for debugging in the device, follow these simple steps in a Webkit browser like Google Chrome:
http://debug.phonegap.com/

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

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.

Screen sizes needed:
1. Need at least two images of one of these sizes: 320 x 480, 480 x 800, 480 x 854, 1280 x 720, 1280 x 800
24 bit PNG or JPEG (no alpha); full bleed, no border in art. (I chose to use 1280 x 720 and use screen grabs from my 1280 x 800 resolution monitor to populate; showing single wide tablet shots – slightly stretched, and side-by-side small screen shots. Unfortunately, Apple’s different screenshot proportions means having to grab fresh screens for that platform.)
2. Prepare a High Resolution Application Icon for Google Play: 512 x 512 pixel JPG image.
3. Promo Graphic: 180w x 120h PNG or JPG. Also write promo text, 80 chars.
4. Feature Graphic: 1024 x 500 PNG or JPG.
5. Prepare a promo video.
6. If preparing for iPhone: 1024 x 1024px JPG image, and screen grabs.
7. If preparing for Amazon App Store release: 1024 x 500px PNG or JPG promotional image, and screen grabs.
8. If you will create an an ebook version through smashwords.com (this is where Apple gets many of its iBooks from) create a 1400 x 2100px JPG image for the book cover.

Add icons of these sizes into these folders. 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 line:

android:debuggable=”true”>

Remove or comment out any other debugging in your HTML files, such as alert messages.

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/

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.”

About these ads

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s