How To Write A Cross-Platform Cordova 3.3 App for Android and iOS

CordovaWriting an app in Cordova 3.3 for iOS 7 and Android? This is the article for you.

This article will cover the specifics of…

  • Setting up a Cordova 3.3 development environment for iPhone, iPad and Android application creation
  • Configuring your Bash profile accordingly to interact with Cordova in a happy manner
  • Setting up and installing Cordova plugins which may be useful such as Splash Screen and In App Browser
  • Using Cordova’s CLI tools to install and manage Cordova plugins
  • How to package and distribute your Android and iOS application on TestFlight

If you are the book-reading sort, you can also check out: Apache Cordova 3 Programming (Mobile Programming).

You can also read more here:

Setting Up Your Cordova Environment

Cordova has several important command line tools which save you a lot of time. For an application which is targeting both Android and iOS, both applications will share several javascript, CSS and HTML files (as well as a config.xml) file in common. Everything else will likely be native (as in platform specific versions of plugins).

This guide assumes you have the following installed:

Without further ado…

Installing Cordova

This will involved having the Node Package Manager on your system, if you are not geared up with Node, install it here:

Now open up your terminal and run:

sudo npm install -g cordova

Now that you have Cordova installed, browse to your target folder and run:

cordova create TestApp com.YourCompany.yourapp TestApp

Note: The purpose of specifying the “com.YourCompany.yourapp” bit is important if you plan on actually signing and distributing your iOS application. If your provisioning profile is built for a certain pre-fix then you will have difficulties signing your Cordova application for distribution. 

Navigate to the newly created folder “TestApp” and add both iOS and Android platforms:

cordova add android
cordova add ios

Note about Android Paths

If Cordova is giving you grief about your Android SDK not being found or available, you may need to update your Path (make sure to update the below directory tree to point at your Android SDK root dir):

open .profile
export ANDROID_HOME=/Users/YOURUSERNAME/android-sdks/
export PATH=/Users/YOURUSERNAME/android-sdks/platform-tools:/Users/YOURUSERNAME/android-sdks/tools:$PATH

Next, run source to make it official:

source ~/.profile

There, your path should now be updated.

Cordova CLI Commands You Should Know

There are a few commands you ought to internalize before going further with Cordova.

Prepare: Copies the basic app structure into the platform-specific app folders:

cordova prepare

Build: Prepares and compiles your individual Cordova apps

cordova build

Compile: Just compiles your apps:

cordova compile

Note: Cordova automatically copies all of the web and config files in the root “www” folder into the folders for each platform (android / iOS). If you edit the files inside the /platform/ folder, you may be disappointed to see them overwritten when you build your project.

 Adding and Removing Cordova Plugins

Syntax for adding and removing plugins is simple. We will be adding the splash screen and in app browser plugins. We will also need to add the “console” plugin in order to view console log output in iOS / XCode:

cordova plugin add org.apache.cordova.splashscreen
cordova plugin add org.apache.cordova.inappbrowser
cordova plugin add org.apache.cordova.console

Removing these plugins uses the syntax:

cordova plugin remove org.apache.cordova.console

Note: You may need to add additional customization to get these plugins working properly on a per platform basis. For splash screens, for example, you will need to provide a variety of image sizes and shapes in the containing folder directories.

Image assets, Splash Screens and Icons

I strongly recommend using this tool to generate all your icons for all the various platforms: Read the Cordova guide on image assets here. You will have to produce assets in a variety of sizes and form factors for both Android and iOS. I have not yet seen any generator for producing the launch screen and splash screen assets yet unfortunately.

Running Your Project

Use “cordova run android” while you have the Genymotion simulator running to automatically launch your android app. The same command will also work for iOS e.g. “Cordova run ios.”
You can also use “cordova emulate.”

Building and Distributing Android App APKs with Cordova

To build a debug signed APK for your Android app, navigate to platforms/android and run “ant build.” Make sure, before doing this, that you have run “cordova build” prior to doing so or your Android directory may not be up to date.

Running “ant build” may also throw errors about your Android SDK if you have not corrected your Path variable as the above instructions document.

If you are planning on distributing via TestFlight, you will need to made a couple adjustments to the AndroidManifest.xml. Namely, open AndroidManifest and set “debuggable” to false. You should also use “ant release” to build the APK (it will get deposited into the platform/android/bin directory and be automatically signed with Android’s debug keystore. It will be called something like “yourapp-debug-unaligned.apk.”

Building and Distributing iOS / XCode 5 Apps with Cordova

Open your project file (platforms/ios) and build your XCode app for distribution as you would normally. It should be fairly straightforward.