How to set up your project

Project Structure

VoltBuilder expects your project to be organized as a zip file in Apache Cordova CLI project format.

The old PhoneGap Legacy project format is not supported.

How do I build the zip file?

VoltBuilder works by uploading a single zip file with everything in it. The contents are the same as for Apache Cordova, with two additional items:

Project Root
├-- config.xml
├-- certificates
│   ├-- android.keystore
│   ├-- development.mobileprovision
│   ├-- distribution.mobileprovision
│   ├-- ios_development.p12
│   └-- ios_distribution.p12
├-- merges (optional)
│   ├-- android
│   └-- ios
├-- resources (optional)
│   ├-- android
│   └-- ios
├-- scripts (optional)
├-- voltbuilder.json
└-- www (required)
    ├-- css
    ├-- images
    ├-- index.html (required)
    └-- js

config.xml

Your config.xml file is probably fine as is, except for updates to the latest plugins. It can be located at the top level of your project or in your www folder.

The plugin spec property can only be used to specify a version. Setting it to a path or URL is not supported.

If you’re on the Free Plan, you can use any of the core plugins. If you’re on the Indy or Pro Plan, nearly all plugins listed on npmjs.com will work. If you need one which is not yet supported, it will usually be added within a day. (current list)

The full list of config.xml options is in Cordova’s documentation.

Here is a minimal config.xml file:

<?xml version='1.0' encoding='utf-8'?>
<widget id="com.voltbuilder.sample" xmlns="http://www.w3.org/ns/widgets" version="1.0.0">
  <name>My Project</name>
  <description>My Project is an app.</description>
  <plugin name="cordova-plugin-device" />
  <access origin="*" />
</widget>

You can see a more complete sample config.xml here.

Notes on config.xml options

For Android <engine>, valid spec is 9.0.0 and above.
For Android <preference name="android-targetSdkVersion" valid value is 28 and above.
For Android 7 and before, certain values of id will not work.

certificates

This folder holds your certificates. If you’re only building for Android, you do not to supply mobileprovision or p12 files. If you are only making a debug build for Android, you don’t even need a keystore file.

resources

This folder holds your icon and splash screen resources. It can have any name, but is commonly called resources. The files are referenced in config.xml.

It should be at the top level of your project - not inside your www folder. (Doing so will make your project much larger than it needs to be.)

You can include all the different sizes for the icon and splash screens here, or have VoltBuilder generate them for you.

voltbuilder.json

This file has information about the build. Copy and paste this into a file named voltbuilder.json and customize it for your configuration. If you’re only building for Android, you can leave the ios fields empty.

Attributes	Description
androidAlias	Name of the alias in the android keystore file. Must be in certificates folder.
androidAliasPassword	Password for alias in the Android keystore file.
androidKeystore	A .keystore or .p12 file, generated by VoltSigner or otherwise. Required for release build.
androidKeystorePassword	Password
androidPackageType	`apk` or `bundle`. Optional, defaults to `apk`. Setting it to `bundle` makes an Android App Bundle (.aab), which is used for the Android Play Store. To download an `aab` build, omit `googlePlayKey` and make sure `GooglePlayTrack` is not `production`.
googlePlayKey	A .json file which authorizes VoltBuilder to upload jobs to the Google Play Store on your behalf. Generated by this procedure. Omit this field or set to “” to avoid uploading the the Play Store. Optional.
googlePlayTrack	The production track to release on. Usually “production”. Valid values include `production`, `internal`, `alpha`, and `beta`. If set to “production” then `androidPackageType` is always `bundle`. Leave empty to build apk - see androidPackageType. Optional.
iosDevP12	The p12 file is generated from the development certificate downloaded from Apple. Must be in the certificates folder. You can use the same p12 for multiple apps. Leave blank if you are not building for iOS.
iosDevP12Password	The password specified when exporting the .p12 file. Leave blank if you are not building for iOS.
iosDevelopment	The mobileprovision file is downloaded from Apple. It specifies which devices the app is allowed to run on. You need a separate mobileprovision file for each one of your apps. Leave blank if you are not building for iOS. Must be in certificates folder.
iosDistP12	The p12 file is generated from the distribution certificate downloaded from Apple. Use VoltSigner to generate it. Leave blank if you are not building for iOS Distribution. Must be in certificates folder.
iosDistP12Password	The password specified when exporting the .p12 file. Leave blank if you are not building for iOS Distribution.
iosDistribution	The mobileprovision file is downloaded from Apple. It specifies which devices the app is allowed to run on. You need a separate mobileprovision file for each one of your apps. Leave blank if you are not building for iOS. Must be in certificates folder.
iosPackageType	iOS Release only. Can be `ad-hoc`, `app-store` or `enterprise`
appStoreConnectAccount	Your App Store account. Required only if uploading to the App Store.
appStoreConnectAppPassword	The app password which allows VoltBuilder to upload jobs to the App Store on your behalf. Generated by this procedure. Optional.
release	Required. Can be `debug` or `release`.
verbose	Controls the amount of log output. Set to `false` to turn off verbose logging. Optional.

Here is a voltbuilder.json file with every possible item in it:

{
    "androidAlias": "key0",
    "androidAliasPassword": "mypassword",
    "androidKeystore": "certificates/android.keystore",
    "androidKeystorePassword": "mypassword",
    "androidPackageType": "apk",
    "googlePlayKey": "certificates/google.json",
    "googlePlayTrack": "production",
    "iosDevP12": "certificates/ios_development.p12",
    "iosDevP12Password": "mypassword",
    "iosDevelopment": "certificates/development.mobileprovision",
    "iosDistP12": "certificates/ios_distribution.p12",
    "iosDistP12Password": "mypassword",
    "iosDistribution": "certificates/distribution.mobileprovision",
    "iosPackageType": "app-store",
    "appStoreConnectAccount": "somebody@somecompany.com",
    "appStoreConnectAppPassword": "wxyz-ymul-hbqn-xxxx",
    "release": "debug",
    "verbose": true
}

www and index.html

www is the folder which holds all the the html, css and js for your app. It also is the place to store assets such images used by the app itself.

Your main html file should be called index.html and be in the www folder. It should have this line of code in the <head> section:

 <script src="cordova.js"></script>

Things which could go wrong

Make sure your index.html (or other file) does not include phonegap.js.
Make sure your index.html has this line in its <head> section:

<script src="cordova.js"></script>

VoltBuilder uses the latest Apache Cordova tooling. Many plugins and usages will need to be updated: users were held back by PhoneGap not being up to date. If you run into issues, that’s one of the first things to consider.
PhoneGap allows platform tags on plugins in config.xml. The latest version of Apache Cordova (and VoltBuilder) does not. If you have a plugin which is only for one platform, you’ll need to have two config.xml files and only submit the correct one for the platform you are building.
Obsolete usage of <config-file> in config.xml.: You’ll need to make some changes. Up to cli-7.0.1, PhoneGap allowed this type of clause:

<config-file platform=”ios” parent=”SomeXMLElement” mode=”replace”>
  <SomeXMLElement someAttribute=”text” >Go Skiing</SomeXMLElement>
</config-file>

Apache Cordova then started using config-file for its plugins, which conflicted with the PhoneGap implementation. PhoneGap then changed to use Cordova’s edit-config. You’ll need to change these in your config.xml. Consult the documentation for the affected controls for the details.

PhoneGap at one point had a <param attribute for plugins. Apache Cordova now calls this <variable.

iOS Specific Documentation

Uploading to Apple App Store Connect

VoltBuilder can automatically upload your app to Apple App Store Connect at the end of your build. You do not need a Mac to upload your apps.

Setting up Upload to Apple App Store Connect

UIWebView

UIWebView Deprecated. Use WKWebview. You will get this message if your config.xml file includes the UIWebView plugin. Remove it, and replace with this:

<platform name="ios">
    <preference name="WKWebViewOnly" value="true" />

    <feature name="CDVWKWebViewEngine">
        <param name="ios-package" value="CDVWKWebViewEngine" />
    </feature>

    <preference name="CordovaWebViewEngine" value="CDVWKWebViewEngine" />
</platform>

There is more information in the Apache Cordova docs. You may not actually have UIWebView in your config.xml file - but it could be used by other plugins. In that case, you’ll need to update the other plugins.

Permissions

If you are using the location, camera or photo album, your app needs to ask the user for permission first. You can change to wording: for example, to use a different language. Declare these in your config.xml file as follows:

<platform name="ios">
  <edit-config target="NSLocationAlwaysUsageDescription" file="*-Info.plist" mode="overwrite">
    <string>Allow the app to know your location</string>
  </edit-config>
  <edit-config target="NSLocationWhenInUseUsageDescription" file="*-Info.plist" mode="overwrite">
    <string>Allow the app to know your location</string>
  </edit-config>
  <edit-config target="NSCameraUsageDescription" file="*-Info.plist" mode="overwrite">
    <string>App would like to access Camera to take picture of any document that you want to upload as attachment to your message</string>
  </edit-config>
  <edit-config target="NSPhotoLibraryUsageDescription" file="*-Info.plist" mode="overwrite">
    <string>Allow the app to open Photo Library to take picture of any document that you want to upload as attachment to your message</string>
  </edit-config>
</platform>

Installing to iOS

Use the Camera app to scan the QR Code which appears after the run. Follow to prompts to install.
If you have a Mac connected vis USB, install ios-deploy and use this command:

ios-deploy --debug --bundle HelloWorld.ipa --no-wifi

If you install a debug build, you can inspect it using Safari, using the Develop menu.
To run on the iOS Simulator (Mac required), make a debug IPA with a development profile, then
1. Unzip the IPA to get the Payload folder.
2. Within the Payload folder is the app executable.
3. Drag and drop the app to an open simulator. (You might see a green add button when you drag it over the simulator)

Remote Debugging

If your app fails at runtime, the next step is to open a remote debugging session to debug your app. You’ll be able to see if there are error messages on the Console.

Here’s more info on remote debugging.

Check out the Troubleshooting page.

For more, check out Support page.

Capacitor

Cordova

Uploading to Stores

VoltBuilder API

Cordova Plugins

Ionic Appflow

PhoneGap

Sample Projects

White Papers