iOS Platform Guide

This guide shows how to set up your SDK development environment to deploy Cordova apps for iOS devices such as iPhone and iPad, and how to optionally use iOS-centered command-line tools in your development workflow. You need to install the SDK tools regardless of whether you want to use these platform-centered shell tools or cross-platform Cordova CLI for development. For a comparison of the two development paths, see the Overview. For details on the CLI, see Cordova CLI Reference.

Requirements and Support

Apple® tools used for building iOS applications can only operate within the macOS environment. Xcode®, the primary tool for iOS application development, incorporates the iOS SDK (Software Development Kit). For submission to the Apple App Store℠, apps must be built using the most recent versions of these Apple tools.

You can evaluate many Cordova features by utilizing the iOS simulator integrated with the iOS SDK and Xcode. However, testing all of an app's device-specific functionalities requires an actual device before final submission to the App Store.

The table below outlines Cordova-iOS's prerequisites by version. Additionally, Xcode has its own set of system requirements and it is advisable to refer to the Minimum requirements and supported SDKs documentation for verification.

Installing the Requirements

Xcode

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 enabled for Cordova to run. From the command line, run:

$ xcode-select --install

Deployment Tools

The ios-deploy tools allow you to launch iOS apps on an iOS Device from the command-line.

Install ios-deploy via Homebrew by running:

$ brew install ios-deploy

CocoaPods

The CocoaPods tools are needed to build iOS apps. A minimum version of 1.8.0 is required but the latest release is always recommended.

To install CocoaPods, run the following from command-line terminal:

$ sudo gem install cocoapods

Project Configuration

Installing Xcode will mostly set everything needed to get started with the native side of things. You should now be able to create and build a cordova project. For more details on installing and using the CLI, refer to Create your first app guide.

Deploying to Simulator

To preview the app in the iOS simulator:

1. Open the workspace file (platforms/ios/HelloWorld.xcworkspace) from Xcode, or from the command line:

    $ open ./platforms/ios/HelloWorld.xcworkspace/
   

2. Make sure the HelloWorld project is selected in the left panel (1).

   

3. Select the intended device from the toolbar's Scheme menu, such as the iPhone XR Simulator as highlighted in (2)

4. Press the Run button (3) in the same toolbar to the left of the Scheme. That builds, deploys, and runs the application in the simulator. A separate simulator application opens to display the app:

   

   Only one simulator may run at a time, so if you want to test the app in a different simulator, you need to quit the simulator application and run a different target within Xcode.

Xcode comes bundled with simulators for the latest versions of iPhone and iPad. Older versions may be available from the Xcode → Preferences… → Components panel.

Deploying to Device

For details about various requirements to deploy to a device, refer to the Launch Your App On Devices section of Apple's About App Distribution Workflows. Briefly, you need to do the following before deploying:

1. Create a Provisioning Profile within the iOS Provisioning Portal. You can use its Development Provisioning Assistant to create and install the profile and certificate Xcode requires.

2. Verify that the Code Signing Identity setting within the Code Signing section within the build settings is set to your provisioning profile name.

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 Scheme drop-down list.

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

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

Signing an App

First, you should read through the Code Signing Support Page and the App Distribution Workflows.

Using Flags

To sign an app, you need the following parameters:

These parameters can be specified using the command line arguments above to the Cordova CLI build or run commands.

Note: You should use double -- to indicate that these are platform-specific arguments, for example:

cordova run ios --release -- --codeSignIdentity="iPhone Developer" --developmentTeam=FG35JLLMXX4A --packageType=development.

Using build.json

Alternatively, you could specify these flags in a build configuration file (default: build.json or add the --buildConfig flag to the same commands, so you can also use other file names e.g. cordova build ios --buildConfig=../customBuild.json). Here's a sample of a build configuration file:

For automatic signing, where provisioning profiles are managed automatically by Xcode (recommended):

{
    "ios": {
        "debug": {
            "codeSignIdentity": "iPhone Developer",
            "developmentTeam": "FG35JLLMXX4A",
            "packageType": "development",
            "automaticProvisioning": true
        },
        "release": {
            "codeSignIdentity": "iPhone Developer",
            "developmentTeam": "FG35JLLMXX4A",
            "packageType": "app-store",
            "automaticProvisioning": true,
            "authenticationKeyPath": "/path/to/AuthKey_D383SF739.p8",
            "authenticationKeyID": "D383SF739",
            "authenticationKeyIssuerID": "6053b7fe-68a8-4acb-89be-165aa6465141"
        }
    }
}

For manual signing, specifying the provisioning profiles by UUID:

{
    "ios": {
        "debug": {
            "codeSignIdentity": "iPhone Development",
            "provisioningProfile": "926c2bd6-8de9-4c2f-8407-1016d2d12954",
            "developmentTeam": "FG35JLLMXX4A",
            "packageType": "development"
        },
        "release": {
            "codeSignIdentity": "iPhone Distribution",
            "provisioningProfile": "70f699ad-faf1-4adE-8fea-9d84738fb306",
            "developmentTeam": "FG35JLLMXX4A",
            "packageType": "app-store"
        }
    }
}

There is also support to mix and match command line arguments and parameters in build.json. Values from the command line arguments will get precedence.

Xcode Build Flags

If you have a custom situation where you need to pass additional build flags to Xcode you would use one or more --buildFlag options to pass these flags to xcodebuild. If you use an xcodebuild built-in flag, it will show a warning.

cordova build --device --buildFlag="MYSETTING=myvalue" --buildFlag="MY_OTHER_SETTING=othervalue"
cordova run --device --buildFlag="DEVELOPMENT_TEAM=FG35JLLMXX4A" --buildFlag="-scheme TestSchemeFlag"

You can also specify a buildFlag option in build.json above (the value for the buildFlag key is a string or an array of strings).

Debugging

For details on the debugging tools that come with Xcode, see this article and this video.

Open a Project within Xcode

Cordova for iOS projects can be opened in Xcode. This can be useful if you wish to use Xcode built in debugging/profiling tools or if you are developing iOS plugins. Please note that when opening your project in Xcode, it is recommended that you do NOT edit your code in the IDE. This will edit the code in the platforms folder of your project (not www), and changes are liable to be overwritten. Instead, edit the www folder and copy over your changes by running cordova build.

Plugin developers wishing to edit their native code in the IDE should use the --link flag when adding their plugin to the project via cordova plugin add. This will link the files so that changes to the plugin files in the platforms folder are reflected in your plugin's source folder (and vice versa).

Once the ios platform is added to your project and built using cordova build, you can open it from within Xcode. Double-click to open the ${PROJECT_NAME}/platforms/ios/${PROJECT_NAME}.xcworkspace file or open Xcode from your terminal:

$ open -a Xcode platforms/ios

The screen should look like this:

Platform Centered Workflow

cordova-ios includes a number of scripts that allow the platform to be used without the full Cordova CLI. This development path may offer you a greater range of development options in certain situations than the cross-platform cordova CLI. For example, you need to use shell tools when deploying a custom Cordova WebView alongside native components. Before using this development path, you must still configure the SDK environment as described in Requirements and Support above.

For each of the scripts discussed below, refer to Cordova CLI Reference for more information on their arguments and usage. Each script has a name that matches the corresponding CLI command. For example, cordova-ios/bin/create is equivalent to cordova create.

To get started, either download the cordova-ios package from npm or Github.

To create a project using this package, run the create script in the bin folder:

$ cordova-ios/bin/create ...

To run the app, use the run script in the bin folder:

$ cordova-ios/bin/run

The created project will have a folder named cordova inside that contains scripts for the project-specific Cordova commands (e.g. run, build, etc.).

To install plugins in this project, use the Cordova Plugman Utility.

Upgrading

Refer to this article for instructions to upgrade your cordova-ios version.

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