Using PhoneGap 3.3 CLI on Mac OS X Mavericks to Build iOS Projects


This article gets you up to speed on how to integrate  your HTML/CSS/JS app with PhoneGap/Cordova into an iOS app using a Mac and prepare it for App Store submission. This article assumes you’ve already followed the steps on http://iphonedevlog.wordpress.com/2013/08/16/using-phonegap-3-0-cli-on-mac-osx-10-to-build-ios-and-android-projects/ to:

Download Node.js
Add PATH statements to .profile
Install Cordova CLI
Install Homebrew

In this article, I am referencing Mac OS X Mavericks 10.8.5 and Xcode 5.0.2 on a Mac Mini. PhoneGap CLI 3.3.0 was downloaded. I am referencing “cordova” in the command-line interface, not “phonegap.” This project will not use the PhoneGap Build service.

Download:
OS X Mavericks and Xcode: http://www.apple.com/osx/apps/app-store.html
PhoneGap: http://www.phonegap.com/

Before you can install the app you create with PhoneGap on your device, you need to sign up as a Developer with Apple and go through the business documentation, Certificate Signing, Developer Certificate process, and more, 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 — you just won’t be able to view the app in your device or App Store. Xcode is a free download you can download now, but the Developer status comes at $99 a year.

Although you can develop the HTML/CSS/JS portion of an iPhone app on a Windows machine, you’ll still need a Mac with Xcode to convert the code to the binary that is uploaded to the App Store. You need a Mac to make iPhone apps. (PhoneGap Build can create this binary for you from your files, but you still need a Mac to download and install certain certificate files.)

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 meets the rules (requires sign-in): https://developer.apple.com/devcenter/ios/index.action You are strongly encouraged to make use of these documents before you start your project, lest you run afoul of Apple’s rules for what apps they will and will not allow in the App Store.

PhoneGap/Cordova now uses the command-line interface (CLI) to generate the files needed to start the project. However, one still needs to enter Xcode to create the final binary for uploading to Apple.

This article covers the creation of an app from CLI creation to upload binary to Apple.

Resources:
http://docs.phonegap.com/en/3.0.0/guide_platforms_index.md.html#Platform%20Guides
http://phonegap-tips.com/articles/the-nodejs-command-line-interface-for-phonegap.html

Create PhoneGap Project Files With CLI

1. Open a Finder window and select the folder you want to create your project’s folder inside of.
2. Open the Terminal app (find it in the dock below, or click on the magnifying glass at top right and type in “terminal”), type cd (for “change directory”), drag the selected folder to the Terminal screen, let go, click on the Terminal to select it, then hit Return. This will orient the commands to that folder.

For this project, all of your commands will always begin with “cordova.” Some online tutorials and PhoneGap documentation will tell you to use “phonegap;” in that case, change it to “cordova” and it should work fine.

3. Type the following, replacing “YourCompany” with your name and “TestAppIos” with the name of your project:

cordova create TestAppIos com.YourCompany.TestAppIos TestAppIos

Preliminary files are generated. (In iOS lingo, com.YourCompany.TestAppIos is called the “Bundle Identifier.”)
4. Enter the new folder you created in Terminal with the cd (change directory) command:

cd TestAppIos

5. CLI only downloaded the skeleton files needed for all platforms. Now you need to download the specific files for iOS:

cordova platform add ios

6. Build the default project with:

cordova build ios

If you get a message saying that codesign wants to sign using the key in your keychain, click on Allow or Always Allow.
7. To see the project in a simulator, type:

cordova emulate ios

(That’s “emulate” not emulator.) This will work if you have Xcode installed; it uses Xcode’s simulator. You may receive an error in Terminal that the simulator session timed out. Just give it a minute and see if the simulator doesn’t start anyway. After it starts and the Cordova default “Device is Ready” page does not appear, leave it on and run the cordova emulate ios command in the terminal again.

An iPhone Retina (4-inch) screen appears, showing the PhoneGap logo above the words APACHE CORDOVA with “Device is Ready” pulsing. This shows that the project is successfully showing the default index.html screen.

8. Try this with the iPhone emulator:
a) Click on the simulator then on Hardware > Device and choose among the available devices.
b) Click on Window > Scale and resize the simulator.
c) With Edit > Copy Screen you can grab it and possibly save for uploading as screenshots, if your screen and simulator sizes are large enough.
d) Click on Debug > Open System Log… to view the console output in separate windows. I personally did not find this information helpful.

If you only have one platform installed, you can shorten the commands above to “cordova build” and “cordova emulate.”

If you have an earlier cordova version installed (check with cordova -v), you can update to the latest version with:

npm update -g cordova

Getting familiar with the Xcode environment

1. Navigate to the project’s platforms/ios directory and look at the files created. A /www folder has been created for you, complete with the cordova.js file and startup index.html page (the page you’ll see when opening your app in the device or emulator). The TestAppIos folder contains many Xcode files for your project.

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

3. Click on the gray arrow by the project name in the upper left corner of the Xcode environment. Now you see the folders for the project appear below it.

4. Click on the gray arrow by the /www folder to open it. Single-click on the index.html file. The contents appear in the middle pane of the Xcode environment. I noticed a warning in mine: “for iOS7, remove the width=device-width and height=device-height attributes.” A URL is given for more info.

5. At top left, to the right of the large gray Run arrow, is the Scheme, spelling out the project name and the emulator, such as “iPhone Retina (3.5-inch).” Click on the Simulator name and change it to another if you wish. [When you archive (create your binary for the app store), you’ll change it to “iOS Device.”]

6. At top left, click on the large gray arrow Run icon. You should see the same contents appear in the simulator as when you ran the CLI command, cordova emulate ios.

7. Click on the Xcode window to bring to front. At the bottom you can see the console output when the project was Run.

8. To halt the process, click on the gray Stop square (next to the gray arrow Run button). 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 Hardware > Home. I recommend you delete the icon before creating a new build lest errors pile up. Sometimes the old code is not fully overwritten with a new cordova build/emulate process.

Using the API Reference

On the PhoneGap site at http://docs.phonegap.com/en/3.3.0/guide_cli_index.md.html#The%20Command-Line%20Interface we can see the many device-level APIs available to us to interact with the mobile device (scroll down left column to see them). PhoneGap does not automatically install every feature or plugin, and that keeps the code footprint down. The page above gives the commands needed to download many different plugins. The following link gives us a chart showing plugin support: http://docs.phonegap.com/en/3.3.0/guide_support_index.md.html#Platform%20Support

Here, we’ll incorporate the InAppBrowser (IAB) API. The IAB allows us to open external URL links from within the app. Some developers would prefer this over the default of leaving the app and opening a web browser, shutting down the web browser when done, then restarting the app again. The IAB opens the link in its own frame with a Done button bringing the user back into the app.

We first download the IAB as a plugin using CLI. Here are the two steps to do it.
Step I: download the plug-in
a. Still in your project’s folder in Terminal, type the add command:

cordova plugin add org.apache.cordova.inappbrowser

b. Verify that the plugin is installed with the ls (list) command:

cordova plugin ls

Step II: add to the config.xml file

a. Open the TestAppIos/www/config.xml file in a text editor (I use TextWrangler) and make sure the following is above the </widget> line. Add it if it isn’t:

<feature name="InAppBrowser">
 <param name="ios-package" value="CDVInAppBrowser" />
</feature>

While we’re on that page, change the other sections:

1. Change the version=”0.0.1″ to the correct version, like version=”1.0.0″ This MUST match the version you enter for the app in the developer console, or you will get errors when validating in Xcode later. “1.0.0″ is not the same as “1.0″
2. Change the <description> line.
3. Change the <author> section.
4. Make sure the “widget id” is (or will be) the same as what you enter in the developer console online as the AppID, include same case.

Now let’s test it. Completely replace PhoneGap’s TestAppIos/www/index.html page with the following lines that start and end with the HTML lines (open it from the Finder, not within Xcode):

***** START BELOW THIS LINE *****

<!DOCTYPE HTML>
<html lang="en">
<head>
 <meta http-equiv="content-type" content="text/html; charset=utf-8">
 <meta name="viewpoint" content="user-scalable-no, initial-scale=1, width=device-width">
<!-- Set the viewport width to device width for mobile. May introduce problems with iOS 7 on iPhone, though. -->
 <meta name="viewport" content="width=device-width">
<title>Hello World test</title>

<script src="cordova.js"></script>
<script>
function onBodyLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
</script>
<script>
function onDeviceReady() {
}
</script>
<style type="text/css">
 html, body { background-color: #FFFFCC; margin: 0; padding: 0; }
 #wrapper { margin:0; width:100%; padding-top: 2em; }
 p { color: black; font-family: Helvetica; padding:.5em; margin: .5em; }
 p.button { font-size: .8em; border-radius: 8px; border: 1px gray solid; background-color: white; text-align: center; display: block; }
 p.note { font-family: Courier; color: black; font-size: .7em; font-style: italic; text-align: left;}
 a { text-decoration: none; }
</style>
</head>
<body onLoad="onBodyLoad()">
 <div id="wrapper">
 <p class="button"><a href="#" onclick="window.open('http://docs.phonegap.com/en/3.3.0/guide_support_index.md.html#Platform%20Support','_blank');"> IAB with location bar (showing URL)</a> 
 </p>
 <p class="note">
&lt;a href="#" onclick="window.<br> 
open('http://URL',<span style="color:red;">'_blank'</span>);"&gt;
 </p> 
 <p class="button"><a href="#" onclick="window.open('https://groups.google.com/forum/#!forum/phonegap','_blank','location=no');"> IAB without location bar</a> 
 </p>
 <p class="note">
&lt;a href="#" onclick="window.<br> 
open('http://URL','_blank',<span style="color:red;">'location=no'</span>);"&gt;
 </p> 
 <p class="button"><a href="#" onclick="window.open('http://docs.phonegap.com/en/3.2.0/cordova_inappbrowser_inappbrowser.md.html#InAppBrowser','_blank','closebuttoncaption=Return');">IAB with "Return" button text change</a> 
 </p>
 <p class="note">
&lt;a href="#" onclick="window.<br> 
open('http://URL','_blank',<br>
<span style="color:red;">'closebuttoncaption=Return'</span>);"&gt;
 </p> 
 <p class="button"><a href="#" onclick="window.open('http://iphonedevlog.wordpress.com/phonegapcordova-crib-sheet/','_system');">URL opens in system web browser (must shut down browser then re-open app)</a>
 </p>
 <p class="note">
&lt;a href="#" onclick="window.<br> 
open('http://URL',<span style="color:red;">'_system'</span>);">
 </p> 
 <p class="button"><a href="http://www.phonegap.com">Plain URL (no return to app; must remove app from memory before re-opening app)</a> 
 </p>
 <p class="note"><span style="color:red;">&lt;a href="http://URL"&gt;</span>
 </p>
 </div>
</body>
</html>

***** END ABOVE THIS LINE *****

10. Save the page. In Terminal, type the following to build the project:

cordova build ios

11. Display it in the emulator with:

cordova emulate ios

In the Simulator, click on the links to see their effect. Click on Hardware > Home to stop. Delete the icon from the screen. (If you get an error message, then download the ios-sim with the following and try the above command again:)

npm install ios-sim -g

Make sure all pages using a Cordova API reference has the following in the <head> above all other .js references, and references cordova.js as being in the root folder:

<script type="text/javascript" charset="utf-8" src="../cordova.js"></script>
<script type="text/javascript" charset="utf-8">
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
 }
</script>

Don’t copy/paste the above as is into all relevant pages; src=”cordova.js” may need to be src=”../cordova.js” or even src=”../../cordova.js” depending on the folder. You won’t see cordova.js in your www/ folder; it appears in the platforms/ios folder.

Splashscreen API

We want to show a splashscreen on the device. This is the screen that displays AFTER the launch image has displayed and BEFORE the index.html page shows. Download and configure the plugin to enable this feature. If you just want a launch image to go straight to the index.html page, ignore this plugin; you configure the launch image in Xcode.

1. In Terminal:

cordova plugin add org.apache.cordova.splashscreen

2. Open config.xml and make sure the following is above </widget> line; if not add it:

<feature name="SplashScreen">
 <param name="ios-package" value="CDVSplashScreen" />
</feature>

3. Modify the event listener in index.html with:

<script> 
function onBodyLoad() 
{ document.addEventListener("deviceready", onDeviceReady, false); } 
function onDeviceReady() 
{ navigator.splashscreen.show(); } 
setTimeout(function() { navigator.splashscreen.hide(); }, 1000); 
</script>

Note that every time a user goes to the home page of the app, this code will show the splash screen! I modified the page to keep count of the number of times it displayed; if it displayed once at startup , then it should not display again:

<script>
function onBodyLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}

function onDeviceReady() {
// Check session storage to see if splash screen already appeared
 countLaunchImage();
}
function countLaunchImage() {
/* If the value is 0 then it has already displayed. If > 0, then it hasn't yet shown and should display. */
 var name = sessionStorage.getItem("count");
 if (name > 0) { showLaunchImage(); }
}
function showLaunchImage() {
// Show splash screen
navigator.splashscreen.show();
// Set value to 0 after it appears
sessionStorage.setItem("count", "0");
// countLaunchImage() should now see a 0 and not launch next time.
}
setTimeout(function() {
 navigator.splashscreen.hide();
}, 1000);
</script>

Installing and using the debug console plugin

As part of your debugging process, you may want to output your own messages in the console when certain code has been executed. The CLI page at http://docs.phonegap.com/en/3.3.0/guide_cli_index.md.html#The%20Command-Line%20Interface tells of a debug console download.

1. Type in the terminal:

cordova plugin add org.apache.cordova.console

2. Add a console.log line in your index.html file:

function onDeviceReady() {
 navigator.splashscreen.show();
 console.log("*** Device is ready! ***");
}

3. Now let’s view the console message in Xcode. Whenever you’ll be running the app in Xcode, first type:

cordova prepare

4. Open the app in Xcode and do Product > Clean.
5. If you can’t see the console in Xcode, then View > Debug Area > Activate Console.
6. Run the app in Xcode and watch your console message appear in Xcode’s console.

Removing plugins

1. To remove a plugin, first get a list of the plugins with:

cordova plugin ls

2. Then use the rm (remove) command to remove it:

cordova plugin rm org.apache.cordova.console

Adding preferences to config.xml

PhoneGap has several ways to add default behavior preferences to your app. Copy the following to your config.xml anywhere between the <widget> tags. To read more about them and get their optional values, see the URLs I included. At this point, I’m not sure config-xml entries listed prior to 3.3.0 will work in a 3.3.0 project, so use those at your own risk. However, the app performs as intended with all these.

<!-- from 3.3.0 and 3.1.0: http://docs.phonegap.com/en/3.3.0/guide_platforms_ios_config.md.html#iOS%20Configuration
http://docs.phonegap.com/en/3.1.0/guide_platforms_ios_config.md.html#iOS%20Configuration -->
<preference name="EnableViewportScale" value="false" />
<preference name="MediaPlaybackRequiresUserAction" value="false" />
<preference name="AllowInlineMediaPlayback" value="false" />
<preference name="BackupWebStorage" value="cloud" />
<preference name="TopActivityIndicator" value="gray" />
<preference name="KeyboardDisplayRequiresUserAction" value="true" />
<preference name="SuppressesIncrementalRendering" value="false" />
<preference name="GapBetweenPages" value="0" />
<preference name="PageLength" value="0" />
<preference name="PaginationBreakingMode" value="page" />
<preference name="PaginationMode" value="unpaginated"/>
<preference name="AutoHideSplashScreen" value="true" />
<preference name="DisallowOverscroll" value="false" />
<preference name="FadeSplashScreen" value="true" />
<preference name="FadeSplashScreenDuration" value="0" />
<!-- from 2.6.0: http://shazronatadobe.wordpress.com/2013/04/08/whats-new-in-cordova-ios-2-6-0/ -->
<preference name="HideKeyboardFormAccessoryBar" value="false" />
<preference name="KeyboardShrinksView" value="false" />
<!-- from 2.2.0: http://docs.phonegap.com/en/2.2.0/guide_project-settings_ios_index.md.html -->
<preference name="ShowSplashScreenSpinner" value="true" />

 Create and Add Your Icons and Launch Images (splash screens)

PhoneGap has provided default icon and splash screen images. Replace all of the graphics in platforms/ios/TestAppIos/Resources/icons and /Resources/splash with your own if you want to support the full range of devices — keeping the same file names, file type, and file sizes. Consult https://developer.apple.com/library/ios/documentation/UserExperience/Conceptual/MobileHIG/IconMatrix.html#//apple_ref/doc/uid/TP40006556-CH27 for graphics sizes.

icon-40.png
icon-40@2x.png (80×80 pixels)
icon-50.png
icon-50@2x.png (100×100 pixels)
icon-60.png
icon-60@2x.png (120×120 pixels)
icon-72.png
icon-72@2x.png (144×144 pixels)
icon-76.png
icon-76@2x.png (152×152 pixels)
icon-small.png (29×29 pixels)
icon-small@2x.png (58×58 pixels)
icon.png (57×57 pixels)
icon@2x.png (114×114 pixels)

(If you removed any of these above files, carefully edit the listing in platforms/ios/TestAppIos/Resources/TestAppIos-Info.plist under the “Icon files” and “CFBundleIcons-ipad” headings. Open it in Xcode or a text editor.)

You can create your launch image (splash screen) from scratch in these sizes, or use a screengrab to get it (instructions for the latter appear later):

Default-568h@2x~iphone.png (640×1136 pixels)
Default-Landscape@2x~ipad.png (2048×1496 pixels)
Default-Landscape~ipad.png (1024×748 pixels)
Default-Portrait@2x~ipad.png (1536×2008 pixels)
Default-Portrait~ipad.png (768×1004 pixels)
Default@2x~iphone.png (640×960 pixels)
Default~iphone.png (320×480 pixels)

Notice the tilde-like character (~) in the filenames? When I converted those to dashes, I got a “build failed” notice with cordova -d build ios. It was a failure of checking dependencies for some of the “Default” images. I copied and pasted the character into my image launch filenames, deleted the icon from the simulator, and all went well with a new build and emulate.

In addition, create the App Store artwork (JPG or PNG) that you’ll upload to the App Store later in iTunes Connect:
1024×1024 (iPad)
512 x 512 (iPhone)

Do a cordova build and cordova emulate to check the icons. Your launch image should show, then when you do a Hardware > Home you should see your icon image.

 Test and Incorporate your Code

<script type="text/javascript" charset="utf-8" src="cordova.js"></script>
<script type="text/javascript" charset="utf-8">
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
 }
</script>

Don’t just copy/paste the above everywhere; change src=”cordova.js” to ../cordova.js or even ../../cordova.js, depending on the folder.

  • When done error-checking, drag or copy your project’s code to the TestAppIos/www folder.
  • You can run the project in a web server via CLI (although you can’t test all the plugins this way):

1. cordova prepare ios
2. cordova serve ios
3. Open a web browser like Chrome or Firefox and paste the following into the URL field:

http://localhost:8000

4. Open Firebug or Developer tools, then click on the ios link.
4. Run your code thoroughly to look for problems.
5. When finished, click on the Terminal screen to select it, then on Control + C keys to terminate the server.

I noticed that Developer Tools could not find cordova.js using the cordova serve method. That file is created in the platforms folder. So you can open platforms/ios/www/index.html in a browser to test.

Use Cordova CLI’s iOS Emulator

1. Cordova CLI offers a “run” option, which allows you to view the app in an emulator. However, before doing that, we must download another piece of software. If you do a cordova run ios now, you’ll get this error message, which tells you of two ways to correct:

Error: An error occurred while running the ios project.Error: ios-deploy was not found. Please download, build and install version 1.0.4 or greater from https://github.com/phonegap/ios-deploy into your path. Or ‘npm install -g ios-deploy’ using node.js: http://nodejs.org/

2. I will show you both ways of making this work. First, let’s use the latter method of “npm install -g ios-deploy.” But first we must set our user account as the owner of the /usr/local directory with:

sudo chown -R $USER /usr/local

(taken from: http://foohack.com/2010/08/intro-to-npm/#what_no_sudo)

3. Now we can follow the download instructions given us:

npm install -g ios-deploy

4. Now we can run the project in the emulator with:

cordova run ios

5. After you are finished checking the app, exit the iPhone Simulator with the Quit command in the upper menu bar.

6. If you ever need to uninstall this Node.js package:

npm rm ios-deploy -g

Now let’s try the GitHub option:

1. Go to GitHub and click on the Download ZIP button (at right): https://github.com/phonegap/ios-deploy I used Chrome and unzipped the file by clicking on the name in the lower left of the window.

2. View the folder “ios-deploy-master” in Finder’s Downloads folder, and drag it to its final location.

3. Change to that folder in the terminal (type cd then drag the folder to the terminal window, then hit Enter).

4. Run in terminal:

make ios-deploy prefix=/usr/bin/local

Everything is now in place to use the run ios command.

5. Now cd to the app’s folder, then build the app with:

cordova build

6. Finally:

cordova run ios

Xcode’s iOS Simulator should start and display the app. I actually got several lines reporting errors before the return of the prompt while waiting for the app to start, but then the app’s launch image displayed, then the app itself.

Quit the simulator normally through its menu bar.

Set up a Developer Account

At this point, you’ll need a Developer account to install and test the project on your device: https://developer.apple.com/ In the Member Center of the iOS Dev Center you’ll learn about Apple ID accounts, device ID, certificates, identifiers, code signing, and development and distribution provisioning profiles. You’ll learn about this in the App Distribution Guide: https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/Introduction/Introduction.html This illustrated guide will show and tell you how to get the app ready for the App Store, including troubleshooting setup problems.

Set Up in Xcode

Follow these steps after setting up a Developer account.

1. In Xcode, click on the product name in the left column. To the right of the product name, and to the left of “General” in the middle pane is a right arrow. Click on that to reveal the Project and Targets. Click on the product name under Targets. Click on General.
2. Insert the version number of the app in the Version field in this format: 1.0.0. The Build number must be updated each time an upgrade of the app is uploaded.
3. Select the Team provisioning profile for this app. Read the above doc link to learn about this.
4. Scroll down to the Deployment Target and choose the earliest iOS version your app was designed to accommodate.
5. Select which Devices your app supports: only iPhone/iPod touch, iPad, or both (Universal).
6. Under the Devices drop-down will be iPhone and iPad buttons; iPhone is highlighted in blue as the selected one. Choose all the device orientations the app supports. Under that, you may wish to hide the status bar style during app launch; if so, select it for each device.
7. Scroll down to see the listing of all the icons and launch images associated with the app.
8. If your app supports iPad, scroll up, select “iPad” and review the content below it.

Set up your device for use

1. Online, you should have created App ID, registered your device for testing, and the Development Provisioning Profile should have links to the App ID, Certificate, and Device. That provisioning profile should be downloaded and installed to your computer.
2. Plug your device into your Mac.
3. The Organizer opens. Click on Use for Development.
4. Choose the development team for provisioning.

More Xcode Settings: Target Build Settings

1. Back in Xcode, click on “Build Settings” to the right of “General.”
2. For Base SDK, make sure “Latest iOS” has been selected.
3. Under Code Signing Identity, make sure “iOS Developer” has been selected for the “Debug” and Debug/Any iOS SDK” drop-down. Later, when you create a Distribution Provisioning Profile, you’ll change the “Release” and “Release/Any iOS SDK” to reflect an “iOS Distribution” setting in the drop-down.
4. Scrolling down further, iOS Deployment Target should be the same as you indicated in the last section above, the earliest version your app will work. Do this for both middle columns.
5. Capabilities Pane — If you are integrating iCloud, Game Center, Passbook, In-App Purchase, Maps, Push Notifications, and so on, you’ll need to work in this section. Again, the online documentation link given above covers these.

Launching your app on a device

1. Connect a device that’s enabled for development to your Mac.
2. In the project navigator, choose your device from the destination Scheme pop-up menu. Remember, it’s located to the right of the Run triangle in Xcode. Xcode assumes you intend to use the selected device for development and automatically registers it for you.
4. Click the large gray Run triangle button in Xcode. Xcode installs the app on the device before launching the app. Larger app = longer wait.
5. If a prompt appears asking whether codesign can sign the app using a key in your keychain, click Always Allow.

As you use the app, keep looking at the console in Xcode for feedback.

When done, hit the square Stop button in Xcode.

Any time you make changes to the HTML etc. pages, do a cordova build in the terminal, then in Xcode do Product > Clean. Then you are ready to Run again with all updates.

Screenshots

Images must be at least 72 dpi, in the RGB color space, and the file must be .jpeg, .jpg, .tif, .tiff, or .png. Choose up to 5.

3.5-inch Retina Display Screenshots
Default@2x~iphone.png (640×960 pixels)
Default~iphone.png (320×480 pixels)

4-inch Retina Display Screenshots
Default-568h@2x~iphone.png (640×1136 pixels)

iPad Screenshots
Default-Landscape@2x~ipad.png (2048×1496 pixels)
Default-Landscape~ipad.png (1024×748 pixels)
Default-Portrait@2x~ipad.png (1536×2008 pixels)
Default-Portrait~ipad.png (768×1004 pixels)

Here are a few ways to get screengrabs of your app.

I.
1. Connect the device to your Mac.
2. On the device, configure the screen the way you want it.
3. In Xcode, choose Window > Organizer, and click Devices to display the Devices organizer.
4. In the Devices organizer, select Screenshots under the device.
5. Click New Screenshot for each screen you want.

II.
Or, to capture a screenshot on your device, you press the Lock and Home buttons simultaneously. Your screenshot is saved in the Saved Photos album in the iPhoto app.

III.
Or, use cordova emulate to show the app in the simulator, then use File > Save Screen Shot. The screen shots will be automatically saved as png to the Desktop. The 3.5-inch saved to 640×960.

IV.
If you don’t have a device, then you’ll need to do a screen grab of the pages in a browser and knit them together in an image editor.

Don’t forget image optimization/compression of all those launch images. http://imageoptim.com/

Upload a launch image (splash screen)

Launch Images for all apps:
640 x 1136 iPhone 5 and iPod touch
1536 x 2048 iPad, iPad Mini — portrait (high res.)
768 x 1024 iPad, iPad Mini — portrait (standard res.)

Follow these steps if you want to use a screen grab as a launch image.

1. Connect the device to your Mac.
2. On the device, configure the screen the way you want it.
3. In Xcode, choose Window > Organizer, and click Devices to display the Devices organizer.
4. In the Devices organizer, select Screenshots for a device or in the Library section.
5. Select an image.
6. Click “Save as Launch Image.”

Xcode has “asset catalogs” which keep all your asset images in one place. You don’t have to use it. For more information, read https://developer.apple.com/library/ios/recipes/xcode_help-image_catalog-1.0/Recipe.html

Final steps

1. 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, close all those folders in Finder and copy and paste this into Terminal:

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

Wait a while as it goes to work and the prompt returns. (This tip from: http://helpx.adobe.com/dreamweaver/kb/remove-ds-store-files-mac.html )

After that’s done, do a cordova prepare from within your project’s folder.

2. Remove or comment out all the development testing code, like console.log and alert().

3. I don’t know if this is necessary or not, but you can copy your www/config.xml contents to the config.xml file in platforms/ios/www/

4. Back up your files! 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.

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

6. Now would be a good time to create a “snapshot” in Xcode of your work at this point in time (File > Create Snapshot). A Snapshot is a copy of the project stored away. You’ll be able to revert to this version at a later date if you need to. 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. 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.

7. Fill out the Application Assets Template located here: http://wp.me/pyIb9-1o

8. You’ll need to go online to the Apple Developer site, sign in, and click on the iTunes Connect link.

9. 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, as well as the screengrabs you made.

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

Upload a binary to 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, first make sure your device is unconnected.
2. If you made any last-minute changes to the PhoneGap project, do a “cordova prepare ios” command in a terminal window.
3. In Xcode, do a Product > Clean while holding down the option key.
4. Then set Product > Destination > iOS Device.
5. Then do a Product > Archive and wait for the app to build.
6. 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. If you get errors, enter the error message into Google search and fix.
7. Until you get an email saying the app is “Ready for Sale,” you’ll get 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.

About these ads

19 thoughts on “Using PhoneGap 3.3 CLI on Mac OS X Mavericks to Build iOS Projects

    • This seems perfectly acceptable, though I haven’t tried it myself. As the article notes, the device needs to have the provisioning profiles in the device, which comes from the developer recording the device’s UDID in the Provisioning Profiles section.

  1. Great article – thanks for sharing!

    I have followed every step of this tutorial, but always end up with a missing libCordova.a (red in Xcode) which makes my app not initializing on start up.

    Any idea what causes this? In previous versions of PhoneGap/Cordova i had no problems setting up a new app. I’m getting no error messages when setting up the app, but for some reason it looks like the Cordova library is not being set up correctly

    Im running Xcode 5.0.2, and PhoneGap 3.3.0

  2. Thanks for the list of assets needed to submit; it’s getting pretty long!

    BTW, Mavericks is 10.9 (Currently 10.9.0, I think) and Mountain Lion is 10.8 (Currently 10.8.5) so either way, I think your intro needs some editing.

  3. Pingback: Fantastic Cordova 3.3 Article : Rex St John

  4. Steve an extremely insightful and helpful article you did here. You didn’t even have to do any of this, but decided to share your experience, do’s and dont’s, gotchas etc…I was struggling to get PhoneGap running until I found your article and was literally up and running in mins. The first big gotcha was how they use PhoneGap and Cordova interchangeably. Like the previous poster suggested, they should seriously replace their entire documentation with your guide.

    • I don’t create apps on an ongoing basis, so I wanted a way to find all the information I needed in one place without researching over and over at the start of a new app. My site contains my careful, step-by-step directions that help me get up and running quickly, with very little guesswork involved, no steps missed. I leave the code analysis to others! Putting it on WordPress means that I can access the notes from any computer at work or home — and you gain all the benefits as well!

      • I could tell everything you wrote was truly step by step and nothing missed, because everything you wrote worked as you wrote and described. I could not even get the first command of PhoneGap to work from their own instructions because it was supposed to be Cordova…that’s so ridiculous. Thanks Again!! I’ll be following your blog. I just started learning app development on my own a last week, so this will be a huge benefit as I progress on this.

      • That’s great! I’m now working through the Cordova APIs, so we’ll both learn as time goes on. I think I’m about to crack the mystery of coding to shoot a photo and upload it to a server directory. Stay tuned!

      • If I may add any suggestions. If would be great if you had some kind of rundown on PhoneJS as well. The first app I am trying to write is utilizing PhoneJS + Cordova. I was actually able to get PhoneJS working for the most part from their example tutorials, but I’m struggling to get the layout implementation working. I may have missed something, but something tells me their doc could also be the problem. Still trying to figure it out.

  5. Pingback: [student post] Installing Phonegap Pt. 1 – the {c}0dEd

  6. Hi Steve this is great! I am currently stuck on trying to scale for iPhone, it seems to work for iPad but I can’t get it to work on anything else – any ideas?

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