www/docs/en/5.0.0/config_ref/index.md

---
license: >
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

title: The config.xml File
---

# 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)](http://www.w3.org/TR/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:

        app/config.xml

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:

- [iOS Configuration](../guide/platforms/ios/config.html)
- [Android Configuration](../guide/platforms/android/config.html)
- [BlackBerry 10 Configuration](../guide/platforms/blackberry10/config.html)

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](images.html) 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](../guide/cli/index.html):

        <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="dev@callback.apache.org" 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:

- The `<widget>` element's `id` attribute provides the app's
  reverse-domain identifier, and the `version` its full version number
  expressed in major/minor/patch notation.

  The widget tag can also have attributes that specify alternative versions,
  namely versionCode for Android and CFBundleVersion for iOS. See the
  Additional Versioning section below for details.

- The `<name>` element specifies the app's formal name, as it appears
  on the device's home screen and within app-store interfaces.

- The `<description>` and `<author>` elements specify metadata and
  contact information that may appear within app-store listings.

- The optional `<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
  `www` directory.

- `<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](../guide/appdev/whitelist/index.html) for details.

- The `<preference>` tag sets various options as pairs of
  `name`/`value` attributes. Each preference's `name` is
  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.

### Additional Versioning

Both, Android and iOS support a second version string (or number) in addition
to the one visible in app stores,
[versionCode](http://developer.android.com/tools/publishing/versioning.html)
for Android and
[CFBundleVersion](http://stackoverflow.com/questions/4933093/cfbundleversion-in-the-info-plist-upload-error)
for iOS.
Below is an example that explicitly sets versionCode and CFBundleVersion

        <widget id="io.cordova.hellocordova"
          version="0.0.1"
          android-versionCode="7"
          ios-CFBundleVersion="3.3.3">

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"

## Global Preferences

The following global preferences apply to all platforms:

- `Fullscreen` allows you to hide the status bar at the top of the
  screen. The default value is `false`. Example:

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

## Multi-Platform Preferences

The following preferences apply to more than one platform, but not to
all of them:

- `DisallowOverscroll` (boolean, defaults to `false`): set to `true`
  if 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: `body{background-color:blue}`.

- `HideKeyboardFormAccessoryBar` (boolean, defaults to `false`): set
  to `true` to 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 iOS and 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 `default`, `landscape` 
  or `portrait`. Example:

        <preference name="Orientation" value="landscape" />
    
  Additionally, you can specify any platform-specific orientation value
  if you place the `<preference>` element within a `<platform>` element:
  
        <platform name="android">
            <preference name="Orientation" value="sensorLandscape" />
        </platform>
  
  Applies to Android, iOS, WP8, Amazon Fire OS and Firefox OS.

  __NOTE__: The `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.

'default' allows both portrait & landscape mode - only after implementing the callback. I could perhaps re-word this as follows:

For iOS, orientation can be programmatically controlled by defining a javascript callback on window:

    /** 
    * @param {Number} degree - UIInterfaceOrientationPortrait: 0, UIInterfaceOrientationLandscapeRight: 90, UIInterfaceOrientationLandscapeLeft: -90, UIInterfaceOrientationPortraitUpsideDown: 180
    * @returns {Boolean} Indicating if rotation should be allowed.
    */
    function shouldRotateToOrientation(degrees) {
         return true;
    }

## 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](../guide/hybrid/plugins/index.html) 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>