Many VoltBuilder users started with PhoneGap. It’s not tough to switch - some projects need no changes at all.

However, there are reasons you may need to make changes to your project:

  • Legacy PhoneGap Patterns: During the 10 years PhoneGap was around, many changes were made to the format and setup of PhoneGap projects. VoltBuilder picks up where PhoneGap left off - but isn’t able to handle all the stuff from PhoneGap’s early days.

  • Updates to Android and iOS requirements: In the past couple of years, both Android and iOS have added new requirements for apps on their platforms. Many of these are for improved security. You’ll need to add and change things in your project to meet those requirements.

  • Changes to Cordova: As with PhoneGap, Apache Cordova is used by VoltBuilder to compile your project. They’ve had updates to their software over the years.

Legacy PhoneGap Project Format

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

The old PhoneGap Legacy project format is not supported. See How to set up your project.

Certificates

With PhoneGap, you saved your signing certificates on PhoneGap’s server. This was a problem for a couple of reasons. Storing certs on someone else’s server is a security risk, and, as many PhoneGap users found out, when PhoneGap shut down they were locked out of their certificates.

With VoltBuilder, you keep your certificates in a folder in your project.

Resources

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

It should be at the top level of your project - not inside your www folder. Old versions of PhoneGap allowed you to keep the resources in the www folder - but this was not a good idea. It results in two copies of each resource being built into your project: one as an asset, the other in the www folder. This can add several megs to your project size.

The voltbuilder.json file

This is a new file required by VoltBuilder. It provides information VoltBuilder needs to run. Here’s where you say what kind of build you’re making (debug or release) and for what platform.

See How to set up your project.

Updates to Plugins

With the updates to Android and iOS, many plugins have been updated. You’ll want to review your plugins to make sure you’re using the current version.

Plugins you used in the past may not be available.

  • cordova-plugin-file-transfer - deprecated by its author
  • cordova-plugin-console - functionality merged into Cordova, no longer supported.

Look up your plugins on npmjs.com to get their latest status.

Obsolete use of in config.xml.

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 started using the same <config-file command 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 to get the details.

Example 1: Change this:

<config-file parent="UIStatusBarHidden" platform="ios" target="*-Info.plist">
    <true/>
</config-file>

to this:

<edit-config file="*-Info.plist" mode="merge" target="UIStatusBarHidden">
    <true/>
</edit-config>

Example 2: For example, in PhoneGap you would have had:

<config-file platform="android" parent="/manifest" mode="merge">
  <supports-screens android:anyDensity="true" android:resizeable="true"
    android:smallScreens="true" android:normalScreens="true" android:largeScreens="true"
    android:xlargeScreens="true" />
</config-file>

This should now be:

<edit-config file="AndroidManifest.xml" target="/manifest/supports-screens" mode="merge">
  <supports-screens android:anyDensity="true" android:resizeable="true" 
    android:smallScreens="true" android:normalScreens="true" android:largeScreens="true" 
    android:xlargeScreens="true" />
</edit-config>

Param attribute in config.xml

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

UIWebView

iOS has dropped support for UIWebView. If your config.xml file includes the UIWebView plugin, you’ll get an error. 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, Android and iOS now require you to ask the user for permission first. You can change the 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>

White screen on startup

If your app has a white screen on startup, you probably have an error in your code which stops it from running. To see the error, check out Remote Debugging (at the bottom).

The most common reason is Content Security Policy (CSP) errors. Both Android and iOS require apps only access URLs which are known and secure. The CSP sets those rules. Here’s a very simple CSP - put this in your index.html file:

<meta http-equiv="Content-Security-Policy" content="default-src 'self'""

(You’ll want to make this more restrictive, so that only the files you actually need are authorized)

Errors messages you might see include Cross origin requests are only supported for HTTP and XMLHttpRequest cannot load ... due to access control checks.

AndroidX

If your project uses AndroidX dependancies, AndroidX needs to be enabled. Add this to your config.xml:

<preference name="AndroidXEnabled" value="true" />

AndroidX is the replacement for the Android Support Library, which is no longer maintained. Many plugins used ASL - hopefully the plugins you use have been updated to use AndroidX.

You may also see a message like this: error: package android.support.v4.content does not exist. If you get this, you are using a plugin which has not been updated. Check npmjs.com for updates. You can also add this plugin, which allows older plugins to be used in AndroidX projects:

<plugin name="cordova-plugin-androidx-adapter">