Cordova

From NSB App Studio
Jump to navigation Jump to search

Apache Cordova is a free and open source tool for make iOS and Android apps. First step is to create the project using a development tool such as AppStudio. The project is then compiled into .ipa and .apk files by Cordova.

Apache Cordova (formerly PhoneGap) is a mobile application development framework originally created by Nitobi. Adobe Systems purchased Nitobi in 2011, rebranded it as PhoneGap, and later released the open source version of the software as Apache Cordova.

PhoneGap Build, a web service which uses Cordova, is still available. It's much easier to use than Cordova itself. Here are instructions for Android and iOS for AppStudio users.

Cordova is recommended for users

  • Who want to build locally on their own system.
  • Who have requirements that PhoneGap Build cannot satisfy.
  • Who have the technical expertise to install the toolchain.

Is a Mac required?

If you're only going to make Android apps, no Mac is needed.

There are several steps to producing an iOS app which can only be done on a Mac:

  • Getting a signing certificate requires the macOS Keychain app
  • Signing the .ipa file requires XCode
  • Setting the .mobileprovision file requires XCode
  • Uploading the app to the iTunes Store requires XCode or Transporter.

As of the last update to this page, the minimum requirement for a Mac is that it runs macOS Catalina (10.15.4). This is required for XCode 11.4, which contains the libraries to create iOS 13.4 apps. Any Mac which can run Catalina should have sufficient speed, memory and storage. Keep in mind that XCode needs 17 gigs of storage.

It's possible to use a service such as MacInCloud instead of an actual Mac.

Android apps can be made on both Windows and MacOS.

Prerequisites

Download and install Node. (This also installs npm.) https://nodejs.org/en/download/

Cordova Android Requirements (not needed if you are only doing iOS): (About 7 gigs on Windows, 8 gigs on Mac) https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html#installing-the-requirements

Installing the Android toolchain can be tricky. It's fragile: all the environmental variables and paths must be correctly set up. There doesn't seem to be an easy way to check and fix problems.

macOS/iOS

https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html#installing-the-requirements

  • mobileprovision file (from Apple Developer site)
  • signing certificate (from Apple Developer site)

How to make an app using Cordova

  1. Install the Prerequisites.
  2. Make your app as usual with AppStudio.
  3. In your Project Properties, set the 'Cordova command' in the PhoneGap and Cordova section. 'Emulate ios' and 'emulate android' are good for testing.
  4. If you have an Android device connected by a USB cable, use 'run android --debug'. It's faster than the emulator.
  5. From the Run menu, select Make Native App with Cordova.
  6. The app should load and run on the emulator or device.
  7. To run on an iOS device, it will need to be signed.

Signing Android Apps

Unsigned apps will run fine in the emulator and on devices. They are especially useful for debugging - you can use Chrome to Remote Debug your app.

If you want to submit your app to the Google Play or Android store, you will need to sign it using a keystore file. AppStudio generates that file automatically from your build.json file. You'll need to supply the correct values in that.

Signing iOS Apps

Both Debug and Release builds need to be signed to run on iOS devices.

The debug and release builds need separate codeSignIdentity and provisioningProfile settings, downloaded from Apple.

You can also leave these values unmodified in AppStudio and supply the information to Xcode instead.

Complete information on signing iOS apps with Cordoba is here:
https://cordova.apache.org/docs/en/latest/guide/platforms/ios/#signing-an-app

Cordova Commands

Command Windows macOS
emulate ios Nothing Opens app in iOS Simulator.
emulate android Opens app in Android Emulator Creates debug apk and opens in Android Emulator
run ios --debug Nothing Creates debug ipa and opens app on Simulator or USB connected device. provisioningProfile and developmentTeam must be supplied in build.json.
run android --debug Opens app on USB connected device Creates debug apk and opens on USB connected device
run ios --release Nothing Creates signed ipa and opens app on Simulator or USB connected device. codeSignIdentity, provisioningProfile and developmentTeam must be supplied in build.json.
run android --release Creates signed .apk Creates signed .apk
Create cordova directory only Creates all files, but does not run a Cordova command. Creates all files, but does not run a Cordova command.
Create and open in Xcode Nothing Creates all files, then launches in XCode.

The full list of command options is in the Cordova documentation.

You can also enter the commands manually. Open a terminal window in {your project}/cordova, and enter one of the commands above or others:

$ cordova platform
Installed platforms:
  android 8.1.0
  ios 5.1.1
Available platforms: 
  browser ^6.0.0
  electron ^1.0.0
  osx ^5.0.0
  windows ^7.0.0

Cordova build.json

This file contains parameters for signing apps. It's in Project Properties, in the 'PhoneGap and Cordova' section. When you run Cordova, it gets copied into the cordova folder and instructs Cordova how to sign the app.

Android

Here's the default Android section in build.json. Only a 'release' section is provided - no debug section is provided since the defaults will work fine in almost all cases.

  "android": {
    "release": {
      "keystore": "../certificates/android.keystore",
      "storePassword": "mypassword",
      "alias": "key0",
      "password": "mypassword",
      "keystoreType": ""
    }
  }

For more options, see the Cordova documentation:
https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html#signing-an-app

iOS

Here's the default iOS section in build.json. Both a debug and release section are required.

  "ios": {
    "debug": {
      "codeSignIdentity": "iPhone Developer",
      "provisioningProfile": "8b3aafc5-e001-4bbe-ac6f-bc6df8ab2534",
      "developmentTeam": "J36MEHTA7K",
      "packageType": "development",
      "automaticProvisioning": true,
      "buildFlag": [
        "EMBEDDED_CONTENT_CONTAINS_SWIFT = YES",
        "ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES=NO",
        "LD_RUNPATH_SEARCH_PATHS = \"@executable_path/Frameworks\""
      ]
    },
    "release": {
      "codeSignIdentity": "iPhone Developer",
      "developmentTeam": "J36MEHTA7K",
      "packageType": "app-store",
      "automaticProvisioning": true,
      "buildFlag": [
        "EMBEDDED_CONTENT_CONTAINS_SWIFT = YES",
        "ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES=NO",
        "LD_RUNPATH_SEARCH_PATHS = \"@executable_path/Frameworks\""
      ]
    }

These are the fields you need to worry about:

  • codeSignIdentity is the name of the certificate downloaded from Apple. It appears in the macOS Keystore app. Get your certificate from Apple's Developer site in the 'Certificates, Identifiers and Profiles' sections, under 'Certificates'.
  • provisioningProfile is the UUID of the mobileprovision file. Download it from Apple and double click on it. Xcode will update your system so XCode can find it. Get the UUID by opening the mobileprovision file itself in an editor and finding UUID. Get your mobileprovision from Apple's Developer site in the 'Certificates, Identifiers and Profiles' sections, under 'Profiles'. You will also need to set up devices in 'Devices' and create an Identifier in 'Identifiers'. The App ID must match the id in config.xml.

For more options, see the Cordova documentation:
https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html#signing-an-app