How to set up your Capacitor project

This beta documentation - both this document and VoltBuilder are subject to change.

Project Structure

To use VoltBuilder, upload your project in the Upload screen. VoltBuilder expects your project to be organized as a zip file in Ionic Capacitor format.

This document is for Capacitor users who would like to use VoltBuilder to create Android and iOS executables. For a higher level view of how Capacitor and VoltBuilder work together, see the Overview.

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 Capacitor, with two additional items. Here’s a typical project:

Project Root
├-- android
├-- angular.json
├-- capacitor.config.json
├-- certificates (NEW!)
│   ├-- android.keystore
│   ├-- development.mobileprovision
│   ├-- distribution.mobileprovision
│   ├-- ios_development.p12
│   └-- ios_distribution.p12
├-- e2e
├-- ionic.config.json
├-- ios
├-- karma.conf.js
├-- LICENSE
├-- ngsw-config.json
├-- package-lock.json
├-- package.json
├-- README.md
├-- src
├-- tsconfig.app.json
├-- tsconfig.json
├-- tsconfig.spec.json
└-- voltbuilder.json (NEW!)

The ios and android folders are optional. If they are not supplied, VoltBuilder will generate them.

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

Dependencies

VoltBuilder uses node 16 to process jobs. You’ll need to make sure your dependencies are up to date with that.

Customizing AndroidManifest.xml and info.plist

Some plugins require modifications to the default AndroidManifest.xml or info.plist files. These files are located in the android and ios folders respectively. If you do not have these folders, VoltBuilder generates these files automatically. Therefore, if you need to modify your AndroidManifest.xml or info.plist files, you need to supply an android or ios folder.

You can add these to your project by executing this command from the command line in your project folder:

npm install @capacitor/android
- or -
npm install @capacitor/ios

You can then modify AndroidManifest.xml or info.plist, zip your project and submit it to VoltBuilder.

Icons and Splash Screens

VoltBuilder can generate your icons and splash screens from templates, so you do not have to worry about adding all the sizes to your project.

For Android, Adaptive Icons are required.

Converting from Cordova

Cordova projects can be converted to Capacitor. Here’s an in-depth article.

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

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, you can also 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.

More

Check out the Troubleshooting page.

For more, check out Support page.