Config.xml API

The config.xml file is a global configuration file that manages various aspects of a Cordova application's behavior. It is written in XML format and follows the structure outlined in the W3C's Packaged Web Apps (Widgets) specification. Additionally, it is extended to include core Cordova API features, plugins, and platform-specific settings.

If you are using the Cordova CLI to create your project (as explained in The Command-Line Interface), you can locate the config.xml file in the top-level directory of your project.

./hellocordova
└── config.xml

When using the CLI to build a project, versions of this file are passively copied into various platforms/ subdirectories. For example:

./hellocordova
└── platforms
    ├── android
    │   └── app
    │       └── src
    │           └── main
    │               └── res
    │                   └── xml
    │                       └── config.xml
    └── ios
        └── HelloCordova
            └── config.xml

Some platforms offer integrated development environments (IDEs) like Xcode for iOS and Android Studio for Android, which allow you to build and test your application. If you choose to use these IDEs for building and testing your project, it is recommended to run the cordova prepare CLI command whenever you make changes to the Cordova application's config.xml. This ensures that the updated configurations are copied into the respective platforms/ subdirectories.

In addition to the configuration options described below, you have the ability to customize the core set of images for your application on each target platform. For more information, please refer to the topic on Customizing Icons.

Sample config.xml:

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets"
    xmlns:cdv="http://cordova.apache.org/ns/1.0"
    id="io.cordova.hellocordova"
    version="1.0.0">
    <name>HelloCordova</name>
    <description>Sample Apache Cordova App</description>
    <author email="dev@cordova.apache.org" href="https://cordova.apache.org">
        Apache Cordova Team
    </author>

    <content src="index.html" />

    <!-- Security Related Settings -->
    <access origin="https://cordova.apache.org" />
    <allow-intent href="http://*/*" />
    <allow-intent href="https://*/*" />

    <!-- Platform Configs & Platform Overriding Configs -->
    <platform name="android"></platform>
    <platform name="ios"></platform>
</widget>

widget

Root element of the config.xml document.

Examples:

<!-- Android -->
<widget id="io.cordova.hellocordova" version="0.0.1" android-versionCode="13" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
</widget>

<!-- iOS -->
<widget id="io.cordova.hellocordova" version="0.0.1" ios-CFBundleVersion="0.1.3" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
</widget>

name

Specifies the app's formal name, as it appears on the device's home screen and within app-store interfaces.

Examples:

<widget ...>
   <name>HelloCordova</name>
</widget>

short name

Specifies an optional display name for the app. Sometimes the app name should be displayed differently on device's home screen than on informational and app-store interfaces due to limited space.

Examples:

<widget ...>
   <name short="HiCdv">HelloCordova</name>
</widget>

description

Specifies metadata that may appear within app-store listings.

Examples:

<widget ...>
   <description>A sample Apache Cordova application</description>
</widget>

author

Specifies contact information that may appear within app-store listings.

Examples:

<widget ...>
   <author email="dev@cordova.apache.org" href="https://cordova.io"></author>
</widget>

content

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.

Examples:

<widget ...>
   <content src="startPage.html"></content>
</widget>

access

Defines the external domains that the app is allowed to communicate with. When the access origin is set to "*", the app can access any server, but this can potentially create a security risk. It is recommended to explicitly specify the permitted URLs to ensure a secure configuration. For detailed instructions, please refer to the Allow List Guide.

Examples:

<widget ...>
   <access origin="*"></access>
</widget>

<widget ...>
   <access origin="http://google.com"></access>
</widget>

allow-navigation

Controls which URLs the WebView can be navigated to. Applies to top-level navigations only. See the Allow List Guide for details.

Examples:

<!-- Allow links to example.com -->
<allow-navigation href="http://example.com/*" />

<!-- Wildcards are allowed for the protocol, as a prefix to the host, or as a suffix to the path -->
<allow-navigation href="*://*.example.com/*" />

allow-intent

Controls which URLs the app is allowed to ask the system to open. By default, no external URLs are allowed. See the Allow List Guide for details.

Examples:

<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />
<allow-intent href="tel:*" />
<allow-intent href="sms:*" />

edit-config

See <config-file> docs for plugin.xml.

config-file

See <config-file> docs for plugin.xml.

engine

Specifies details about what platform to restore during a prepare.

Examples:

<engine name="android" spec="https://github.com/apache/cordova-android.git#5.1.1" />
<engine name="ios" spec="^4.0.0" />

plugin

Specifies details about what plugin to restore during a prepare. This element is automatically added to a project's config.xml when a plugin is added using the --save flag. See the CLI reference for more information on adding plugins.

Note: As of Cordova 9.x, this tag is obsolete. Learn More

Examples:

<plugin name="cordova-plugin-device" spec="^1.1.0" />
<plugin name="cordova-plugin-device" spec="https://github.com/apache/cordova-plugin-device.git#1.0.0" />

variable

Persists the value of a CLI variable to be used when restoring a plugin during a prepare. This element is added to config.xml when a plugin that uses CLI variables is added using the --save flag. See the CLI reference for more information on adding plugins.

Note that this value is only used when the plugin is restored to the project during a prepare, changing it will not change the value used by the plugin in the current project. In order for changes to this value to take effect, remove the plugin from the project and restore it by running cordova prepare. See the preference element of plugin.xml for more details on CLI variables.

Examples:

<plugin name="cordova-plugin-device" spec="^1.1.0">
    <variable name="MY_VARIABLE" value="my_variable_value" />
</plugin>

preference

Sets various options as pairs of name/value attributes. Each preference's name is case-insensitive. Many preferences are unique to specific platforms, and will be indicated as such.

Examples:

<preference name="DisallowOverscroll" value="true"/>
<preference name="Fullscreen" value="true" />
<preference name="BackgroundColor" value="0xff0000ff"/>
<preference name="HideKeyboardFormAccessoryBar" value="true"/>
<preference name="Orientation" value="landscape" />

<!-- iOS only preferences -->
<preference name="EnableViewportScale" value="true"/>
<preference name="MediaPlaybackAllowsAirPlay" value="false"/>
<preference name="MediaPlaybackRequiresUserAction" value="true"/>
<preference name="AllowInlineMediaPlayback" value="true"/>
<preference name="TopActivityIndicator" value="white"/>
<preference name="SuppressesIncrementalRendering" value="true"/>
<preference name="GapBetweenPages" value="0"/>
<preference name="PageLength" value="0"/>
<preference name="PaginationBreakingMode" value="page"/>
<preference name="PaginationMode" value="unpaginated"/>
<preference name="UIWebViewDecelerationSpeed" value="fast" />
<preference name="ErrorUrl" value="myErrorPage.html"/>
<preference name="OverrideUserAgent" value="Mozilla/5.0 My Browser" />
<preference name="AppendUserAgent" value="My Browser" />
<preference name="target-device" value="universal" />
<preference name="deployment-target" value="7.0" />
<preference name="CordovaWebViewEngine" value="CDVWebViewEngine" />
<preference name="CordovaDefaultWebViewEngine" value="CDVWebViewEngine" />
<preference name="SuppressesLongPressGesture" value="true" />
<preference name="Suppresses3DTouchGesture" value="true" />

<!-- Android only preferences -->
<preference name="KeepRunning" value="false"/>
<preference name="LoadUrlTimeoutValue" value="10000"/>
<preference name="InAppBrowserStorageEnabled" value="true"/>
<preference name="LoadingDialog" value="My Title,My Message"/>
<preference name="ErrorUrl" value="myErrorPage.html"/>
<preference name="ShowTitle" value="true"/>
<preference name="LogLevel" value="VERBOSE"/>
<preference name="AndroidLaunchMode" value="singleTop"/>
<preference name="AndroidInsecureFileModeEnabled" value="true" />
<preference name="DefaultVolumeStream" value="call" />
<preference name="OverrideUserAgent" value="Mozilla/5.0 My Browser" />
<preference name="AppendUserAgent" value="My Browser" />
<preference name="GradlePluginGoogleServicesEnabled" value="true" />
<preference name="GradlePluginGoogleServicesVersion" value="4.2.0" />
<preference name="GradlePluginKotlinEnabled" value="true" />
<preference name="GradlePluginKotlinCodeStyle" value="official" />
<preference name="GradlePluginKotlinVersion" value="1.3.50" />

feature

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 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 tag to enable device-level APIs and external plugins. They often appear with custom values in platform-specific config.xml files. 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. NOTE: Most of the time, you do NOT want to set this directly.

param

Used to specify certain plugin parameters such as: what package to retrieve the plugin code from, and whether the plugin code is to be initialized during the Webview's initialization.

Examples:

<!-- 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's how the element appears for iOS projects -->
<feature name="Device">
   <param name="ios-package" value="CDVDevice" />
   <param name="onload" value="true" />
</feature>

platform

When using the CLI to build applications, it is sometimes necessary to specify preferences or other elements specific to a particular platform. Use the element to specify configuration that should only appear in a single platform-specific config.xml file.

Examples:

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

hook

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.

Examples:

<hook type="after_plugin_install" src="scripts/afterPluginInstall.js" />

resource-file

This tag installs resource files into your platform, and is similar to the same tag in plugin.xml. This tag is currently only supported on cordova-ios@4.4.0 or greater and cordova-android@6.2.1 or greater.

Examples:

For Android:

<resource-file src="FooPluginStrings.xml" target="res/values/FooPluginStrings.xml" />