Preferences

For a complete list of all of the preferences supported, refer to the Apache Cordova config.xml preferences documentation.

PhoneGap utilizes the <preference> tag to customize your application configuration. All <preference> tags in your config.xml are copied to the platform-specific configuration files, which means that any preferences supported by the Cordova framework, or by any plugins you are using, will work on PhoneGap Build.

Note: make sure you select your Cordova version when looking at the Cordova docs page.

In addition, PhoneGap Build supports some of its own custom preferences, used for things like selecting the PhoneGap version, platform sdk version targeting, and others. These custom preferences are listed below.

If you want to see more detail about what exactly these custom preferences are doing, most of them are translated using the open-source confetti library. Check out the templates directory if you want to dig in.

Multi-Platform

iOS Only

Android Only

Note: The AndroidLaunchMode preference is not currently supported on Phonegap Build. You can work around this by using the config-file element to set the value in your config.xml directly:

<config-file platform="android" parent="/manifest/application" mode="merge">
    <activity android:launchMode="singleTop" />
</config-file>

Windows Only (cli-6.1.1 and above)

Examples

Multi-Platform

**phonegap-version**: PhoneGap Build only -- the version of PhoneGap / Cordova to be used. For a list of currently supported PhoneGap versions, and a breakdown of the individual platform versions, go here.

**orientation**: Device orientation; possible values are default, landscape, or portrait. Please note that default means both landscape and portrait are enabled. If you want to use each platform's default settings (usually portrait only), remove this tag from your config.xml file.

**fullscreen**: Makes your app full screen, with values true or false. This hides the status bar at the top, and is false by default. Note: may not be supported by newer versions of iOS, but users can use the config-file element on phonegap build, and set UIViewControllerBasedStatusBarAppearance to false and UIStatusBarHidden to true.

**signing-key**: specifies which signing key to use when building. This can either be the key's id or title. If a title is specified it will use the most recently uploaded key with that title. A platform must be specified either placing this preference inside a platform tag or adding a platform attribute.

**pgb-builder-version**: With the release of cli-7.0.1 on PhoneGap Build, we did some refactoring of the build servers which may change how your app behaves. By default, this new builder is used for cli-7.0.1 and above, and the older builder is used for the older versions. However you can explicitly specify which builder to use ("1" for old builder, "2" for new builder). See this blog post for more info.

iOS Only

**target-device**: For targeting a specific device; possible values are handset, tablet, or universal. Note that this currently only applies to iOS builds; by default all builds are universal.

**prerendered-icon**: This will cause iOS to not apply its gloss to the app's icon on the user's home screen; possible values are true or false, default is false.

**detect-data-types**: Controls whether certain data types (such as phone numbers and dates) are automatically turned into links by the system. Defaults to "true" (as does the system web view). In preference to this, try using meta-tags: 
```xml
<meta name="format-detection" content="telephone=no">
<meta name="format-detection" content="email=no">
```

And use detect-data-types if meta tags don't work for you.

**exit-on-suspend**: If set to true, app will terminate when suspended, for example when home button is pressed; default is false.

**deployment-target**: This sets the IPHONEOS_DEPLOYMENT_TARGET in the build, which tranlsates to the MinimumOSVersion in the ipa Property List.

**swift-version**: This sets the SWIFT_VERSION for the build. Valid values are 2.3 or 3.0. Defaults to 3.0

Android Only

**android-versionCode**: Internal Android Version Code. Sets the version code for the application. This number is used only to determine whether one version is more recent than another, with higher numbers indicating more recent versions. Default is generated from version as MAJOR \* 10000 + MINOR \* 100 + PATCH, or 1 if version cannot be parsed.

**android-build-tool**: Specifies which android build tool to use. Values can be `gradle` or `ant`. Defaults to `gradle` for android >= 5 or `ant` for android < 5.

**android-minSdkVersion**: Minimum Android SDK version. Corresponds to the usesSdk attributes in the AndroidManifest.xml file - more details are in the Android documentation:(http://developer.android.com/guide/topics/manifest/uses-sdk-element.html). Defaults to 14 (Android >= 4.0).

**android-maxSdkVersion**: Maximum Android SDK version. Corresponds to the usesSdk attributes in the AndroidManifest.xml file - more details are in the Android documentation. Unset by default.

**android-targetSdkVersion**: Corresponds to the usesSdk attributes in the AndroidManifest.xml file -- an integer designating the API Level that the application targets. If not set, the default value equals that given to minSdkVersion. More details are in the Android documentation. Unset by default.

**android-installLocation**: Where an app can be installed - defaults to internalOnly (as the Android SDK). auto or preferExternal allow the app to be installed on an SD card - this can lead to unexpected behavior. More details available in the Android documentation.

**android-windowSoftInputMode**: How the main window of the activity interacts with the window containing the on-screen soft keyboard. More details, and possible values, available in the Android documentation.

Windows Only

**windows-arch**: Select the architecture that your build targets. Valid values are `anycpu`, `arm`, `x86`, and `x64`. Supported by cordova-windows 4.x (cli-6.1.0) and above only.

**windows-identity-name**: Set the App Idenity Name in your App Manifest, necessary for publishing to the App Store. This preference must match the App Identity Name from your *Windows Dev Center Account -> App Management -> App Identity*. Supported by cordova-windows 4.x (cli-6.1.0) and above only.

**windows-appx-target**: Which of the supported Windows platforms you wish to target. Supported values are `uap` (Windows 10 Mobile / Universal), `8.1-phone`, `8.1-win`. Supported by cordova-windows 4.x (cli-6.1.0) and above only.

Example Config.xml

<?xml version="1.0" encoding="UTF-8" ?>
<widget xmlns   = "http://www.w3.org/ns/widgets"
    xmlns:gap   = "http://phonegap.com/ns/1.0"
    id          = "com.phonegap.example"
    versionCode = "10"
    version     = "1.0.0" >

  <name>PhoneGap Example</name>
  <description>
      An example for phonegap build docs.
  </description>
  <author href="https://build.phonegap.com" email="support@phonegap.com">
      wildabeast
  </author>

  <!-- all platforms -->
  <preference name="phonegap-version" value="cli-6.0.0" />
  <preference name="orientation" value="landscape" />
  <preference name="fullscreen" value="true" />

  <!-- iOS only -->
  <preference name="target-device" value="universal" />
  <preference name="prerendered-icon" value="true" />
  <preference name="detect-data-types" value="true" />
  <preference name="exit-on-suspend" value="true" />
  <preference name="deployment-target" value="7.0" />

  <!-- Android only -->
  <preference name="android-build-tool" value="ant|gradle" />
  <preference name="android-minSdkVersion" value="10" />
  <preference name="android-maxSdkVersion" value="15" />
  <preference name="android-targetSdkVersion" value="12" />
  <preference name="android-installLocation" value="auto" />
  <preference name="android-windowSoftInputMode" value="stateVisible|adjustResize" />
</widget>

Platform Selection

By default, preferences are for all platforms. To specify a preference to be for a single platform you can place any preference inside a platform tag.

<platform name="ios" >
  <preference name="orientation" value="landscape" />
</platform>

<platform name="android" >
  <preference name="orientation" value="portrait" />
</platform>

This fragment will make the iOS app be available in landscape orientation while the android app will be in portrait mode.

Edit this page on GitHub

Looking for more help?

If you're having issues that aren't solved here, be sure to check out the following:

PhoneGap Forum

PhoneGap/Cordova community forum to use for finding info and posting issues.
Go to the forum

Stackoverflow

For PhoneGap specific questions.
Get the answers

Meetup.com

Consider finding (or starting) a local Cordova/PhoneGap meetup group.
See what's happening