Cordova 2.0 Android App Creation in Mountain Lion with Eclipse: from Install to Google Play

I kept meticulous notes as I downloaded Eclipse and all the other software I needed to create an Android app for Google Play as though my readers were absolute newbies on the Mac (I’ve been there and I haven’t forgotten) using PhoneGap 2.0.0.

I highly recommend you read this informative FAQ page before you start your app if you are going to submit to the Amazon app store: https://developer.amazon.com/help/faq.html  and this page if you want your app to work on the Kindle Fire devices: http://www.amazonappstoredev.com/2012/09/the-kindle-fire-hd-7-emulator.html

My article below follows these basic steps, but provides much more material to finalize the app: http://docs.phonegap.com/en/2.0.0/guide_getting-started_android_index.md.html#Getting%20Started%20with%20Android

(After I finished the app, I discovered strange error. An Aussie colleague told me to open up the bin/create file in the Downloads folder and do a search for “Darwin.” “Darwin11” should be changed to “Darwin12.” It looks like it would be better off to download PG 2.1.0 instead.)

Download Eclipse

Eclipse is a basic package for developing apps

1. http://www.eclipse.org/downloads/ (I used Eclipse IDE for Java Developers,but you may want to use Eclipse Classic 4.2.1)

Download and install Android SDK

(Software Development Kit – a suite of tools used to develop Android apps)

1. http://developer.android.com/sdk/index.html
2. In Eclipse, install the Android SDK: Window > Android SDK Manager. I found several packages checked already, for Android 4.1 (API 16). I also selected 2.8 (API 8). Go ahead and select any other packages you know you’ll need (if you already have apps created that need particular APIs).
3. I clicked on the button saying, “Install 11 packages..”
4. I clicked on the Accept All radio button, then on Install. This may take 15-45 minutes, depending on which packages you chose.
5. Exit the SDK Manager (click on the red light at upper left) and click on Help > Check for Updates to look for updates the the software you just downloaded. This process will take several minutes.

Download the ADT

(Android Development Tools, an environment that extends Eclipse to quickly develop Android apps) plugin.

1. http://developer.android.com/sdk/installing/installing-adt.html
2. Follow the steps in the page above to Download, Configure and Update the plugin.

Download PhoneGap

I’m downloading 2.0.0 (Aug. 2012, 45.4MB).

1. http://www.phonegap.com
2. It was a saved to my Downloads folder as phonegap-phonegap-2.0.0-0-g2dbbdab.zip. Uncompress by right-clicking and selecting Open. It became folder phonegap-phonegap-2dbbdab
3. Open that folder, then open folder lib. As you can see, there are several phone formats listed, including Android. For each phone platform, PhoneGap uses the software that is unique to that platform. So we will use the Android folder and ignore the others. In the phonegap.com site, click on the link to the Getting Started Guides, and choose the Android link. (Look up in the right corner. You’ll see the version drop-down showing 2.0.0. If you click on the down arrow, you’ll see all the previous versions archived there.)

Start a New Project in Eclipse

(Aug. 2012, Helios Service Release 2.) These steps assume you’ve already created your square launcher icon (the icon on home screen that launches the app), of a minimum of 512 x 512 px, PNG format. Yes, you can skip the creation of this graphic for now. However, I suggest you create your raster app graphic at 2500 x 2500px to accommodate other required sizes. Even better, create your icon with vector software so you can scale it upwards without losing resolution to meet any future need.

1. Launch Eclipse and select menu item New Project. File > New > Project. (If you don’t see Eclipse in the dock at bottom, click on the magnifying glass search icon at the top of the desktop and type the application name.)
2. Under Wizards, select Android > Android Application Project, then Next.
3. In the New Android Application screen, fill out the Application Name and make sure the Project Name and Package Names are correct. The Package Name should NOT start with com.example.appname when you are finished! Mine was com.stevehusting.hustingpockethymnal7.
4. You may set your Build SDK as Android 4.1 (API 16) and minimum Required SDK as API 8, which is Android 2.2. Click Next.
5. In Configure Launcher Icon screen, click on Image > Browse, and select your 512 x 512px icon. You should see your icon reduced into four sizes shown in the Preview.
6. For Foreground Scaling, choose Center. Shape is Square. For  Additional Padding, move the slider to 0%. Click Next.
7. In Create Activity, choose BlankActivity. Click Next.
8. In New Blank Activity, leave the defaults: MainActivity, activity_main, None, blank Hierarchical Parent, MainActivity. OK, that last MainActivity is your app name under the icon. Change that to something about 10 characters or fewer. Click Finish.
9. The Install Dependencies screen tells me that my template “depends on the Android Support library, which is either not installed, or the template depends on a more recent version than the one you have installed. Required version: 8.” I clicked on the Install/Upgrade button. The Android SDK Manager took care of this for me, then I clicked Finish.

Add the Basic PhoneGap/Cordova Files

1. In the Project Explorer window of Eclipse, click on the gray arrow to the left of your project name to expand the folders.
2. Right-click on the assets directory, then on New > Folder.
3. In Folder window, Folder name, type www. Click Finish. You created a new folder in the assets folder.
4. From Downloads/phonegap-phonegap-2dbbdab/lib/android/, right-click on cordva-2.0.0.js and select Copy.
5. In Eclipse, right-click on www and select Paste.
6. In the same way, copy and paste cordova-2.0.0.jar to /libs.
7. In the same way, copy and paste the entire xml folder to /res.
8. We need to verify that cordova-2.0.0.jar is listed in the Build Path. Right click on the /libs folder and go to Build Path > Configure Build Path…. Then, click on the Libraries button or tab, click on Add External JARs…, and navigate again to the cordova-2.0.0.jar file in Downloads to add it to the project. You should see it appear at the top of the list. If not, you might need to refresh (F5) the project once again. Click OK to finish.

Update Eclipse files

1. In Eclipse, open src/ and navigate to the MainActivity.java file. Right-click, Open With > Java Editor.
2. In my Java Developers edition download of Eclipse I have, below my package name:

import android.os.Bundle;
 import android.app.Activity;
 import android.view.Menu;
public class MainActivity extends Activity {
@Override
 public void onCreate(Bundle savedInstanceState) {
 super.onCreate(savedInstanceState);
 setContentView(R.layout.activity_main);
 }
@Override
 public boolean onCreateOptionsMenu(Menu menu) {
 getMenuInflater().inflate(R.menu.activity_main, menu);
 return true;
 }
 }

I changed it to the copy on the phonegap.com website:

import android.app.Activity;
 import android.os.Bundle;
 import org.apache.cordova.*;
public class MainActivity extends DroidGap {
 /** Called when the activity is first created. */
 @Override
 public void onCreate(Bundle savedInstanceState) {
 super.onCreate(savedInstanceState);
 super.loadUrl("file:///android_asset/www/index.html");
 }
 }

Save the file.

2. Now right-click on AndroidManifest.xml and select Open With > Text Editor.
3. Right above <application, put the following:

<supports-screens
 android:largeScreens="true"
 android:normalScreens="true"
 android:smallScreens="true"
 android:resizeable="true"
 android:anyDensity="true" />
 <uses-permission android:name="android.permission.VIBRATE" />
 <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
 <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
 <uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS" />
 <uses-permission android:name="android.permission.READ_PHONE_STATE" />
 <uses-permission android:name="android.permission.INTERNET" />
 <uses-permission android:name="android.permission.RECEIVE_SMS" />
 <uses-permission android:name="android.permission.RECORD_AUDIO" />
 <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
 <uses-permission android:name="android.permission.READ_CONTACTS" />
 <uses-permission android:name="android.permission.WRITE_CONTACTS" />
 <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
 <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
 <uses-permission android:name="android.permission.GET_ACCOUNTS" />
 <uses-permission android:name="android.permission.BROADCAST_STICKY" />

Remove all the permissions your app doesn’t need. Or comment them out NOW with /* at left and */ at right of each line. (To learn more about permissions, see here,  here, and here. )

4. Update the following line to replace “com.example” with your own information:

package="com.example.yourappname"

You may get a popup asking if you want to update, so click OK.

Explanatory note 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 (http://developer.android.com/guide/topics/manifest/uses-sdk-element.html).

(If you started clicking around in Eclipse like I did, you may lose the Project Explorer window. Just go to Window > Show View > Project Explorer to bring it back.)
5. Support orientation changes by pasting the following inside the <activity></activity> tags:

 android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale"

Add Your Project’s Assets

1. Open the folder containing all your already-created www “assets” in Finder (your project’s HTML, CSS, Javascript, videos, images, etc., files). With the window side by side with Eclipse, copy/paste or drag all your assets to Eclipse’s /assets/www folder. Make sure “Copy files and folders” is selected.
2. Make sure you reference the new cordova-2.0.0.js file in your pages.
3. In Eclipse, select the project name in the Package Explorer and refresh the project (File > Refresh, or F5).
4. Right-click on your project name again, and select Validate.  It’ll give you (usually useless) messages in a popup.
5. Right-click on your project name again, and select Debug As > Android Application. If you have a working emulator installed, then it will launch and you’ll see the home screen. Slide the lock over and the app will launch, if all is well. Also, you’ll see the LogCat screen at the bottom of the Eclipse environment as it records what is happening in the emulator.

Specify your App Title

1. (Just in case you missed this earlier, here’s another way to set your app title under the icon.) 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 where shown. Keep the text short, like 11 characters are fewer, or it will be truncated. Make sure to check this later in your device:

<string name="app_name">App Title Here</string>
<string name="hello_world">App Title Here</string>
<string name="menu_settings">Settings</string>
<string name="title_activity_main">App Title Here</string>

2. Save the page.

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 creat the “apk” file that is uploaded to the app store for 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. [WARNING: if this is a upgrade, use the same name as the earlier version!]
4. Key [“Private Key”] Creation dialog:
Alias: same as app_name, no spaces.
password of keystore.
validity: 50 [meaning, good for 50 years. Validity period must end after 22 October 2033]
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 location where Eclipse will save the program’s .apk file that you would upload to Google Play.

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.

If you get: “keytool error: java.io.IOException: Incorrect AVA format”, then an invalid character was used in one of the previous screens. 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 Nexus 7 does not include an SD card. I downloaded DropBox 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 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. 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.
5. When you are satisfied, open the project in Eclipse, do a restore (F5), and make your final api file for upload to your favorite app store.

Debugging: LogCat to the Rescue

If you are still having problems, like your app simply crashes in the device, you may want to go online and post your problem. You may be told, “What’s your adb logcat say?” Be ready to give it to them with these steps.

1. Hook up your device to the computer.
2. Prepare your device for debugging by going to Settings > Developer Options (or similar) and turning on USB Debugging and Allow Mock Locations.
3. Right-click on your app name and choose Run As > Android Application. Your application starts to load onto your device.  Quickly go to the next step.
4. Window > Open Perspective > DDMS. You should see your device listed under Devices. You’ll see DDMS at bottom left and LogCat at the bottom right. There’s your LogCat entries. You should see a drop-down for various filters, such as verbose and error. Choose Verbose. When you app hangs, then  drag from the top to the bottom in that field so it’s all highlighted.
5. Click on the 3.5″ floppy drive Save icon (remember those?) to save to a text file. Copy and paste those contents into the forum when they ask for the adb logcat.

Prepare Promotional Artwork

You’ll want to include screen captures for upload to Google Play. Choose screens carefully to present your app in its best light. What if your device doesn’t do screen captures? My eLocity tablet and Google Nexus 7 did not have this native functionality, nor did I find apps that performed this function. All is not lost, though; here is what I did.

1. Just double-click the index.html file in the Finder (workspace folder) to open it in a browser, then narrow the browser window to approximate the device screen proportion.
2. Use your favorite screen grab utility to get the picture.
3. Use GIMP or other photo-retouching program to crop it appropriately.
4. 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.

Screen sizes needed:
(Need at least 2 images) 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
You may upload screenshots in landscape orientation. The thumbnails will appear to be rotated, but the actual images and their orientations will be preserved.
4. Prepare a High Resolution Application Icon for Google Play: 512 x 512 pixel JPG image.
5. Promo Graphic: 180w x 120h PNG or JPG.
6. Feature Graphic: 1024 x 500 PNG or JPG.
7. Prepare a promo video.
8. If preparing for iPhone: 1024 x 1024px JPG image, and screen grabs.
9. If preparing for Amazon App Store release: 1024 x 500px PNG or JPG promotional image, and screen grabs.
10. If you will create an an ebook version through smashwords.com, create a 1400 x 2100px JPG image for the book cover.

Prepare Copy for App Store

You’ll need this information on hand when filling out the form for apk submission in Google Play.

Language
Title (English)
Description (English, 4000 characters maximum)
Recent Changes (English, 500 max.)
Promo Text (English, 80 max.)
Application Type (Applications, Games)
Category
Copy Protection (Off or On). On helps prevent copying of this application from the device. Increases the amount of memory on the phone required to install the application.
Content Rating (from “Everyone” to “High Maturity.”)
Pricing (Free, Paid)
Default Price USD
Auto FIll button. Automatically populate all price fields with a one-time conversion of the default price into local currencies based on today’s exchange rate and the tax rates defined in the account owner’s Google Checkout Merchant Account (if applicable).
Contact Information (Website, Email, Phone)
Enable Google Cloud Messaging Stats
(There is no keyword field, as there is in the iTunes App Store uploads.)

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 https://iphonedevlog.wordpress.com/phonegapcordova-crib-sheet/ and look under “App Stores.”