phonegap iOS Platform Guide

his guide shows how to set up your SDK development environment todeploy Cordova apps for iOS devices such as iPhone and iPad. See thefollowing for more detailed platform-specific information:

• iOS Configuration
• Upgrading iOS
• iOS WebViews
• iOS Plugins
• iOS Command-line Tools

The command-line tools above refer to versions prior to Cordova 3.0.See The Command-Line Interface for information about thecurrent interface.

Requirements and Support

Apple® tools required to build iOS applications run only on the OS Xoperating system on Intel-based Macs. Xcode® 4.5 (the minimum requiredversion) runs only on OS X version 10.7 (Lion) or greater, andincludes the iOS 6 SDK (Software Development Kit). To submit apps tothe Apple App Store℠ requires the latest versions of the Apple tools.

You can test many of the Cordova features using the iOS emulatorinstalled with the iOS SDK and Xcode, but you need an actual device tofully test all of the app's device features before submitting to theApp Store. The device must have at least iOS 5.x installed, theminimum iOS version supported as of Cordova 2.3. Supporting devicesinclude all iPad® models, iPhone® 3GS and above, and iPod® Touch 3rdGeneration or later. To install apps onto a device, you must also be amember of Apple'siOS Developer Program,which costs $99 per year. This guide shows how to deploy apps to theiOS emulator, for which you don't need to register with the developerprogram.

Install the SDK

There are two ways to download Xcode:

• from the App Store,available by searching for "Xcode" in the App Store application.

• from Apple Developer Downloads,which requires registration as an Apple Developer.

Once Xcode is installed, several command-line tools need to be enabledfor Cordova to run. From the Xcode menu, select Preferences,then the Downloads tab. From the Components panel, press theInstall button next to the Command Line Tools listing.

Open a Project in the SDK

Use the cordova utility to set up a new project, as described in TheCordova The Command-Line Interface. For example, in a source-code directory:

    $ cordova create hello com.example.hello "HelloWorld"
    $ cd hello
    $ cordova platform add ios
    $ cordova prepare              # or "cordova build"

Once created, you can open it from within Xcode. Double-click to openthe hello/platforms/ios/hello.xcodeproj file. The screen shouldlook like this:

Deploy to Emulator

To preview the app in the iOS emulator:

1. Make sure the .xcodeproj file is selected in the left panel.

2. Select the hello app in the panel immediately to the right.

3. Select the intended device from the toolbar's Scheme menu, suchas the iPhone 6.0 Simulator as highlighted here:

   

4. Press the Run button that appears in the same toolbar to theleft of the Scheme. That builds, deploys and runs theapplication in the emulator. A separate emulator application opensto display the app:

   

   Only one emulator may run at a time, so if you want to test the appin a different emulator, you need to quit the emulator applicationand run a different target within Xcode.

Xcode comes bundled with emulators for the latest versions of iPhoneand iPad. Older versions may be available from the Xcode →Preferences → Downloads → Components panel.

Deploy to Device

For details about various requirements to deploy to a device, referto the Configuring Development and Distribution Assets section ofApple'sTools Workflow Guide for iOS.Briefly, you need to do the following before deploying:

1. Join the Apple iOS Developer Program.

2. Create a Provisioning Profile within theiOS Provisioning Portal.You can use its Development Provisioning Assistant to create andinstall the profile and certificate Xcode requires.

3. Verify that the Code Signing section's Code Signing Identitywithin the project settings is set to your provisioning profilename.

To deploy to the device:

1. Use the USB cable to plug the device into your Mac.

2. Select the name of the project in the Xcode window's Schemedrop-down list.

3. Select your device from the Device drop-down list. If it isplugged in via USB but still does not appear, press theOrganizer button to resolve any errors.

4. Press the Run button to build, deploy and run the applicationon your device.

Common Problems

Deprecation Warnings: When an application programming interface(API) is changed or replaced by another API, it is marked asdeprecated. The API still works in the near term, but is eventuallyremoved. Some of these deprecated interfaces are reflected in ApacheCordova, and Xcode issues warnings about them when you build anddeploy an application.

Xcode's warning about the invokeString method concerns functionalitythat launches an app from a custom URL. While the mechanism to loadfrom a custom URL has changed, this code is still present to providebackwards functionality for apps created with older versions ofCordova. The sample app does not use this functionality, so thesewarnings can be ignored. To prevent these warnings from appearing,remove the code that references the deprecated invokeString API:

• Edit the Classes/MainViewController.m file, surround the followingblock of code with /* and */ comments as shown below, then typeCommand-s to save the file:

  (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];
  }
  

• Edit the Classes/AppViewDelegate.m file, comment out the followingline by inserting a double slash as shown below, then typeCommand-s to save the file:

  //self.viewController.invokeString = invokeString;
  

• Press Command-b to rebuild the project and eliminate the warnings.

Missing Headers: Compilation errors relating to missing headersresult from problems with the build location, and can be fixed via Xcode preferences:

1. Select Xcode → Preferences → Locations.

2. In the Derived Data section, press the Advanced button andselect Unique as the Build Location as shown here:

   

This is the default setting for a new Xcode install, but it may be setdifferently following an upgrade from an older version of Xcode.

For further information, consult Apple's documentation:

• Start Developing iOS Apps Today provides a quick overview of steps for developing iOS Apps.

• Member Center home pageprovides links to several iOS technical resources includingtechnical resources, the provisioning portal, distribution guidesand community forums.

• Tools Workflow Guide for iOS

• Xcode 4 User Guide

• Session Videos fromthe Apple World Wide Developer Conference 2012 (WWDC2012)

• The xcode-select command,which helps specify the correct version of Xcode if more than one is installed.

(Mac®, OS X®, Apple®, Xcode®, App Store℠, iPad®, iPhone®, iPod® and Finder® are Trademarks of Apple Inc.)