PhoneGap / Cordova CLI Builder

Description

Alpha Anywhere includes a CLI build option in the PhoneGap App Builder. Support is provided for Android builds on a Windows PC and iOS builds on a Mac.

Discussion

For Android, the build scripts will build an Android APK file, installing all requested plugins. Options are provided to install the APK file on an Android device through the USB debug cable, by scanning a QR Code or the APK can be uploaded to the cloud so that it could be shared and installed by a group of test users. For iOS apps, the builder will package up all of the required app files into a zip file and generate a Bash shell script to build the Cordova App on a Mac.

Alpha Anywhere has supported the creation of native iOS, Android and Windows Mobile Apps through the use of Adobe's PhoneGap Build service for many years. PhoneGap Build removes the requirement of installing the native mobile platform development tools on the local development machine so it is simple to build Android, iOS and Windows native mobile apps from a Windows PC.

However, there are certain plugins that are not supported at the present time through PhoneGap Build. These include any plugin that requires the use of hooks. Hooks are scripts that the Cordova CLI executes at certain points in the application build process. They allow the developer to extend the Cordova framework to better suit certain specific plugin requirements. Hooks can be used to integrate the CLI into a larger framework but they are typically used to control project creation and manipulate files in a project.

The Cordova CLI provides a command line interface for creating Cordova (PhoneGap) apps. It is supported on OSX and Windows development machines and requires the developer to install the Cordova CLI and the native app developer tools on the development machine.

If you want to build iOS apps using the Cordova CLI, you will need a Mac with the Cordova CLI and Xcode installed. You will also need an Apple Developer Account.

To develop Android apps on a Windows PC you will need to install the Java SE Development Kit (JDK), NodeJS, NPM, the Android SDK (or Android Studio) and the Cordova CLI.

Windows PC Android SDK installation and setup for deploying Cordova Apps 

  1. Install Node.js

    • a. Download the installer from https://nodejs.org/en/downloads

      Node.js needs to be added to the PATH environment variable, which is done by default.
    • b. To test the installation, open up a new command window and type node --version The version number should be displayed.

  2. Install a local Git client (if not previously installed).

  3. Install Cordova

    • a. From a command window, enter npm install -g cordova.

    • b. To verify proper installation, from the command window enter cordova -v, the installed Cordova version will be displayed.

  4. Install the Java Development Kit

  5. Install Android Studio

  6. Set the Environment Variables

    • The Cordova CLI will attempt to set these variables for you but in certain cases they need to be set manually. In Windows, the steps to set the environment variables are dependent on the installed version of Windows. You must close and open any command prompt windows after making the changes for the changes to take effect.

      1. Click on the Start Menu in the lower left corner of the desktop.

      2. In the search bar, search for Environment Variables and select Edit the System Environment Variables.

      3. In the window that appears, click the Environment Variables button.

      4. Click New... and enter the variable name and value.

      5. Set the JAVA_HOME environment variable to the location of your JDK installation.

      6. Set the ANDROID_HOME environment variable to the location of your Android SDK installation.

  7. Edit the System Path

      1. Select the Path variable and press Edit.

      2. Add the following entries:

          1. %JAVA_HOME%\bin

          2. %ANDROID_HOME%\platform-tools

          3. %ANDROID_HOME%\tools

Mac OSX Cordova Installation 

  1. Install Xcode (if not previously installed)

  2. Install Node.js

    • a. Download the installer from https://nodejs.org/en/downloads

      /usr/local/bin needs to be added to the PATH environment variable, which should done by default. To verify, enter echo $PATH from Terminal.
    • To test the installation, from Terminal, type node --version The version number should be displayed.

  3. Install a local Git client (if not previously installed).

  4. Install Cordova

    • a. From a Terminal window, enter npm install -g cordova.

    • b. To verify proper installation, from a Terminal window enter cordova -v, the installed Cordova version will be displayed.

Using the PhoneGap CLI Builder 

From the PhoneGap App Builder, it is best to start a new PhoneGap Project to make sure you are using the latest project template files. These files change from time to time based on device operating system revisions or revisions to PhoneGap. Set the App Build Target to CLI.

The options within the PhoneGap App Builder will be updated to reflect the options that are applicable to a CLI build. Make sure to specify the Application ID properly. The Application ID uses reverse domain naming notation and the CLI app folder created will use the app name specified in this string. For example, if the application id is com.alphasoftware.test1 then the CLI project folder created will be test1. Spaces are not allowed and the name will automatically be in lower case, per Android conventions.

The Cordova version that is used for the CLI build is dictated by the installed Cordova CLI version. To update the Cordova CLI version to the latest release, from a Command window, enter npm install -g cordova.

All other options are set similar to the values used for PhoneGap Build. Make sure to specify the Ajax URL as you would for PhoneGap Build.

You can select a custom app icon (remember to use a 512px x 512px image) and splash screen or launch image. If nothing is specified a default icon and splash-screen will be used.

Specify all of the required required plugins as you would for PhoneGap Build. If you are using any plugins that require you to insert a hook, you will need to build the CLI version of the app and then edit the generated source code to include the hook per the plugin documentation. You can then run the Cordova CLI Builder again and update the app.

Once all of the options have been set, select the Save / Launch PhoneGap CLI Builder button. The PhoneGap CLI Project Builder Window will appear.

The Cordova CLI Builder 

Build Specifications 

Step 1 is to specify the Target Project Build Folder. This will be the root folder for the CLI generated files. If you have specified an Android build, a sub-folder will be created with the name of the app ID. If you have specified an iOS build, an iOS files sub-folder will be created with a naming convention of appid_iOS_Files. The iOS files generated need to be transferred to a Mac to build an iOS App

Generate Android Build

Check this option to build a CLI Cordova Android project. Once checked, numerous other Android project related options will appear.

Generate iOS Build

Check this option to package up all of the app files and generate a BASH script for building a Cordova project on a Mac.

Android Build Options 

Update Existing App If checked, and an app with the same app id exists within the target project build folder, then only the /www folder will be updated. This allows you to make changes to the base component and update the app quickly. If this option is unchecked and an existing app with the same app id exists within the target project build folder, then all of the app files are deleted and a new project is built. This includes the installation of all plugins.

Update All Plugins Enable this option if the Update Existing App option is checked and you have added a new plugin to the project.

Include/Update Custom App Icon or Launch Image If you have generated and included a custom icon or a custom launch image (splash screen) then this option needs to be enabled at least once to copy the icon and launch images to the appropriate folders within the Cordova Android platform specific folders. This only needs to be done once so if you are updating an existing app, you can save time by disabling this option on subsequent updates.

Android Build Type The Build Type can be either a Debug Build or a Production Build. For development and testing, use a Debug build. When you are ready to deploy the app through either a the Google Play Store or through an Enterprise Mobile App Manager, then use a Production Build. Production Builds must be signed with the appropriate developer credentials. When you select a Production Build, the Production Android App Credentials category will be displayed.,

Production Android App Credentials 

First you should read the Android app signing requirements. See: See: https://developer.android.com/studio/publish/app-signing.html

Keystore Select the binary file that holds the set of keys.

Keystore Password Password to the keystore.

Alias The ID specifying the private key used for signing the app.

Password Password for the private key specified.

Keystore Type Default is auto-detect which is based on the file extension. You can also select the specific pkcs12 or jks extension.

Post APK Build Behavior 

The options in this category determine the actions that take place after the Android Cordova project is completed and the APK file is generated.

Show QR Code To Install APK With Scanner If you would like to install the app on an Android device, this option can be enabled to present a QR Code that can be scanned to install the APK file. The generated APK file will be copied to the development server (which must be running) and stored in a folder called apk_files/appID (the name of the app).

Install On Device Or Emulator This option allows the app to be installed on an emulator (if one has been installed and configured) or on an actual device (if USB debugging has been enabled and the Windows device drivers are working properly). Android devices can be very tricky to setup with Windows due to the numerous device drivers available and the large variety of Android devices and OS's.

Upload APK To Cloud Storage If you would like to upload the APK file to S3 Cloud storage to allow easy sharing of the APK file, enable this option. The Cloud Storage Properties category will be displayed when this option is enabled.

Cloud Storage Properties 

Method for specifying credentials You can specify the cloud storage credentials by selecting a Named Storage Connection String or Explicitly providing the credentials. If you select the Named Storage Connection String Option, the Storage Connection string property will appear, allowing you to select a previously defined storage connection string.

Storage connection string This will be displayed if the named Storage Connection String option is selected above. The drop-down will allow selection of any of the previously defined storage connection strings.

Access key Displayed when the Explicit option for specifying credentials is selected. Enter your access key.

Secret Displayed when the Explicit option for specifying credentials is selected. Enter your secret key.

Bucket Displayed when the Explicit option for specifying credentials is selected. Enter the bucket name.

iOS Builds 

Since iOS builds must be done on a Mac with Xcode installed, the Cordova CLI Builder will package all of the required application files into a zip file (all files and sub-directories contained in the PhoneGap project /www directory) and a Bash script will be generated (called build.sh) that will build the Cordova project on a Mac. All required plugins will be installed.

The files will be generated in the specified project directory with the following naming convention: appID_iOS_Files (appID will be replaced with your app ID).

Once these files have been generated, copy them to your Mac and enter bash build.sh from a Terminal window that is opened to whatever folder you would like to use for this Cordova project. The script will build the project within this folder.

The project may now be opened in Xcode by simply double clicking on the appID.xcodeproj file that is in the platforms/ios folder (again, appID will be replaced by your app id).

You can now build the project in Xcode and install, run and test on the iOS emulator or any iOS device provisioned for development on your Mac.

If you have included any new plugins you can either delete the existing Xcode project and create a new project by running the bash build.sh script again or you can install the plugins with the Cordova CLI command cordova plugins install nameOfPlugin entered from the project root folder in Terminal.

  • Updating an existing Xcode project If the Xcode project exists and you have made a change to any of the app files within Alpha Anywhere (such as modifying the base component), run the CLI builder again and copy the zip file over to your Mac and install the files into the platforms/ios/www folder, overwriting the existing files. You do not need to run the bash build.sh script a second time, unless you have included any new plugins.

For More Information 

Cordova Android Platform Guide

For more information, review the Cordova Android Platform Guide.

See: https://cordova.apache.org/docs/en/latest/guide/platforms/android/

Official Cordova Documentation

For more information on Cordova CLI development, review the official Cordova Documentation.

See: https://cordova.apache.org/docs/en/latest/guide/overview/index.html