PhoneGap 2.1.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.1.0/guide_getting-started_ios_index.md.html#Getting%20Started%20with%20iOS. (Earlier versions of this PG pointed to the wrong file.) PhoneGap uses “PhoneGap” and “Apache Cordova” terminology on its web site. I’m going to use “PG” often in this article for shorthand.

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.
2. I already had Xcode installed. With the September 2012 release of iOS 6 on the new iPhone (with the longer 4″ screen – this article was written late Sept. 2012), a new version of Xcode was available. I upgraded Xcode to 4.5, which included support for iOS 6. 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.)
3. 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.1.0 from http://www.phonegap.com/download (22.2MB). The zip file was unzipped and downloaded to

Downloads/phonegap-phonegap-26d211b/

2. Initially, I had no idea where to go next to get the install working. I looked in lib/ios/bin and saw no dmg file. Actually, PG now uses Terminal to set up PhoneGap. I’m normally an icon-pushing guy, so I was pleasantly surprised how well the command-line interface worked to set up the project with Terminal. I had a few false starts, because I included a $ in front of my terminal text input because it was shown in the getting started guide. As you’ll see in Terminal, your waiting message already ends in a $, so you don’t need to type that in. Here are the install instructions using Terminal, which you follow when you want to create a new project.

Create a New Xcode Project 

1. Open Terminal by tapping on the magnifying glass in the upper right corner of your monitor and typing Terminal in the Spotlight box. Click on the Top Hit, Terminal. A Terminal app window opens.
2. In Terminal, I changed directories to start at my Downloads folder by typing:

cd Downloads

3. Determine where you’ll store your new project files and write down the path, starting with /Users.
4. In Terminal, you’ll make the path to the ios/bin/create file inside the PG folder you just downloaded, then to the new project’s location, then the reverse-domain-style package name, then the project name, no spaces, like this:

./phonegap-phonegap-26d211b/lib/ios/bin/create /Users/[myname]/Documents/NewProject com.stevehusting.projectname projectname

5. Wait until the cursor returns, then exit the Terminal.
6. If you look inside Documents/NewProject, you’ll find it filled with folders and files. A www file has been created for you, complete with the cordova-2.1.0.js file and startup index.html page (the page you’ll see when opening your app in the device or emulator). In the past, PhoneGap startup Javascripts were put at the head of the index.html file; now they’re stored separately in js/index.js as an external file. If you’ve used PG in the past, I think you’ll agree this was a very smooth install! They’ve done a very good job with this version.
7. Double-click on projectname.xcodeproj to open it in Xcode.
8. 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.
9. Click on the index.html file. The contents appear in the middle pane of the Xcode environment.
10. As a test I’ll explain later, add the following line directly under the <h1>Apache Cordova</h1> line:

<p><a href=”http://www.phonegap.com/”>Click Me</a></p>

11. Hit File > Save to save the page.
12. In the upper-left of the Xcode window, you’ll see “Run,” “Stop,” and “Scheme.” Above Scheme I see “projectname > iPad 6.0 Simulator.” You can click on on iPad 6.0 Simulator to change it to iPhone if you wish. (When you archive — create your binary — for the app store, you’ll change it again to “iOS Device.”) Go ahead and click on the button above Run.
13. You’ll see a Build Succeeded box, the iOS Simulator load, then the index.html file in an simulated iPad 6 showing the Apache Cordova logo and “Device is Ready” pulsing below. Pretty cool!
14. Click on the link. You’ll find that the link is broken. In Xcode, look below the index.html file contents to the log window. It’ll tell you why the link did not work:

ERROR whitelist rejection: url=’http://www.phonegap.com/&#8217;

We will be fixing this in the next section.
15. In Xcode, click on the Stop button, then on the gray folder button below the Run button to see the files again.
16. Tap on the simulator and exit the Simulator.

Setting Up the Project in Xcode 

1. To take care of the whitelist error, add your allowed hosts in Resources > Cordova.plist under ExternalHosts (such as http://www.phonegap.com). To do this step, click on Resources > Cordova.plist, then on the gray triangle to the left of ExternalHosts, then on the + sign and type the text in the far right field. Typing in an * will allow all external URLs to work. Then tap outside the field and save the changes by File/Save. (To understand all the other settings on that file, visit here: https://github.com/apache/incubator-cordova-ios/blob/master/guides/Cordova%20Settings%20File.md).
2. Click on Run and try the link again. It should take you to the PhoneGap.com web site. However, the web page opened in a new screen, and there was no way to get back to the app from there. We would need to turn off the device and turn it on again to get the app to open again. So we need to install the ChildBrowser plugin to rectify this (I amy write an update on this install later. Perhaps the article I wrote earlier for Childbrowser installation will still work. I have not checked).
3. Drag or copy all the HTML, CSS, and JS contents of your project into the “www” folder in the Finder window, NOT into Xcode.
4. Run Product > Clean, then Run Xcode in the simulator to test. Test the external URLs and check for any whitelist errors, and fix, if you decided not to use *.

Check the Properties List 

1. Click on the 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. In YourProjectName.plist, hold down the cursor over an entry in the Key column until the + and – buttons appear, and click on the + button 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. 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 (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 computer. 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

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, then going to Window > Organizer > Devices, then under Library choose Screenshots. Go to the screen you want to grab in your device, hold down both buttons momentarily to take the screengrab, then it should appear in Organizer (I’m recalling this from memory). Yo 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 Grab, and got a screengrab 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 alternative 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

Build for the App Store!

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 time to put 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. 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.
2. Fill out the Application Assets Template located here: http://wp.me/pyIb9-1o
3. You’ll need to go online to the Apple Developer site, sign in, and click on the iTunes Connect link.
4. 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.
5. 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 next.

Upload a Binary

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.