Cordova Setup

Installing Cordova

To be able to use the Cordova framework, we just need to install it globally on our computer. The command is the same for Windows and MacOS and Linux.

From the Terminal / Command Prompt:

npm install -g cordova

If you ever need to update Cordova to a newer version we use:

npm update -g cordova

You can see all the cordova commands here (opens new window)

Full Cordova reference documentation (opens new window)

Cordova CLI commands reference (opens new window)

Creating a Cordova Project

Once you have the Cordova framework installed via npm, then we can start to create Cordova projects. We use the cordova create command to start a project. It takes three arguments.

cordova create folderName com.algonquin.username.appname "App Name"

The first argument is the name of the project folder to be created. You cannot create the folder before running the cordova create command.

The second argument is the reverse-domain-name style package name for your app. This is the unique name that the mobile devices use to identify your app. The first two parts are typically the company domain. The third will be your username. The fourth is a name for the app.

The third argument is the display name for the App. If you have a space in the name, then you need to wrap it in quotation marks.

Cordova Project Folder Structure

A default Cordova project has several files and folders.

Top level folders - plugins, platforms, www, res, and merges. The www folder will contain all our HTML, CSS, and JS files. The merges folder will be used for platform specific styles and scripts. The res folder will hold the icons and splashscreen images.

Top level files - config.xml, package.json. We will add a build.json file.

Adding Plugins

We can search for available plugins through the Cordova plugin website (opens new window).

We add and remove plugins using the cordova plugin command. add is used with the plugin name to add a plugin to your project. list will tell you all the plugins that currently exist in your project. remove will remove a specific plugin. search will launch the Cordova plugin website and run a search for the keyword.

cordova plugin add cordova-plugin-camera
cordova plugin list
cordova plugin remove cordova-plugin-camera
cordova plugin search bluetooth

Adding Platforms

Adding the iOS or Android platform to the project works the same way as the plugins.

cordova platform add ios
cordova platform remove android

Device Plugin

Cordova has a core plugin called the Device plugin. This plugin can be used to determine information about the device that is running the app.

App Versioning

Cordova projects have two settings files package.json and config.xml. Adobe tried to migrate from the config.xml file to the package.json file but failed to get enough support from the plugin creators. So, the config.xml file is the one that we use for managing permissions and version information about the project.

Below is a sample of a config.xml file. The root tag is the widget element. It has an attribute id which is the package name for the app that was used with the cordova create command. The version attribute is used to manage the version number for the app.

The <name> element is the display name for the app.

The <content> element is the default HTML file that will be loaded first.

<?xml version='1.0' encoding='utf-8'?>
<widget id="com.example.griffis.myapp"
        version="1.0.5"
        xmlns="http://www.w3.org/ns/widgets"
        xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:cdv="http://cordova.apache.org/ns/1.0">
  <name>My App</name>
  <description>
      A sample Apache Cordova application.
  </description>
  <author email="abcd0001@algonquinlive.com" href="http://cordova.io">
      Sample Name
  </author>
  <content src="index.html" />
  <plugin name="cordova-plugin-whitelist" spec="1" />
  <access origin="*" />
  <allow-intent href="http://*/*" />
  <allow-intent href="https://*/*" />
  <allow-intent href="tel:*" />
  <allow-intent href="sms:*" />
  <allow-intent href="mailto:*" />
  <allow-intent href="geo:*" />
  <!--
    plus platform section
    plus plugin entries
  -->
</widget>

DeviceReady Event

When we build SPAs, we use the DOMContentLoaded event to know when the interface is ready for us to work with. For Cordova apps we need to know not just when the DOM is ready but also when the plugins are loaded.

Cordova has an event called deviceready. This event gets fired when both the plugins are loaded and the DOMContentLoaded event has fired.

XCode

We need to have XCode installed to be able to build, simulate, or launch iOS apps. Since that is what we are doing with Cordova, it means that we need to have XCode installed from the App Store. We need to have the latest version of XCode installed.

xcode-select

To be able to run XCode commands from the command line, like when you run cordova commands for building or running an app, we need to install the XCode CLI tools. We need to run this command in the Terminal.

xcode-select --install

Updates for iOS

To add additional versions of iOS or addition devices for the Simulator, we need to download them through XCode.

Xcode > Preferences > Components

Select or deselect each of the versions of iOS, WatchOS, and TVOS that you want to use in the simulator.

ios-sim

To be able to launch the iOS simulator, or see which simulator versions are currently available, we will install the ios-sim program with npm.

npm install -g ios-sim

Once it is installed, then we can use the ios-sim program to get a list of the available simulators.

ios-sim showdevicetypes

When we launch our Cordova app from the command line, if we are targeting the simulator then Cordova will use ios-sim.

Learn more about ios-sim (opens new window)

Simulator

We can launch the iOS Simulator from XCode or from the command line using ios-sim.

ios-sim start --devicetypeid=iPhone-X, 12.1

This command will launch the simulator with that specific configuration of device and OS.

You can get the available devicetypeid values using the ios-sim showdevictypes command.

Set up for iOS Deployment from Cordova

NPM has a tool for deploying to an iOS device from the command line. This will let us launch our apps from the command line into the iOS device. From the terminal run this command:

npm install -g ios-deploy --unsafe-perm=true --allow-root

To avoid issues with NPM that require you to use sudo, we recommend that you change your default NPM global install location to ~/.npm_packages. See the NPM page for the instructions on this.

iOS Build Settings

There are certain settings that we want to specify each time we compile and launch our app. With Cordova we can create a build.json file to hold these settings without having to add them to our build or run commands every time we use them.

Simulating & Launching Apps

When using Cordova, we need to be able to convert our HTML-based app into an actual iOS or Android app.

To compile / build a Cordova app we use the cordova build command plus the platform we want to target.

cordova build ios
cordova build android

To build and launch the app in a simulator or emulator:

cordova emulate ios --target=iPhone-X, iOS12.1

The list of targets is available through ios-sim showdevicetypes.

To build and run the app on a connected device:

cordova run ios

If there is only one connected device then it will be used. If there are multiple choices then we can add the --target= flag.

Adding your own iOS Devices

If you want, we can add your own iOS devices to our account as an approved device too.

You will need to plugin your device to your MacBook, on the OSX side. Then open iTunes and select the device from the available items. You may be asked to backup or update your device. It is up to you whether you do that.

You should see information about the device being displayed that will include a SERIAL number. If you CLICK on the serial number it will change the display to reveal other bits of information about the device. What we need is the UUID. Copy and Paste this number into an email for Steve - griffis@algonquincollege.com .

In your email include the type of device that it is. Eg: iPhone 8 plus.

You will be notified when a new provision profile that includes this device has been created.

iOS Developer Certificates

This is here as a reminder and reference. You should have already done this in first semester.

You will need to create a signed certificate that will create a connection between your Apple Developer account, our College account, and your MacBook Pro with your copy of XCode. You can follow the instructions on the developer.apple.com (opens new window) website for creating the certificate signing request CSR on your computer. This CSR will be uploaded to the website and then you will be given a certificate to download and install in Keychain Access.

To compile and install an iOS app you will need to do the following things:

1. Register as an Apple Developer here https://developer.apple.com/account/ (opens new window)
2. Go to the page for Certificates and create a Developer certificate. This will require you using the Keychain Assistant program on your Macbook Pro. Instructions are on the page that you visit to create the certificate. You will be uploading a CSR (certificate signing request) that you generate. Watch the video below for more details on this.
3. Download and install the Certificate that you made. XCode will need this certificate.
4. Download and install a provisioning certificate. The Provisioning certificate is something that combines a list of approved users and a list of approved devices for a developer account. This certificate is used to allow the building and installing of apps on devices.

Every time a new developer certificate is created or a device is added to our Apple account then an account administrator (your instructor) has to create a new updated provisioning certificate.

Each student should only have ONE certificate. We have a limited number that we can create. If you create a new one, please let us know so that we can remove the old one.

Provisioning Profiles

Once you have created and uploaded your certificate then Steve will have to create a mobile provisioning profile file. This is a file that stores a list of approved certificates and approved devices that you can use to test your apps.

New provisioning profiles get created from time to time, as new devices are added, new certificates are created, or people or devices are removed from the account. You can always download and run a new provisioning profile at any time. Just grab the latest one that has MAD&D in the name.