FreeSoft
English EN
PhoneGap archiveDocumentation

Documentation

PhoneGap Build config.xml reference

The recovered configuration reference, including preferences, access rules, icons and splash screens.

Restored original referencesHistorical reference
Archive note. Historical reference. PhoneGap tools and the former Adobe services are no longer maintained as described in the original material. Recovered text and newly written explanations are identified below; consult current platform documentation for active development.

About this reference

This page combines the recovered PhoneGap Build configuration documents: the top-level file, widget settings, access elements, preferences, icons and splash screens. These describe the retired Build service. Build-specific settings are not automatically equivalent to current Cordova configuration.

Original configuration reference · 0-index

PhoneGap and PhoneGap Build are built upon the Apache Cordova Project. Spend some time at docs.cordova.io to get more familiar with how PhoneGap and Cordova applications are configured.

PhoneGap applications are configured using a config.xml file. This should be at the root of your application.

The config.xml file follows the W3C widget specification. It allows developers to easily specify metadata about their applications. You can see a sample config.xml with our PhoneGap Start application.

We're continually adding features to our config.xml support to give PhoneGap Build developers more power to customize their apps. If there are any specific features you'd like to see support for, please let us know.

  1. Essential Properties
  2. Example config.xml

Essential Properties

<widget>

The widget element must be the root of your XML document - it lets us know that you are following the W3C specification. When using PhoneGap Build, ensure you have the following attributes set on your widget element. It supports the following attributes:

  • id: the unique identifier for your application. To support all supported platforms, this must be reverse-domain name style (e.g. com.yourcompany.yourapp)
  • version: for best results, use a major/minor/patch style version, with three numbers, such as 0.0.1
  • versionCode: (optional) when building for Android, you can set the versionCode by specifying it in your config.xml. For more information on Android's versionCode attribute, see the Android documentation.
<name>

The name of the application.

<description>

A description for your application.

<author>

The author of the application, either a company or individual (required for Windows 10 builds).

<platform>

You can have zero or more of these elements present in your config.xml. Set the name attribute to one of ios, android, or windows. If you specify none, all platforms will be built. Example usage:

<platform name="ios" />
<platform name="android" />
<platform name="winphone" />

All of the above fields are standard Cordova config.xml tags. For more detailed info about the above elements, and all the others available, see the Cordova config.xml documentation. Most of these will work on PhoneGap Build, but if you face issues with any specific tags, let us know.

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

<!-- versionCode is optional and Android only -->

  <name>PhoneGap Example</name>

  <description>
      An example for phonegap build docs.
  </description>

  <author href="https://build.phonegap.com" email="support@phonegap.com">
      Hardeep Shoker
  </author>

</widget>
Original configuration reference · config-file-element
As of cli-7.0.1 on PhoneGap Build (and as long as you're using the new builder), modifying manifests is handled by Cordova with the `edit-config` element. Check out the [cordova edit-config docs](https://cordova.apache.org/docs/en/latest/config_ref/index.html#edit-config) for usage details. Otherwise if you're using cli-6.5.0 and below (and/or the old builder), use the config-file element as documented below.

PhoneGap Build aims to take away the pains of configuring SDKs and compiling native applications so you can focus on writing great code. As part of this, we obfuscate management of the platform configuration files -- namely your Android Manifest (AndroidManifest.xml) and your iOS Property List (Info.plist). We configure these files based on the preferences you specify in your app's config.xml file. However, the specifications of these xml files are constantly changing, and it would be impossible for us to expose all of the possible configurations through the use of simple preferences. So for those cases that we haven't covered, you can contribute xml directly to your Android Manifest and iOS Propertly List files, via the config-file element (beta feature).

The config-file spec is based on the config-file element in PhoneGap's plugin.xml spec, though has a slightly different implementation.

<config-file platform="ios" parent="SomeXMLElement" mode="replace">
  <SomeXMLElement someAttribute="text" >Go Skiing</SomeXMLElement>
</config-file>
  • platform: currently supported values are ios (Info.plist) and android (AndroidManifest.xml)
  • parent: on iOS this will be the plist key you wish to modify; on android this will be an xpath string resolving to the parent of the xml element inside of which your xml will be injected
  • mode: add, replace, merge, or delete -- how to modify the parent element. add will append to the inner xml of the parent, replace will completely overwrite the parent's inner xml with your declaration, merge will attempt to find elments of the same name and merge their attributes, and delete will search for elements matching the specifed name and attributes and delete them.

iOS

As an example on iOS, if you wish to restrict the orientation of an application, you can use the orientation preference in config.xml, where

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

will translate to the following in your iOS Property List:

<key>UISupportedInterfaceOrientations</key>
<array>
  <string>UIInterfaceOrientationPortrait</string>
  <string>UIInterfaceOrientationPortraitUpsideDown</string>
</array>

But suppose you don't want to allow PortraitUpsideDown? So specify your own xml for this property instead:

<config-file platform="ios" parent="UISupportedInterfaceOrientations" mode="replace">
  <array>
    <string>UIInterfaceOrientationLandscapeOmg</string>
  </array>
</config-file>

To check and debug the resulting Property List file, simply rename your .ipa file to .zip, unzip it, and examine the Info.plist file.

Android

**Important**: When targeting Android with the config-file element, you'll need to declare the android xml namespace in the widget element of your config.xml, otherwise your document will not pass our xml validation. 
<widget xmlns       = "http://www.w3.org/ns/widgets"
    xmlns:gap       = "http://phonegap.com/ns/1.0"
    xmlns:android   = "http://schemas.android.com/apk/res/android"
    id              = "com.lumberg.greeeaaat"
    version         = "1.0.0">

For an Android example suppose you want to modify the screen sizes supported by your application, through the supports-screens element in the Android Manifest. Here is the default in a PhoneGap Build AndroidManifest.xml:

<supports-screens android:anyDensity="true" android:resizeable="true"
  android:smallScreens="true"
  android:normalScreens="true"
  android:largeScreens="true"
  android:xlargeScreens="true" />

To disable support for all but normalScreens, set them to false:

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

Your xml will be merged with the default manifest xml, and when conflicts occur, your specified values will take precedence. To check and debug the resulting Android Manifest, you can use the Android apk-tool to unpack your compiled apk, and examine the AndroidManifest.xml.

If you have any questions about using this beta feature, don't hesitate to ask.

Original configuration reference · access-elements
As of Cordova iOS 4.x, Cordova Android 4.x, and Cordova Windows 4.x, whitelist management was moved from the core Cordova project to the `cordova-whitelist-plugin`, including the addition of the `allow-navigation` and `allow-intent` elements. You must add this plugin to enable and restrict network access in your application. 
  <plugin name="cordova-plugin-whitelist" />

See the cordova-whitelist-plugin repository for up to date documentation.

Original configuration reference · 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.

Original configuration reference · icons-and-splash
As of cli-7.0.1 and the new builder (more info), PhoneGap Build hands off to Cordova put read your icon and splash configurations and put them where they need to be. As a result, we recommend referring to the Cordova Icon and Splashscreen Plugin docs for the most up to date instructions. Otherwise if you're still using cli-6.5.0 (and the old builder), see below.

Specifying platform

Icons and splashes are usually platform specific. There are two ways to specify an icon or splash is for a particular platform. The first way is by specifying a platform attribute:

<icon src="icon-60@3x.png" platform="ios" width="180" height="180" />

The second way (recommended) is by putting the icon or splash inside a platform tag:

<platform name="ios">
  <icon src="icon-60@3x.png" width="180" height="180" />
</platform>

Both these fragments will result in the icon being used for iOS.

Icons

The simplest icon configuration is a single default icon.png:

  <icon src="icon.png" />

The default icon must be named icon.png and must reside in the root of your application folder. If no other icon configurations are specified, each platform will attempt to use this file as the default icon. To define platform specific icons please use the guide provided below. Icon files should be the file formats specified in the examples below, other file types are not guaranteed to work across platforms.

  <icon src="res/icon/ios/icon-60@3x.png" platform="ios" width="180" height="180" />
  • src: (required) specifies the location of the image file relative to your config.xml
  • width: (optional) but recommended to include, width in pixels
  • height: (optional) but recommended to include, height in pixels
  • platform: (optional) the target platform (ios, android, or windows)

iOS

We support classic, retina, iPhone 5 and iPad displays.

The names below reflect the names of the destination files when they are added to the application. During app submittal you may get feedback that has a reference to these filenames.

iOS 7.0+

<!-- iPhone 6 / 6+ -->
<icon src="icon-60@3x.png" platform="ios" width="180" height="180" />

<!-- iPhone / iPod Touch  -->
<icon src="icon-60.png" platform="ios" width="60" height="60" />
<icon src="icon-60@2x.png" platform="ios" width="120" height="120" />

<!-- iPad -->
<icon src="icon-76.png" platform="ios" width="76" height="76" />
<icon src="icon-76@2x.png" platform="ios" width="152" height="152" />
<icon src="icon-83.5@2x.png" platform="ios" width="167" height="167" />

<!-- Settings Icon -->
<icon src="icon-small.png" platform="ios" width="29" height="29" />
<icon src="icon-small@2x.png" platform="ios" width="58" height="58" />
<icon src="icon-small@3x.png" platform="ios" width="87" height="87" />

<!-- Spotlight Icon -->
<icon src="icon-40.png" platform="ios" width="40" height="40" />
<icon src="icon-40@2x.png" platform="ios" width="80" height="80" />
<icon src="icon-40@3x.png" platform="ios" width="120" height="120" />

iOS 6.1

<!-- iPhone / iPod Touch -->
<icon src="icon.png" platform="ios" width="57" height="57" />
<icon src="icon@2x.png" platform="ios" width="114" height="114" />

<!-- iPad -->
<icon src="icon-72.png" platform="ios" width="72" height="72" />
<icon src="icon-72@2x.png" platform="ios" width="144" height="144" />

<!-- iPhone Spotlight and Settings Icon -->
<icon src="icon-small.png" platform="ios" width="29" height="29" />
<icon src="icon-small@2x.png" platform="ios" width="58" height="58" />

<!-- iPad Spotlight and Settings Icon -->
<icon src="icon-50.png" platform="ios" width="50" height="50" />
<icon src="icon-50@2x.png" platform="ios" width="100" height="100" />

Android

We support all Android resource qualifiers. Commonly used qualifiers refer to device density and language.

<icon src="ldpi.png" platform="android" qualifier="ldpi" />
<icon src="mdpi.png" platform="android" qualifier="mdpi" />
<icon src="hdpi.png" platform="android" qualifier="hdpi" />
<icon src="xhdpi.png" platform="android" qualifier="xhdpi" />
<icon src="xxhdpi.png" platform="android" qualifier="xxhdpi" />
<icon src="xxxhdpi.png" platform="android" qualifier="xxxhdpi" />
<icon src="fr-xxhdpi.png" platform="android" qualifier="fr-xxhdpi" />

A list of these qualifiers can be viewed on Table-2 here. Note that compound qualifiers (eg. "port-xhdpi") have to be in the same order as viewed on this table.

Windows Phone 8 (cordova-wp8)

We support two icons for Windows Phone, a regular icon and a tile image.

<icon src="icon.png" platform="winphone" />
<icon src="tileicon.png" platform="winphone" role="background" />

Windows Phone 8.1+ (cordova-windows)

As of PhoneGap Release cli-6.0.0, the Windows Phone 8.1 package is built using cordova-windows. Here are the supported icons:

<icon platform="winphone" width="44"  height="44"  src="res/Square44x44Logo.scale-100.png" />
<icon platform="winphone" width="106" height="106" src="res/Square44x44Logo.scale-240.png" />
<icon platform="winphone" width="150" height="150" src="res/Square150x150Logo.scale-100.png" />
<icon platform="winphone" width="360" height="360" src="res/Square150x150Logo.scale-240.png" />
<icon platform="winphone" width="71"  height="71"  src="res/Square71x71Logo.scale-100.png" />
<icon platform="winphone" width="170" height="170" src="res/Square71x71Logo.scale-240.png" />
<icon platform="winphone" width="310" height="150" src="res/Wide310x150Logo.scale-100.png" />
<icon platform="winphone" width="744" height="360" src="res/Wide310x150Logo.scale-240.png" />
<icon platform="winphone" width="70"  height="70"  src="res/Square70x70Logo.scale-100.png" />
<icon platform="winphone" width="30"  height="30"  src="res/Square30x30Logo.scale-100.png" />
<icon platform="winphone" width="310" height="310" src="res/Square310x310Logo.scale-100.png" />
<icon platform="winphone" width="50"  height="50"  src="res/StoreLogo.scale-100.png" />
<icon platform="winphone" width="120" height="120" src="res/StoreLogo.scale-240.png" />

Splash Screens

You can have zero or more of these elements present in your config.xml. This element can have src, platform, width and height attributes, just like the <icon> element above. Like icon files, your splash screens should be saved as png files.

<splash src="splash/ios/Default-568h@2x~iphone.png" platform="ios" width="320" height="480" />

Usage and Additional Information:

Unless otherwise specified in a config.xml, each platform will try to use the default splash.png during compilation. To define platform specific splash screens please use the guide provided below.

Splash files should be the file formats specified in the examples below. Any other file type is not guaranteed to work across platforms.

Warning:

If you do not supply the platform attribute, the referenced image will be copied to ALL platforms, increasing the size of their application packages.

Default

The default splash must be named splash.png and must reside in the root of your application folder.

  <splash src="splash.png" />

Please note that in the past splash screens were specified with the gap:splash element and the platform specified with gap:platform. This is still supported but we recommend moving to splash and platform.

iOS

We support classic, retina, iPhone 5 and iPad displays; the following will define splash screens for each of those. Standard iPads have two different splash screens, portrait, landscape. Retina iPads have two additional splash screens, retina portrait and retina landscape.

The names below reflect the names of the destination files when they are added to the application. During app submittal you may get feedback that has a reference to these filenames.

<!-- iPhone and iPod touch -->
<splash src="Default.png" platform="ios" width="320" height="480" />
<splash src="Default@2x.png" platform="ios" width="640" height="960" />

<!-- iPhone 5 / iPod Touch (5th Generation) -->
<splash src="Default-568h@2x.png" platform="ios" width="640" height="1136" />

<!-- iPhone 6 -->
<splash src="Default-667h@2x.png" platform="ios" width="750" height="1334" />
<splash src="Default-Portrait-736h@3x.png" platform="ios" width="1242" height="2208" />
<splash src="Default-Landscape-736h@3x.png" platform="ios" width="2208" height="1242" />

<!-- iPad -->
<splash src="Default-Portrait.png" platform="ios" width="768" height="1024" />
<splash src="Default-Landscape.png" platform="ios" width="1024" height="768" />

<!-- Retina iPad -->
<splash src="Default-Portrait@2x.png" platform="ios" width="1536" height="2048" />
<splash src="Default-Landscape@2x.png" platform="ios" width="2048" height="1536" />

Android

We support all Android resource qualifiers. Commonly used qualifiers refer to device orientation, language and density.

<splash src="ldpi.png" platform="android" qualifier="ldpi" />
<splash src="mdpi.png" platform="android" qualifier="mdpi" />
<splash src="hdpi.png" platform="android" qualifier="hdpi" />
<splash src="xhdpi.png" platform="android" qualifier="xhdpi" />
<splash src="fr-xhdpi.png" platform="android" qualifier="fr-xhdpi" />
<splash src="portrait-xxhdpi.png" platform="android" qualifier="port-xxhdpi" />
<splash src="landscape-xxhdpi.png" platform="android" qualifier="land-xxhdpi" />
<splash src="xxxhdpi.png" platform="android" qualifier="xxxhdpi" />

A list of these qualifiers can be viewed on Table-2 here. Note that compound qualifiers (eg. "port-xhdpi") have to be in the same order as viewed on this table.

Patch-9 backgrounds are supported. All patch-9 files have to have a ".9.png" suffix.

Windows Phone 8 (cordova-wp8)

Windows Phone supports a single splash image and can be defined as below. Unlike the other supported platforms, Windows Phone splash screen should be in jpg format

<splash src="splash/winphone/splash.jpg" platform="winphone" />

Windows Phone 8.1 (cordova-windows)

Windows Phone 8.1 supports a single png splash as defined here

<splash platform="winphone" width="1152" height="1920" src="res/SplashScreenPhone.scale-240.png" />
<splash platform="winphone" width="620"  height="300"  src="res/SplashScreen.scale-100.png" />

Sources & archive notes

Recovered repository material is attributed to its original authors and distributed with its source license. Changes: FreeSoft layout, archive context, navigation, link and image locations. Apache License 2.0 · Notices and provenance. Editorial material is labeled separately.