Understanding Intel XDK Cordova* Build Files

NOTE: A previous release of the Intel® XDK used a beta release of the Intel® XDK Cordova build system (versions 0876 and earlier of the Intel XDK). The previous beta build system required that you create a special build config file (aka intelxdk.config.xml) and include it with your HTML5 mobile app sources before submitting your application to the Cordova build system. In the current production release of the Intel XDK Cordova build system, this build config file is generated automatically based on information you provide about your app in the Projects tab. This document describes many of the directives you will see in the automatically generated build config files. It can also be used to help you create an intelxdk.config.additions.xml file to control special build options that are not handled by the Projects tab GUI. This document describes that build config file.

The Intel® XDK Cordova build system uses special configuration files in your project directory to control the build process. The Cordova build option is based on the open source Apache* Cordova CLI build system. When using the Cordova build option your application project files are submitted to a Cordova CLI system that is hosted and maintained on the Intel XDK build server, there is no need to install the open source Cordova CLI system on your workstation.

NOTE: the Adobe* PhoneGap* CLI system and the Google* Mobile Chrome Apps project (aka cca) are based on the same Apache Cordova CLI open source project.

Because this build system is derived directly from the Cordova CLI open source project, the build control files share many options with the Cordova CLI config.xml file(s) you will find in a local Cordova CLI (or PhoneGap CLI) build environment. The options used in the Intel XDK build configuration file are a superset of those used in the Cordova CLI config.xml file.

NOTE: The config.xml file used to direct the cloud-based Adobe* PhoneGap Build* environment is unique to PhoneGap Build; it is also a superset of the Cordova CLI config.xml file. You may find similarities between the Intel XDK configuration file and that used by PhoneGap Build, but they are neither compatible nor interchangeable. If you have an existing PhoneGap project you will need to create an Intel XDK configuration file first before you build your project with the Intel XDK.

For each HTML5+Cordova project, you can select the Cordova CLI version under Build Settings in the Projects tab. As of release 1816 of the Intel XDK, the default and recommended version to use in the Build Settings section is 4.1.2. Cordova CLI 4.1.2 refers to the version number of the Cordova command-line interface. The precise Cordova platform versions that are “pinned” to CLI 4.1.2 are can be found here.

The intelxdk.config.<platform>.xml File

The intelxdk.config.<platform>.xml file controls the behavior and application specific properties of the Intel XDK Cordova and Crosswalk build targets. This file follows the W3C Packaged Web Apps (Widgets) specification. The name space used for settings unique to the Intel XDK build system are still under development and; therefore, are subject to change.

NOTE: intelxdk.config.<platform>.xml files are automatically generated by a GUI interface on the Projects tab (beginning with release 1199 of the Intel XDK). A user-editable intelxdk.config.additions.xml configuration file is provided as a way to handle special case configuration options that are not dealt with by the build GUI interface. The features described in this document can be used within that intelxdk.config.additions.xml configuration file.

A reference intelxdk.config.xml file is maintained on github to show you most of the preferences that can be included in a build configuration file. Since the Intel XDK Projects tab generates the intelxdk.config.<platform>.xml files automatically, this file should be considered as a reference for understanding what options can be added to your intelxdk.config.additions.xml configuration file.

The intelxdk Namespace

A namespace is required to designate this file for use by the Intel XDK. The following namespace entry (which is subject to change) must be present in the intelxdk.config.xml file if any intelxdk namespace entries are used in the configuration file.

xmlns:intelxdk="http://xdk.intel.com/ns/v1"

Options Common to All Cordova Platforms

For a full list of Cordova supported settings see the Apache Cordova config.xml File Documentation.  The settings described below are either modifications of or additions to the standard Cordova settings designed for use with the Intel XDK build system.

Standard Cordova Plugins

The plugin package names listed below represent the available "core" Cordova APIs. These plugins can be selected via the Projects tab GUI and automatically included in the respective platform build config files.

Plugin Name Plugin Value Notes
Accelerometer org.apache.cordova.device-motion  
Camera org.apache.cordova.camera  
Capture org.apache.cordova.media-capture  
Compass org.apache.cordova.device-orientation  
Connection org.apache.cordova.network-information  
Contacts org.apache.cordova.contacts  
Device org.apache.cordova.device  
Events (battery status) org.apache.cordova.battery-status  
File org.apache.cordova.file  
Geolocation org.apache.cordova.geolocation  
Globalization org.apache.cordova.globalization  
InAppBrowser org.apache.cordova.inappbrowser Plugin version 0.3.0 is recommended.
Media org.apache.cordova.media Requires the Cordova File plugin.
Dialogs (notification) org.apache.cordova.dialogs  
Vibration (notification) org.apache.cordova.vibration  
Splash Screen org.apache.cordova.splashscreen  


See the Cordova API Reference Documentation for API and platform details regarding the "core" Cordova API plugins.

If you do not specify a plugin version the latest available version will be included by the build system. In some cases, this may result in problems or incompatibilities. The notes section indicates a recommended version where problems are known to exist and a known good version should be specified, instead of using the latest version of the plugin.

Intel XDK Plugins

The plugin package names listed below represent the available Intel XDK APIs. These plugins can be selected via the Projects tab GUI and automatically included in the respective platform build config files.

Plugin Name Plugin Value Notes
Base intel.xdk.base  
Accelerometer intel.xdk.accelerometer  
Audio intel.xdk.audio  
Cache intel.xdk.cache  
Camera intel.xdk.camera  
Contacts intel.xdk.contacts  
Device intel.xdk.device Android and Crosswalk, only. Other platforms under development.
Display intel.xdk.display  
Facebook intel.xdk.facebook Requires the FBAPPID parameter == Facebook Application ID.
Android, only. Other platforms under development.
File intel.xdk.file  
Geolocation intel.xdk.geolocation  
Notification intel.xdk.notification  
Player intel.xdk.player  

See the Intel XDK API Reference Documentation for API and platform details about the Intel XDK API plugins.

NOTE: Some plugins (Cordova, Intel XDK and third-party) include device permissions that will automatically be added to your application, and must be acknowledged by the end user of your application during installation on their mobile device, or when they run your application (specific behavior is platform-dependent). Including unneeded plugins may result in an inappropriate list of permissions for your app. The specific permissions associated with a plugin, if any, vary as a function of the platform.

Build Config Directives Specific to the Intel XDK

See Adding Plugins to Your Intel® XDK Cordova App for instructions on how to use third-party Cordova plugins as a way of extending your app's JavaScript API for access to unique device and platform features.

Including Cordova Plugins
The Plugin tag allows you to add predefined plugins to your application at build time. It is constructed as follows:
<intelxdk:plugin intelxdk:name="<NAME>" intelxdk:value="<VALUE>" intelxdk:version=”<VERSION>” />
where:
  • <NAME> is the description of the plugin.
  • <VALUE> is the package name or git repository representing the plugin.
  • <VERSION> is the [optional] version of the plugin (see next section for more info regarding plugin versions).
Some plugins may require, or optionally allow, parameters as part of their installation. Any parameters required by a plugin are specific to that plugin and are documented in that plugin’s documentation. Plugin parameters are added by using the <param> tag:
<intelxdk:plugin intelxdk:name="<NAME>" intelxdk:value="<VALUE>" >
    <intelxdk:param intelxdk:name="<PARMNAME>" intelxdk:value="<PARMVALUE>" />
    .....
    <intelxdk:param intelxdk:name="<PARMNAME>" intelxdk:value="<PARMVALUE>" />
</intelxdk:plugin>
Specifying Custom Icons
The icon tag provides a mechanism to add launch (home screen) icons to your application.
<icon platform="<PLATFORM>" src="<SRC>" density="<DENSITY>" height="<HEIGHT>" width="<WIDTH>" />
where:
  • <PLATFORM> indicates for which platform the launch icon will be applied. Valid platforms are android, ios, windows8 and wp8. If this property is not supplied, a default icon is provided by the build system.
  • <SRC> indicates the path of the icon image file relative to the SOURCE DIRECTORY in your project (see the Projects tab in the Intel XDK).
  • <DENSITY> indicates the resolution of the icon image file. This property is required for and only used by Android. Valid values are xhdpi,hdpi, mdpi, and ldpi.
  • <HEIGHT> indicates the height of the icon image file in pixels. This property is required for iOS and optional for other platforms.
  • <WIDTH> indicates the width of the icon image file in pixels. This property is required for iOS and optional for other platforms.
Details regarding icon dimensions, sizes and image types can be found on the respective platform-specific pages (links provided below, in the next section).
Including Custom Splash Screens
The splash tag gives you a way to add a custom splash screen to your application. This static image will be displayed during app initialization for a preset period of time following initialization, or until your application calls the navigator.splashscreen.hide() function, whichever comes first.
<splash platform="<PLATFORM>" src="<SRC>" density="<DENSITY>" width="<WIDTH>" height="<HEIGHT>" orientation="<ORIENTATION>" />
where:
  • <PLATFORM> indicates for which platform the splash screen image will be applied. Valid platforms are android, ios, windows8, and wp8. If this property is not supplied, a default image is provided by the build system.
  • <SRC> indicates the path of the splash screen image file relative to the SOURCE DIRECTORY in your project (see the Projects tab in the Intel XDK).
  • <DENSITY> indicates the resolution of the splash screen image file. This property is required for and only used by Android. Valid values are xhdpi, hdpi, mdpi, and ldpi.
  • <WIDTH> indicates the width of the splash screen image file in pixels. This property is required for iOS and optional for other platforms.
  • <HEIGHT> indicates the height of the splash screen image file in pixels. This property is required for iOS and optional for other platforms.
  • <ORIENTATION> indicates the orientation of the splash screen image. Valid values are "portrait" and "landscape." This property is currently only used by Android platforms.
Details regarding splash screen image dimensions, sizes and file types can be found on the respective platform-specific pages (links provided below, in the next section).

Platform Specific Options

Each Cordova build platform may have additional build options that can be added to the config file. These options are specific to that platform and have no impact on other target platforms.

Follow these links for details regarding platform-specific build options:




For more complete information about compiler optimizations, see our Optimization Notice.