The config.xml File
Many aspects of an app's behavior can be controlled with a global configuration file,
config.xml. This platform-agnostic XML file is arranged based on the W3C's Packaged Web Apps (Widgets) specification, and extended to specify core Cordova API features, plugins, and platform-specific settings.
For projects created with the Cordova CLI (described in The Command-Line Interface), this file can be found in the top-level directory:
Note that before version 3.3.1-0.2.0, the file existed at
app/www/config.xml, and that having it here is still supported.
When using the CLI to build a project, versions of this file are passively copied into various
platforms/ subdirectories, for example:
app/platforms/ios/AppName/config.xml app/platforms/blackberry10/www/config.xml app/platforms/android/res/xml/config.xml
This section details global and cross-platform configuration options. See the following sections for platform-specific options:
In addition to the various configuration options detailed below, you can also configure an application's core set of images for each target platform. See Icons and Splash Screens for more information.
Core Configuration Elements
This example shows the default
config.xml generated by the CLI's
create command, described in The Command-Line Interface:
<widget id="com.example.hello" version="0.0.1"> <name>HelloWorld</name> <description> A sample Apache Cordova application that responds to the deviceready event. </description> <author email="[email protected]" href="http://cordova.io"> Apache Cordova Team </author> <content src="index.html" /> <access origin="*" /> </widget>
The following configuration elements appear in the top-level
config.xml file, and are supported across all supported Cordova platforms:
idattribute provides the app's reverse-domain identifier, and the
versionits full version number expressed in major/minor/patch notation.
The widget tag can also have attributes that specify alternative versions, namely
versionCode for Android,
CFBundleVersion for iOS, and
packageVersion for Windows. See the Additional Versioning section below for details.
<name>element specifies the app's formal name, as it appears on the device's home screen and within app-store interfaces.
<author>elements specify metadata and contact information that may appear within app-store listings.
<content>element defines the app's starting page in the top-level web assets directory. The default value is
index.html, which customarily appears in a project's top-level
<access>elements define the set of external domains the app is allowed to communicate with. The default value shown above allows it to access any server. See the Domain Whitelist Guide for details.
<preference>tag sets various options as pairs of
valueattributes. Each preference's
nameis case-insensitive. Many preferences are unique to specific platforms, as listed at the top of this page. The following sections detail preferences that apply to more than one platform.
Android, iOS, and Windows support a second version string (or number) in addition to the one visible in app stores:
Below is an example that explicitly sets these properties:
<widget id="io.cordova.hellocordova" version="0.0.1" android-versionCode="7" ios-CFBundleVersion="3.3.3" windows-packageVersion="22.214.171.124">
If alternative version is not specified, the following defaults will be used:
// assuming version = MAJOR.MINOR.PATCH-whatever versionCode = PATCH + MINOR * 100 + MAJOR * 10000 CFBundleVersion = "MAJOR.MINOR.PATCH" packageVersion = "MAJOR.MINOR.PATCH.0"
The following global preferences apply to all platforms:
Fullscreenallows you to hide the status bar at the top of the screen. The default value is
<preference name="Fullscreen" value="true" />
The following preferences apply to more than one platform, but not to all of them:
DisallowOverscroll(boolean, defaults to
false): set to
trueif you don't want the interface to display any feedback when users scroll past the beginning or end of content.
<preference name="DisallowOverscroll" value="true"/>
Applies to Android and iOS. On iOS, overscroll gestures cause content to bounce back to its original position. On Android, they produce a more subtle glowing effect along the top or bottom edge of the content.
BackgroundColor: Set the app's background color. Supports a four-byte hex value, with the first byte representing the alpha channel, and standard RGB values for the following three bytes. This example specifies blue:
<preference name="BackgroundColor" value="0xff0000ff"/>
Applies to Android and BlackBerry. Overrides CSS otherwise available across all platforms, for example:
HideKeyboardFormAccessoryBar(boolean, defaults to
false): set to
trueto hide the additional toolbar that appears above the keyboard, helping users navigate from one form input to another.
<preference name="HideKeyboardFormAccessoryBar" value="true"/>
Applies to BlackBerry.
Orientation(string, defaults to
default): allows you to lock orientation and prevent the interface from rotating in response to changes in orientation. Possible values are
<preference name="Orientation" value="landscape" />
Additionally, you can specify any platform-specific orientation value if you place the
<preference> element within a
<platform name="android"> <preference name="Orientation" value="sensorLandscape" /> </platform>
Applies to Android, iOS, WP8, Amazon Fire OS and Firefox OS.
default value means Cordova will strip the orientation preference entry from the platform's manifest/configuration file allowing the platform to fallback to its default behavior.
For iOS, to specify both portrait & landscape mode you would use the platform specific value
<platform name="ios"> <preference name="Orientation" value="all" /> </platform>
The feature Element
If you use the CLI to build applications, you use the
plugin command to enable device APIs. This does not modify the top-level
config.xml file, so the
<feature> element does not apply to your workflow. If you work directly in an SDK and using the platform-specific
config.xml file as source, you use the
<feature> tag to enable device-level APIs and external plugins. They often appear with custom values in platform-specific
config.xml files. For example, here is how to specify the Device API for Android projects:
<feature name="Device"> <param name="android-package" value="org.apache.cordova.device.Device" /> </feature>
Here is how the element appears for iOS projects:
<feature name="Device"> <param name="ios-package" value="CDVDevice" /> </feature>
See the API Reference for details on how to specify each feature. See the Plugin Development Guide for more information on plugins.
The platform Element
When using the CLI to build applications, it is sometimes necessary to specify preferences or other elements specific to a particular platform. Use the
<platform> element to specify configuration that should only appear in a single platform-specific
config.xml file. For example, here is how to specify that only android should use the Fullscreen preference:
<platform name="android"> <preference name="Fullscreen" value="true" /> </platform>
The hook Element
Represents your custom script which will be called by Cordova when certain action occurs (for example, after plugin is added or platform prepare logic is invoked). This is useful when you need to extend default Cordova functionality. See Hooks Guide for more information.
<hook type="after_plugin_install" src="scripts/afterPluginInstall.js" />
© 2012-2015 The Apache Software Foundation
Licensed under the Apache License 2.0.