Config.xml is a platform specific configuration file.

With the help of this configuration file, it is possible to modify the default values of PhoneGap application elements like –

  • Widget
  • Name
  • Description
  • Plugins
  • API
  • Icons
  • Splash Screens etc.

Important Points About Config.xml

  1. Make sure it is at the top level of your application.
  2. You can take a look at the file structure of PhoneGap here.
  3. Its major purpose is to let developers specify the metadata about the application.

Now let’s take a look at the steps through which you can create a configuration file:

Step 1: Including XML Element

The very first step while creating a configuration file is to include XML element with the attributes version and encoding type.

<?xml version = "1.0" encoding = "UTF-8"?>

Step 2: Including Widget, Name & Description Element

Following elements are the basic elements of the configuration file. Their inclusion is mandatory.

Necessary Elements

  1. <widget>: (required) It is the root of the configuration file. It indicates that whether configuration file is following W3C Standards or not.
    <widget xmlns = ""
    xmlns:gap = ""
    id = "com.formget.sample"
    versionCode = "1"
    version = "1.0.0">

    (a) id: It acts like the unique identifier for an application. It is written as reverse domain format. An application supports different platforms because of it.

    id = "com.formget.sample"

    (b) version: Full version number of the application with the three number format : “Major.Minor.Patch”.

    version = "1.0.0"

    (c) versionCode: (optional) Internal version number only set for android.

    versionCode = "1"

    (d) cfBundleVersion: (optional) Internal version number only set for ios.

  2. <name>: (required) It is the name of the application which is going to be visible on home screen and app store.
  3. <description>: (optional) It is the description of the application that what this app is all about and what it does.
    <description>An online form building application to create & design any type of HTML web form</description>

Step 3: Including Author Element

(optional) It defines the author of the application with the attributes email and href.

<author email="[email protected]" href="">FormGet Team</author>

Step 4: Including Content Element

(optional) It sets the starting page of the application.

<content src="index.html"/>

Step 5: Including Platform Element

By default PhoneGap Build builds an application for all platforms. If you want to build an app for a specific platform, you can do it with gap:platform element or platform element.

With ‘gap:platform’ Element:

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

With ‘platform’ Element:

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

Step 6: Including Feature (API) Element

Feature Element is used to include the features (API) which are going to used by the application.

Suppose you want to include the network feature.

<feature name="" />

Similarly, you can add multiple features.

<feature name="" />
<feature name="" />
<feature name="" />
<feature name="" />
<feature name="" />
<feature name="" />
<feature name="" />
<feature name="" />
<feature name="" />

Step 7: Including Plugin Element

Plugin Element is used to include the plugins.


<plugin name="com.phonegap.plugins..barcodescanner" spec="~1" source="npm" />
  1. name: Plugin id with the reverse domain format.
  2. spec: (optional) Plugin version.
  3. source: (optional) It can be pgb or npm.
  4. params: (optional) Parameters for configuration properties.

Suppose you want to include the barcodescanner plugin.

<plugin name="com.phonegap.plugins..barcodescanner" spec="~1" source="npm" />

There are several plugins available for different purposes. You can see them here.

Step 8: Including Preference Element

There are 2 types of preferences you can set in the configuration file of PhoneGap.

  1. Common Preferences
  2. Platform Specific Preferences

Common Preferences:

Common Preferences

  1. Fullscreen Preference: It makes the application full screen. It is used to hide the status bar at the top of the screen.
    <preference name="Fullscreen" value="true"/>
  2. DisallowOverscroll Preference: If you don’t want the application to show anything when users scroll past the beginning or end of content, set this to true.
    <preference name="DisallowOverscroll" value="true"/>
  3. Orientation Preference: Orientation allows you to set and fix the orientation of the app to avoid automatic rotation.
    There are three options for orientation: default, landscape and portrait.

    <preference name="Orientation" value="landscape"/>
  4. HideKeyboardFromAccessoryBar Preference: Sets to true to hide additional toolbar above the keyboard.
    <preference name="HideKeyboardFormAccessoryBar" value="false"/>
  5. BackgroundColor Preference: Sets the background color of the application with a 4 byte format.
    Byte 1 : Alpha Channel
    Byte 2-4 : RGB(Red Green Blue Colors)

    <preference name="BackgroundColor" value="0xff0000ff"/>

Platform Specific Preferences:

Platform Specific Preferences:

IOS Specific Preferences

  1. Target-Device Preference: Targeting the specific device. Its options are : handset, tablet, or universal.
    <preference name="target-device" value="universal" />
  2. Prerendered-icon Preference: Sets to ‘true’ to let ios know that icon is already rendered and don’t add anything to it.
    <preference name="prerendered-icon" value="true" />
  3. Detect-data-types: Checks whether data types (For Example: dates and phone numbers) are automatically converted to links by the system.
    <preference name="detect-data-types" value="true" />
  4. Exit-on-suspend: Application will be closed when suspended.
    <preference name="exit-on-suspend" value="true" />
  5. Deployment-target: It sets the IPHONEOS_DEPLOYMENT_TARGET in the build process, which is converted to theMinimumOSVersion in the ipa Propertly List.
    <preference name="deployment-target" value="7.0" />

Android Specific Preferences

  1. KeepRunning: App will continue to run in the background.
    <preference name="KeepRunning" value="false"/>
  2. LoadUrlTimeoutValue: It sets the amount of time to wait during a page load. After that, it will throw a timeout error. It is in milliseconds.
    <preference name="LoadUrlTimeoutValue" value="5000"/>
  3. SplashScreen: To set the names of the splash screen images. They must share a common name.
    <preference name="SplashScreen" value="FormGetSplash"/>
  4. SplashScreenDelay: The amount to time a splash screen appears. It is in milliseconds.
    <preference name="SplashScreenDelay" value="5000"/>
  5. InAppBrowserStorageEnabled: It makes sure that web pages opened in an InAppBrowser and web pages opened in the default browser share the same localStorage.
    <preference name="InAppBrowserStorageEnabled" value="true"/>
  6. LoadingDialog: It displays a dialog at the first page of the application with a title, message and a loading image.
    <preference name="LoadingDialog" value="My Title,My Message"/>
  7. LoadingPageDialog:  It displays a dialog at every page of the application.
    <preference name="LoadingPageDialog" value="My Title,My Message"/>
  8. ErrorUrl: Intead of dialog, an error page will be displayed with a title,”Application Error”.
    <preference name="ErrorUrl" value="myErrorPage.html"/>
  9. ShowTitle: It displays the title at the top of the screen.
    <preference name="ShowTitle" value="true"/>
  10. LogLevel: Its sets the log level to minimum. By doing this, log messages of the app are filtered. Options are :   ERROR, DEBUG, INFO, VERBOSE, and WARN.
    <preference name="LogLevel" value="VERBOSE"/>
  11. SetFullscreen: It is similar to the FullScreen of global config file.
    <preference name="SetFullscreen" value="false"/>

Step 9: Including Icon and Spash Element

Icons and Splashes are also platform specific. Use ‘icon’ element to include ‘icons’ and use ‘splash’ element to include ‘splash screens’.

There are 2 ways to include icons and splashes:

  1. Use icon and splash element directly
    <icon src="formget-icon.png" platform="ios" width="180" height="180"/>
    <splash src="formget-icon.png" platform="ios" width="180" height="180"/>
  2. Put icon element inside the platform element
    <platform name="ios">
    <icon src="formget-icon.png" width="180" height="180" />
    <splash src="formget-icon.png" platform="ios" width="180" height="180"/>



<icon src="formget-icon.png" platform="ios" width="180" height="180"/>
  1. src: (required) Source/Location of the icon image file specific to the www folder.
    src= "formget-icon.png" 
  2. platform: (optional) Platform for which the icon belongs to.
  3. width: (optional) Width of the icon image.
  4. height: (optional) Height of the icon image.

Similarly, icons of different sizes can be included for different platforms.



<splash src="formget-icon.png" platform="ios" width="180" height="180"/>
  1. src: (required) Source/Location of the splash image file specific to the www folder.
    src= "formget-icon.png" 
  2. platform: (optional) Platform for which the icon belongs to.
  3. width: (optional) Width of the icon image.
  4. height: (optional) Height of the icon image.

Similarly, splash screens of different sizes can be included for different platforms.


So you see, how easy it is to configure PhoneGap using the configuration file. It’s no rocket science to include icons, splash screens, plugins and other elements. I hope this will definitely help you.

You may also like –