PhoneGap 2.3.0 in Mac OS X Mountain Lion 10.8: from Download to iOS App Store

These instructions follow the Getting Started with iOS guide at http://docs.phonegap.com/en/2.3.0/guide_getting-started_ios_index.md.html#Getting%20Started%20with%20iOS.

Before you can install the app on your device, you need to sign up as a Developer with Apple and go through the business documentation, Certificate Signing, and Developer Certificate process, all of which are detailed on Apple’s web site (https://developer.apple.com/programs/ios/), under Prepare for App Submission. Nevertheless, you can skip all those steps and still see your work in the the iOS Simulator included with Xcode. Xcode is a free download you can download now, but the Developer status comes at $99 a year. If you are new to creating apps for the App Store, you’ll want to peruse the App Store Review Guidelines to make sure your app falls within acceptable limits: https://developer.apple.com/appstore/resources/approval/guidelines.html 

Xcode Install and/or Upgrade

1. This install requires Xcode 4.3 or later, and Mac OS X Lion 10.7 or later, both available from the Mac App Store (http://www.apple.com/osx/apps/app-store.html). Install those now if you don’t already have them.

As of this writing, I have Xcode 4.5.2 installed. You must use Xcode 4.5 in order to code for iOS 6 on iPhone 5. (Note to self: I use an iPod touch for a development device. As per an Apple Developers Forum reply about iPod touches, only the 4th and 5th generation iPod touches support iOS 6.)

2. This PhoneGap install requires the Xcode Command Line tools, so I opened Xcode to download it – Xcode Preferences > Downloads > Components > Command Line Tools > Install (115.4MB). Downloading this package will install copies of the core command line tools and system headers into system folders, including the LLVM compiler, linker, and build tools.

Download Apache Cordova

1. I downloaded PG 2.3.0 from http://www.phonegap.com/download (28.2MB), released January 7, 2013. The zip file was unzipped and expanded as:

Downloads/phonegap-2.3.0/

(That was a departure from the online documentation, which on Jan. 17 seems to imply that there are two zip files to click on.)

PG now uses Terminal to set up PhoneGap. Here are the install instructions using Terminal, which you follow when you want to create a new project.

Create a New Xcode Project using Terminal

1. Create a directory where you’ll store your project files. In my case, it was:

Documents/PhoneGap_apps/Phonegap_apps/testPG230

2. Open Terminal by tapping on the magnifying glass in the upper right corner of your monitor and typing Terminal in the Spotlight box (or by clicking on the Terminal app in the dock). Click on the Top Hit, Terminal. A Terminal app window opens.
3. You’ll need to type out three parameters. I suggest putting them in a separate text file until you get it right, then copy/paste into Terminal.
4. First parameter: project location. Drag the directory you created to the Terminal and copy that location:

/Users/Steve/Documents/PhoneGap_apps/PhoneGap_apps/testPG230/

5. Second parameter: package name. In Xcode, the name will be in reverse-domain format plus the app name, no spaces:

com.stevehusting.TestingPG230

6. Third parameter: project (app) name:

TestingPG230

7. Return to the phonegap-2.3.0 Downloads directory and open it up to:

Downloads/phonegap-2.3.0/lib/ios/bin

8. Hold down the Command key and drag the bin folder to the Terminal to set that directory as the starting place, then hit Enter.
9. Type in the Terminal:

./create

10. Copy and paste each of your parameters into the Terminal in order, with a space between each, including a space after ./create:

./create /Users/Steve/Documents/PhoneGap_apps/PhoneGap_apps/testPG230/ com.stevehusting.TestingPG230 TestingPG230

11. Wait until the cursor returns, then exit the Terminal.

Problem found:
When I did step 10, the Terminal returned “… is a directory.” Checking the project directory revealed it to be empty. I needed to hold down the Command key while dragging the bin folder over, otherwise it was not changing to that directory.

(If you check the PhoneGap Getting Started Guide online, you’ll find several optional features that I’m not covering here.)

View files in the Simulator

1. Navigate to the project’s directory and look at the files created. If you look inside, you’ll find it filled with folders and files. A www file has been created for you, complete with the cordova-2.3.0.js file and startup index.html page (the page you’ll see when opening your app in the device or emulator). The res (resources) folder contains all the icons and splash images. You’ll later replace all of these with your own images of the same size.

2. Double-click on the TestingPG230.xcodeproj to open the file in Xcode.

3. To view the app online in the emulator, click on the gray arrow for the blue icon for project name in the upper left corner of the Xcode environment. Now you see the folders for the project appear.

4. Click on the www/index.html file. The contents appear in the middle pane of the Xcode environment.

5. At top left, to the right of the Run icon is the Scheme, showing the project name and the emulator, such as iPad 6.0 Simulator. Click on the Simulator name and choose iPhone 6.0 Simulator. (When you archive (create your binary for the app store), you’ll change it again to “iOS Device.”)

6. At top left, click on the Run icon.

7. The app has been successfully deployed when you see the PhoneGap icon splash screen, then it’s replaced with “Device is Ready” in a pulsing box in the iPhone Simulator. Click on the Simulator’s Home button (at bottom).

8. Click on the Xcode window and click on Stop.

9. Click on the Simulator, then hold down on the project’s icon until it quivers. Click on the X in the corner of the icon to delete the icon. Confirm, then tap the Home button.

9. Let’s quickly test the new inAppBrowser. Completely replace the index.html page with the following:

<!DOCTYPE HTML>
<html>
<head>
<script type="text/javascript" src="cordova-2.3.0.js"></script>
<script>
function onLoad() {
document.addEventListenter(
‘deviceready’, onDeviceReady, false);
}

</script>
</head>
<div style="padding:1em 2em;"><a href="#" onclick="window.open('http://www.phonegap.com','_blank');"> inAppBrowser with location bar</a> 
<br><br> 
<a href="http://www.phonegap.com">Plain URL (no return to app)</a> </div>
</body>
</html>

10. Save the page and hit Run.

11. When the screen loads, click on the top link. It loads in the inAppBrowser, showing the location bar with the URL visited at bottom, and below that, the Done button. Click on the Done button to return right to the app.

If you click on the bottom link, you’ll see why the inAppBrowser is important: you can’t return to the app directly from that page. You’ll have to restart the app from the home screen.

To learn more about the inAppBrowser, visit: http://docs.phonegap.com/en/2.3.0/cordova_inappbrowser_inappbrowser.md.html#InAppBrowser and http://wiki.apache.org/cordova/InAppBrowser

Problems found:
If you have deprecation warnings or missing header warnings, see this page for PhoneGap’s fixes: http://docs.phonegap.com/en/2.3.0/guide_getting-started_ios_index.md.html#Getting%20Started%20with%20iOS

Check the Properties List (.plist)

1. Click on the yellow Resources folder in Xcode’s left pane and click on projectname-info.plist and make sure the Bundle Identifier line is correctly populated with the reverse-domain-name you included in the Terminal.
2. Still in projectname-info.plist, change the Bundle Display Name to the name you want under the icon on the home screen. Keep it short and remember to test it later in your device. Titles of 11 or fewer characters work best. Titles too long will truncate and end with ellipses (. . .), which look poor!
3. Still in projectname-info.plist, hold down the cursor over an entry in the Key column until the + and – buttons appear, click on the + button, and wait a moment for the drop-down to appear to add a property. Choose the “Icon already includes gloss effects”, and “YES” if you don’t want Xcode to add the gloss effect to the app icon that will appear on the device’s home screen. Select “NO” (default) if you want Apple to add the gloss to top of icon.
4. Scroll down in the drop-down to see the many properties you can set on this page. For instance, Copyright (human readable), Initial interface orientation, Status bar is initially hidden, and others are available.
5. Before leaving this page, save.

Set Up the Build Settings

1. At the top of the left folder pane, click on the blue heading showing your project name. You see three panes in the Xcode environment. In the middle pane under TARGETS, click on the project name. Under the Summary tab, make changes where necessary, such as Version number of project (1.0), Devices supported (iPhone, iPad, or both – Universal), and Deployment target. It’s important to select a deployment target that your code supports AND (for testing purposes) the earliest one your test device includes. I chose 4.3, which is believe is the minimum this version of PG supports. Also click on the Supported Device Orientations you want your device to support. Don’t worry about the Main Interface. Lastly, if you have supplied the icons for the project, they should appear in the App Icons section (scroll down to see). If one is missing, you’ll see that, too. More about icons later.
2. Under Build Settings tab, Architectures heading, select your Base SDK to reflect the latest iOS installed on your test device. In my case (as of Sept. 2012), it’s iOS 6.0.
3. Under Build Settings tab, Code Signing heading, Debug setting, make sure the iPhone Developer setting is current if you want to test in your device. For the Release setting, choose the Distribution profile. These would have been created online, downloaded, and installed previously. You can save this step for later, when you are ready to upload to Apple.
4. Under Build Settings tab, Deployment heading, select the iOS Deployment Target your code will support, AND if you can test it on a device containing that version. It should be the same as step 2.

5. Under PROJECT, click on the project name (above the TARGETS name). You will repeat the above steps with the same settings. Many errors arise from entering the information only once – the information has to be entered twice.
6. Under Build Settings tab, Architectures heading, select your Base SDK to reflect the latest iOS installed on your computer.
7. Under Build Settings tab, Code Signing heading, Debug setting, make sure the iPhone Developer setting matches your project name if you want to test in your device. Choose your Distributor profile for the Release setting if you have one already.
8. Under Build Settings tab, Deployment heading, select the same iOS Deployment Target.

Fixing Warnings

Xcode, after every launch in the Simulator, shows us any warnings or errors it generates in the left column. Warnings have a yellow triangle associated with them; errors are symbolized by a red circle and a failed build. The file containing the warnings is listed as well as the specific warning for that file. A file may contain more than one warning. This project generated a few warnings. Let’s tackle them now.

Fixing Warnings: “missing Default-568h@2x.png”

1. iOS 6 in iPhone 5 with the Retina 4-inch display requires a different splash screen (launch screen) image size. When you click on the warning, Xcode will ask if you want it to supply the image for you. If you answer yes, the warning will go away, and you’ll have a black starting image. You’ll see it listed right above the blue www folder in Xcode if you click on the gray folder icon under Run at top left.
2. If that’s not what you want, simply prepare your own image and upload according to the instructions coming up.

Fixing Warnings: MainViewController.m, AppDelegate.m “invokestring” is deprecated

1. After my build, I got the following warning three times:
“invokestring” is deprecated
2. 1. Open Classes > MainViewController.m and comment out this section by adding /* before and */ after as shown:

/*
#pragma UIWebDelegate implementation

– (void) webViewDidFinishLoad:(UIWebView*) theWebView
{
// only valid if ___PROJECTNAME__-Info.plist specifies a protocol to handle
if (self.invokeString)
{
// this is passed before the deviceready event is fired, so you can access it in js when you receive deviceready
NSLog(@”DEPRECATED: window.invokeString – use the window.handleOpenURL(url) function instead, which is always called when the app is launched through a custom scheme url.”);
NSString* jsString = [NSString stringWithFormat:@”var invokeString = \”%@\”;”, self.invokeString];
[theWebView stringByEvaluatingJavaScriptFromString:jsString];
}

// Black base color for background matches the native apps
theWebView.backgroundColor = [UIColor blackColor];

return [super webViewDidFinishLoad:theWebView];
}
*/

Save the file.

2. Also open Classes > AppDelegate.m and comment out the following line by adding two slashes to the left, like this:

// self.viewController.invokeString = invokeString;

Save the file.
4. All three invokestring warnings should now be gone.

Set Up Your Icon and Splash Images

1. Still in Xcode 4, click on the Resources folder at left. Replace the splash and icon images with your own. Right-click on the folder and select to “Add files to ‘project name…’”, and navigate to the files for insertion.

If you haven’t made the icon and splash screen files, here are the required pixel sizes of each (from Apple’s iOS HIG – Human Interface Guidelines):

Images preferred are PNG, 24 bits depth.

App Icons, iPhone:
icon.png = 57 x 57px
icon@2x.png = 114 x 114px
For iOS7, icon size is now 120px x 120px high resolution — this change is mandatory for all new apps

App Icons, iPad:
icon-72.png = 72 x 72px
icon-144.png = 144 x 144px

splash or launch images:
Default.png = 320 x 480px
Default@2x.png = 640 x 960px (Retina 3.5 inch)
Default-568h@2x.png = 640 x 1136px (Retina 4-inch). For simple apps like mine, just adding this to my project will automatically adjust the height of all my pages – no other coding will be needed to eliminate the black bars above and below.

iPad splash or launch images:
Default-Portrait.png = 768 x 1004px (corrected)
Default-Landscape.png = 1024 x 748px (corrected)
Default-Portrait@2x.png= 1536 x 2008px
Default-Landscape@2x.png= 2048 x 1496px

You’ll need to add the above icons to your Xcode project internally. The following images are uploaded to the App Store separately:

App Store icons (JPG or PNG):
1024×1024 (iPad)
512 x 512 (iPhone)

Newsstand apps, later iPhone and iPad:
At least 1024 pixels on the longest edge

Newsstand apps, earlier iPhone and iPad:
At least 512 pixels on the longest edge.

Screenshots (JPG or PNG):

You can get the screenshots by hooking up your device to your computer, then in Xcode going to Window > Organizer > Devices, then under Library choose Screenshots. Go to the screen you want to grab in your device, hold down both device’s Home and On/Off buttons momentarily to take the screengrab, then it should appear in Organizer (I’m recalling this from memory). You can then click on the selected screenshot and then on Export to save it to a folder. A button allows you to Save as Launch Image too!

On a hunch, I opened my purchased Grab app and got a screenshot of the iOS screen in the iOS Simulator. Upon trimming it down, it was a TIFF image of only 318 x 454px size. I would need to open a graphic program to save as PNG and size it up to 320 x 480.

An alternate that works for me is to open your app in a browser, size it by eye, then do a screen grab. If the grab dimensions were too small, then enlarge the view (control +) and try again. Then in your graphics program, open a window of the correct size and place the image there, sizing the width to fit and letting the bottom slide out below.

Screenshots should not include the mobile status bar along the top. Here are the requirements for upload to the App Store:

The requirements for high-resolution screenshot images are 960 x 640, 960 x 600, 640 x 960, or 640 x 920 pixels. Images must be at least 72 dpi, in the RGB color space, and the file must be .jpeg, .jpg, .tif, .tiff, or .png. You can update your screenshot files at any time in iTunes Connect.

In addition, the iPhone 5 has a new screen size. New and revised apps must submit the following sizes:
portrait: 640 x 1136px or 640 x 1096px
landscape: 1136 x 640px or 1136 x 600px

Last-minute Tidying 

Assuming you’ve got your Developer’s certificates and profiles in working order, and your app is working fine in your test device, it’s getting closer to putting it on the App Store. If you are getting code signing errors, head over to here to debug them: http://developer.apple.com/library/ios/#technotes/tn2250/_index.html

1. In Xcode, check out the config.xml file to see if there are any changes you need to make. There, you’ll set whether you want the “bounce” effect; splash screen settings; web storage backup; media playback settings; and so on. Use this guide to undertand what each line does: http://cordova.apache.org/docs/en/edge/guide_project-settings_ios_index.md.html#Project%20Settings%20for%20iOS

2. You’ll want to get rid of all those .DS_Store files cluttering up your app’s folders. They’re a security hazard if they fall into the wrong hands. To do this system-wide, copy and paste this into Terminal (this tip from: http://helpx.adobe.com/dreamweaver/kb/remove-ds-store-files-mac.html):

sudo find / -name “.DS_Store” -depth -exec rm {} \;

You’ll be asked for your Administrator password. Once that’s entered in, wait a while as it goes to work and the prompt returns.

3. If everything is working fine, then do a File > Create Snapshot of your current working project before the next steps so you can revert if necessary. A Snapshot is a copy of the project stored away. You can delete these snapshots by going to Window > Organizer, click on Projects at top, then on the project name at left. After clicking on a Snapshot, click on the Delete Snapshot icon at lower right. This will free up a lot of memory after you’re sure you will no longer need the earlier versions. If you need to revert to an earlier version (snapshot) of the project, you will first create a new folder in Finder, then click on the Restore Snapshot icon to save it to that folder. You’ll have two versions of the project; this way the reverted version will not overwrite the previous version.
4. Fill out the Application Assets Template located here: http://wp.me/pyIb9-1o
5. You’ll need to go online to the Apple Developer site, sign in, and click on the iTunes Connect link.
6. Click on Manage Your Applications and either Add New App, or choose an existing app to upgrade. Follow the steps online and transfer all the information into the fields from the Application Assets Template you just filled out.
7. You need to finish to the point you see a button saying that it is “waiting for binary.” With that status, you are ready to upload a binary. Let’s do that after we back up some important files.

Back up Files

1. Open Keychain Access (click on the magnifier icon at top right of your desktop and type in “keychain” and select the app). Right-click on the certificates and export each one to your computer (giving each one a name similar to the name in the Keychain Access line), then send it off to a safe backup location. Without these files, you wouldn’t be able to upload successive versions of your apps.

2. Back up your password files. Go to Users/[name]/Library/Keychains and copy the any.keychain files there to a safe place. /Library is a hidden folder.

To show the hidden files, type in Terminal …

defaults write com.apple.finder AppleShowAllFiles TRUE

… and hit Return.

Then type in Terminal …

killall Finder

… and hit Return. The desktop will go blank, then after a while will refresh. Open the Documents folder, then in Finder, Go > Enclosing Folder, and see the hidden files in gray, including /Library.

To hide the hidden files, repeat both commands, but substitute FALSE in place of TRUE.

3. Now would be a good time to create a snapshot of your work at this point in time (File > Create Snapshot). You’ll be able to revert to this approved version at a later date if you need to.

Upload a Binary for the App Store

1. A binary of the app is the compiled version of the app that is made up of 0s and 1s. To compile your app for the App Store, make sure your device is unconnected and the Scheme in Xcode shows “iOS Device.”
2. Do a Product > Clean while holding down the option key. Then do a Product > Archive and wait for the app to build.
3. The Organizer window should open. Click on Distribute. If all went well, then follow the steps until the app has been successfully validated and uploaded to the App Store.
4. While you wait until you get an email saying the app is “Ready for Sale,” you can go back to the Developer’s site and click on the link for App Store Approval Process (found in the same right menu below the iTunes Connect link). Along the way, you’ll get status notifications in your iPhone or iPod touch giving you the status of your app as it goes through the approval process.

Credits:
Mac®, OS X®, Apple®, Xcode®, App Store℠, iPad®, iPhone®, iPod® and Finder® are trademarks of Apple Inc.