Creating Mobile Applications with Apache Cordova

Apache Cordova is a tool which converts web applications to cross-platform mobile applications. Cordova is mostly used to create apps for Android and iOS platforms, however, it's also possible to develop Windows, macOS, and Linux applications. The tool is completely free, easy-to-use and allows for advanced customizations with Puzzles or JavaScript (if you need it).

To see Cordova in action, download the Farmer's Journey game from App Store or Google Play.

Preliminary Considerations

Before you start working with Cordova, make sure you have the following:

Hardware. You can develop Android apps on any computer running Windows, macOS, or Linux, while developing apps for Apple devices will require a decent Mac system.
Basic Windows/macOS/Linux console (aka command prompt) skills. If you don't, please seek the internet for beginner-level tutorials.
Time. By following this guide you can build your first app really quick, however it may take hours or days, before you get your developer account approved and your app published in App Store / Google Play.
Money. Creating and running applications on your own devices is completely free. However, to get published in Google Play you'll need $25 (one-time payment), while for App Store, you'll need $99 (paid annually).

The good part, you don't need to be an Android or iOS developer to create apps for these platforms. Once you have your development system up and running, creating mobile versions of your Verge3D apps would be really easy!

Another method of distributing your apps across various mobile and desktop platforms is by using the installable progressive web apps.

Getting Started with Apache Cordova

To work with Cordova, you'll need the npm utility which is part of the Node.js runtime. You can install it by following these instructions.

For Linux you better get npm via the package manager. See here for details.

Once npm installed, Cordova binaries can be installed with the following command.

On macOS/Linux:

sudo npm install -g cordova

On Windows:

npm install -g cordova

Instead of installing Cordova globally, you can use the npx utility, e.g.

npx cordova platform add android

Creating Application Template

You can create your mobile app manually or with Cordova command-line utility. However, to simplify things up, we integrated a Cordova template builder right in the App Manager.

By using it you can create a Cordova app template right from your Verge3D app.

Once your template is ready, download it and then unpack the zip archive to some directory.

Creating Android App

Go to some directory where your Cordova app template located then add the Android platform:

cordova platform add android

Now the hardest part. To be able to build and test your app in the Android emulator or real devices, you're gonna need to install and configure additional software.

First, you need to install Android Studio, get it from here.

Once Android Studio is installed, you need to specify path to it in the ANDROID_HOME environment variable. On Windows you'll also need to set the JAVA_HOME variable with the path to the Java directory.

See here on how to setup these variables.

The last thing you will require is the Gradle build tool. See here for instructions.

To check if you satisfy the requirements for building, execute the following command in your apps directory:

cordova requirements

If some dependency is missing, this command will say so, e.g.


    Requirements check results for android:
    Java JDK: installed 1.8.0
    Android SDK: installed true
    Android target: not installed
    Please install the Android SDK Platform "platforms;android-30"
    Gradle: installed /home/alex/Downloads/gradle-6.3/bin/gradle
    Some of requirements check failed

Here it says you need to install (or updgrade) the Android SDK platform in the Android Studio:

If you are good to go, the output will look like that:


    Requirements check results for android:
    Java JDK: installed 1.8.0
    Android SDK: installed true
    Android target: installed android-30
    Gradle: installed /home/alex/Downloads/gradle-6.3/bin/gradle

To build your app, exec:

cordova build android

To run it in the Android emulator, make sure you have a virtual device added to Device Manager in the Android Studio (it should match the version of the SDK platform installed before):

then exec this command:

cordova emulate android

To run your app on the real phone connected to your system (e.g via USB cable) run:

cordova run android

Creating iOS App

Go to some directory where your Cordova app template located then add the iOS platform:

cordova platform add ios

Now the hardest part. To be able to build and test your app in the iOS emulator or real devices, you're gonna need to install and configure additional software.

First, you need to install XCode, get it from from the Mac App Store.

Then install the Homebrew package manager:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After that you'll need ios-deploy tools.

brew install ios-deploy

Then you're gonna need CocoaPods dependency manager:

sudo gem install cocoapods

To check if you satisfy the requirements for building, execute the following command in your apps directory:

cordova requirements

It's time to run your app, exec:

cordova emulate ios

to build and run it in the iOS emulator.

To run your app on the real phone connected to your system exec:

cordova run ios

To run on a real device your app must be signed via XCode. See here for instructions.

Beautifying Things

Modifying App Icon

To be able to generate proper icon for your mobile app, first assign the 512x512 image in the application settings:

Every time you create a Cordova template, this image will be used as a source to create a set of icons, required by Android/iOS. The actual resizing is performed by the ImageMagick utility.

For Windows installations of Verge3D, ImageMagick is already included in your distribution, so the conversion will happen automatically.

For macOS install ImageMagick with Homebrew:

brew install imagemagick

For Ubuntu Linux, use the APT package manager:

sudo apt install imagemagick

Cordova-Specific Events

There are 3 Cordova-specific events available via JavaScript or Puzzles which you can use to make your apps more mobile-friendly:

deviceready — triggered when your app is fully initialized. You can also use it to detect when your app is running on Cordova.
pause — triggered when you app goes to the background or got switched by another app. Use it to pause your app rendering / sound playback / videos etc.
resume — triggered when you app becomes active. This event is the opposite of the pause.

Make sure you register these events on the document element. Also, use the in parent doc option in case if your app runs in the iframe (see more info about this setup here).

Creating Native UI Dialogs

Use the cordova-plugin-dialogs plugin.

More Features

You can create full-featured app with access to camera, battery info, device file system, geolocation etc. See the appropriate plugin in the Cordova documentation.

Publishing your App

See here for instructions.

Got Questions?

Feel free to ask on the forums!