Project Structure

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

The 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 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
├-- res (optional)
│   ├-- android
│   └-- ios
├-- voltbuilder.json
└-- www
    ├-- css
    ├-- images
    ├-- index.html
    └-- js

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.

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 file, generated by the Certificate Wizard or otherwise. Leave blank for automatic generation by VoltBuilder.
androidKeystorePassword Password
googlePlayKey A .json file which authorizes VoltBuilder to upload jobs to the Google Play Store on your behalf. Generated by this procedure. Optional.
googlePlayTrack The production track to release on. Usually “production”. Valid values for googlePlayTrack include production, internal, alpha, and beta. 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 the Certificate Wizard 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"
itunesAccount Your Apple/iTunes account. Required only if uploading to iTunes Store.
itunesAppPassword The app password which allows VoltBuilder to upload jobs to the Apple iTunes Store on your behalf. Generated by this procedure. Optional.
platform Required. Can be "ios" or "android".
release Required. Can be "debug" or "release".

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

{
    "androidAlias": "key0",
    "androidAliasPassword": "mypassword",
    "androidKeystore": "certificates/android.keystore",
    "androidKeystorePassword": "mypassword",
    "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",
    "itunesAccount": "somebody@somecompany.com",
     "itunesAppPassword": "wxyz-ymul-hbqn-xxxx",
    "platform": "ios",
    "release": "debug"
}

config.xml

Your config.xml file is probably fine as is, except for updates to the latest plugins.

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)

You can see a sample config.xml here.

Things which could go wrong

  • Make sure your index.htm (or other file) does not include phonegap.js. Voltbuilder will include cordova.js automatically.
  • VoltBuilder uses the latest 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 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>

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. Cordova now calls this <variable.

iOS Specific Documentation

Uploading to iTunes App Connect

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

Setting up Upload to iTunes

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 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

Once you have the app installed on a device, you can open a remote debugging session to debug your app.

For Android, use Chrome Remote Debugging.

For iOS, use Safari Remote Debugging.

Another ($) option is BrowserStack