Repository files navigation

• Apache Cordova is an open-source mobile development framework. It allows you to use standard web technologies - HTML5, CSS3, and JavaScript for cross-platform development. Applications execute within wrappers targeted to each platform, and rely on standards-compliant API bindings to access each device's capabilities such as sensors, data, network status, etc.
• Use Apache Cordova if you are:
• a mobile developer and want to extend an application across more than one platform, without having to re-implement it with each platform's language and tool set.
• a web developer and want to deploy a web app that's packaged for distribution in various app store portals.
• a mobile developer interested in mixing native application components with a WebView (special browser window) that can access device-level APIs, or if you want to develop a plugin interface between native and WebView components.

Create your first Cordova app

This guide shows you how to create a JS/HTML Cordova application and deploy them to various native mobile platforms using the cordova command-line interface (CLI). For detailed reference on Cordova command-line, review the CLI reference.

Installing the Cordova CLI

The Cordova command-line tool is distributed as an npm package.

To install the cordova command-line tool, follow these steps:

Download and install Node.js. On installation you should be able to invoke node and npm on your command line.

(Optional) Download and install a git client, if you don't already have one. Following installation, you should be able to invoke git on your command line. The CLI uses it to download assets when they are referenced using a url to a git repo.

Install the cordova module using npm utility of Node.js. The cordova module will automatically be downloaded by the npm utility.

on OS X and Linux:

$ sudo npm install -g cordovaOn OS X and Linux, prefixing the npm command with sudo may be necessary to install this development utility in otherwise restricted directories such as /usr/local/share. If you are using the optional nvm/nave tool or have write access to the install directory, you may be able to omit the sudo prefix. There are more tips available on using npm without sudo, if you desire to do that.

on Windows:

C:>npm install -g cordovaThe -g flag above tells npm to install cordova globally. Otherwise it will be installed in the node_modules subdirectory of the current working directory.

Following installation, you should be able to run cordova on the command line with no arguments and it should print help text.

Create the App

Go to the directory where you maintain your source code, and create a cordova project:

$ cordova create hello com.example.hello HelloWorldThis creates the required directory structure for your cordova app. By default, the cordova create script generates a skeletal web-based application whose home page is the project's www/index.html file.

Customize Icons

This section shows how to configure an application's icon for various platforms. Documentation about splash screen images can be found in the Cordova-Plugin-Splashscreen documentationSplashscreen plugin docs.

Configuring Icons in the CLI

When working in the CLI you can define application icon(s) via the<icon> element (config.xml).If you do not specify an icon, the Apache Cordova logo is used.

<iconsrc="res/ios/icon.png"platform="ios"width="57"height="57"density="mdpi"/>

Attributes	Description
src	Required Location of the image file, relative to your project directory.
platform	Optional Target platform
width	Optional Icon width in pixels
height	Optional Icon height in pixels
target	Optional Destination filename for the image file and all its MRT companions

The following configuration can be used to define a single default iconwhich will be used for all platforms.

<iconsrc="res/icon.png"/>

For each platform, you can also define a pixel-perfect icon set to fitdifferent screen resolutions.

Android

On Android, instead of using a single image for an icon, you can use two images (background and foreground) to create anAdaptive Icon.

Attributes	Description
background	Required for Adaptive Location of the image (png or vector) relative to your project directory, or color reference
foreground	Required for Adaptive Location of the image (png or vector) relative to your project directory, or color reference
density	Required Specified icon density

Adaptive Icons

To use the adaptive icons thebackground andforeground attributes must be defined in place of thesrc attribute. Thesrc attribute is not used for adaptive icons.

Adaptive Icon with Images:

<platformname="android"><iconbackground="res/icon/android/ldpi-background.png"density="ldpi"foreground="res/icon/android/ldpi-foreground.png"/><iconbackground="res/icon/android/mdpi-background.png"density="mdpi"foreground="res/icon/android/mdpi-foreground.png"/><iconbackground="res/icon/android/hdpi-background.png"density="hdpi"foreground="res/icon/android/hdpi-foreground.png"/><iconbackground="res/icon/android/xhdpi-background.png"density="xhdpi"foreground="res/icon/android/xhdpi-foreground.png"/><iconbackground="res/icon/android/xxhdpi-background.png"density="xxhdpi"foreground="res/icon/android/xxhdpi-foreground.png"/><iconbackground="res/icon/android/xxxhdpi-background.png"density="xxxhdpi"foreground="res/icon/android/xxxhdpi-foreground.png"/></platform>

Note: In this example, the foreground image will also be used as the fallback icon for Android devices that do not support the adaptive icons. The fallback icon can be overridden by setting the src attribute.

Adaptive Icon with Vectors:

<platformname="android"><iconbackground="res/icon/android/ldpi-background.xml"density="ldpi"foreground="res/icon/android/ldpi-foreground.xml"src="res/android/ldpi.png"/><iconbackground="res/icon/android/mdpi-background.xml"density="mdpi"foreground="res/icon/android/mdpi-foreground.xml"src="res/android/mdpi.png"/><iconbackground="res/icon/android/hdpi-background.xml"density="hdpi"foreground="res/icon/android/hdpi-foreground.xml"src="res/android/hdpi.png"/><iconbackground="res/icon/android/xhdpi-background.xml"density="xhdpi"foreground="res/icon/android/xhdpi-foreground.xml"src="res/android/xhdpi.png"/><iconbackground="res/icon/android/xxhdpi-background.xml"density="xxhdpi"foreground="res/icon/android/xxhdpi-foreground.xml"src="res/android/xxhdpi.png"/><iconbackground="res/icon/android/xxxhdpi-background.xml"density="xxxhdpi"foreground="res/icon/android/xxxhdpi-foreground.xml"src="res/android/xxxhdpi.png"/></platform>

Note: In this example, the src attribute must be defined when then foreground attribute is defined with a vector or color.

Adaptive Icon with Colors:

Create ares/values/colors.xml resource file in your project directory to store the app's color definitions.

<?xml version="1.0" encoding="utf-8"?><resources><colorname="background">#FF0000</color></resources>

In theconfig.xml, we will addresource-file to copy thecolors.xml into the approprate location so that the colors are available during build time.

<platformname="android"><resource-filesrc="res/values/colors.xml"target="/app/src/main/res/values/colors.xml"/>
<iconbackground="@color/background"density="ldpi"foreground="res/icon/android/ldpi-foreground.png"/><iconbackground="@color/background"density="mdpi"foreground="res/icon/android/mdpi-foreground.png"/><iconbackground="@color/background"density="hdpi"foreground="res/icon/android/hdpi-foreground.png"/><iconbackground="@color/background"density="xhdpi"foreground="res/icon/android/xhdpi-foreground.png"/><iconbackground="@color/background"density="xxhdpi"foreground="res/icon/android/xxhdpi-foreground.png"/><iconbackground="@color/background"density="xxxhdpi"foreground="res/icon/android/xxxhdpi-foreground.png"/></platform>

Standard Icons

<platformname="android"><!--            ldpi    : 36x36 px            mdpi    : 48x48 px            hdpi    : 72x72 px            xhdpi   : 96x96 px            xxhdpi  : 144x144 px            xxxhdpi : 192x192 px        --><iconsrc="res/android/ldpi.png"density="ldpi"/><iconsrc="res/android/mdpi.png"density="mdpi"/><iconsrc="res/android/hdpi.png"density="hdpi"/><iconsrc="res/android/xhdpi.png"density="xhdpi"/><iconsrc="res/android/xxhdpi.png"density="xxhdpi"/><iconsrc="res/android/xxxhdpi.png"density="xxxhdpi"/></platform>

See Also

• Android icon guide
• Android - Supporting multiple screens

Browser

Icons are not applicable to the Browser platform.

iOS

<platformname="ios"><!-- iOS 8.0+ --><!-- iPhone 6 Plus  --><iconsrc="res/ios/icon-60@3x.png"width="180"height="180"/><!-- iOS 7.0+ --><!-- iPhone / iPod Touch  --><iconsrc="res/ios/icon-60.png"width="60"height="60"/><iconsrc="res/ios/icon-60@2x.png"width="120"height="120"/><!-- iPad --><iconsrc="res/ios/icon-76.png"width="76"height="76"/><iconsrc="res/ios/icon-76@2x.png"width="152"height="152"/><!-- Spotlight Icon --><iconsrc="res/ios/icon-40.png"width="40"height="40"/><iconsrc="res/ios/icon-40@2x.png"width="80"height="80"/><!-- iOS 6.1 --><!-- iPhone / iPod Touch --><iconsrc="res/ios/icon.png"width="57"height="57"/><iconsrc="res/ios/icon@2x.png"width="114"height="114"/><!-- iPad --><iconsrc="res/ios/icon-72.png"width="72"height="72"/><iconsrc="res/ios/icon-72@2x.png"width="144"height="144"/><!-- iPad Pro --><iconsrc="res/ios/icon-167.png"width="167"height="167"/><!-- iPhone Spotlight and Settings Icon --><iconsrc="res/ios/icon-small.png"width="29"height="29"/><iconsrc="res/ios/icon-small@2x.png"width="58"height="58"/><iconsrc="res/ios/icon-small@3x.png"width="87"height="87"/><!-- iPad Spotlight and Settings Icon --><iconsrc="res/ios/icon-50.png"width="50"height="50"/><iconsrc="res/ios/icon-50@2x.png"width="100"height="100"/><!-- iPad Pro --><iconsrc="res/ios/icon-83.5@2x.png"width="167"height="167"/></platform>

See Also

• App Icons on iPad and iPhone

Windows

For Windows the recommended approach to define application icons is to use thetarget attribute.

<platformname="windows"><iconsrc="res/windows/storelogo.png"target="StoreLogo"/><iconsrc="res/windows/smalllogo.png"target="Square30x30Logo"/><iconsrc="res/windows/Square44x44Logo.png"target="Square44x44Logo"/><iconsrc="res/windows/Square70x70Logo.png"target="Square70x70Logo"/><iconsrc="res/windows/Square71x71Logo.png"target="Square71x71Logo"/><iconsrc="res/windows/Square150x150Logo.png"target="Square150x150Logo"/><iconsrc="res/windows/Square310x310Logo.png"target="Square310x310Logo"/><iconsrc="res/windows/Wide310x150Logo.png"target="Wide310x150Logo"/></platform>

wheresrc is the path to the icon which needs to be added.

The Windows platform handles MRT icons automatically, so if you specifysrc="res/windows/storelogo.png" the following files will be copied into the application'simages folder:res/windows/storelogo.scale-100.png,res/windows/storelogo.scale-200.png, etc.

TODO Define what MRT is.

Thetarget attribute specifies the base name for the resultant icons. For every icon file, its destination filename is calculated astarget + '.' + MRT_qualifiers + extension(src). For the icons to display properly in the application, everytarget value should be one of the icon filenames defined in the application's.appxmanifest file.

Summarizing the above... using thetarget attribute it is possible to:

• define a group of icons for different device scale factors using a single<icon ...> element, for example:xml<icon src="res/windows/AppListIcon.png" />which is equivalent to the following lines:xml<icon src="res/windows/Square44x44Logo.scale-100.png" width="44" height="44" /><icon src="res/windows/Square44x44Logo.scale-150.png" width="66" height="66" /><icon src="res/windows/Square44x44Logo.scale-200.png" width="88" height="88" /><icon src="res/windows/Square44x44Logo.scale-240.png" width="106" height="106" />
• define icons with scale factors other thanscale-100 andscale-240 (and any other MRT qualifiers)

Although it is not recommended, it is also possible to define icons using thewidth andheight attributes:

<platformname="windows"><iconsrc="res/windows/logo.png"width="150"height="150"/><iconsrc="res/windows/smalllogo.png"width="30"height="30"/><iconsrc="res/windows/storelogo.png"width="50"height="50"/><iconsrc="res/windows/Square44x44Logo.scale-100.png"width="44"height="44"/><iconsrc="res/windows/Square44x44Logo.scale-240.png"width="106"height="106"/><iconsrc="res/windows/Square70x70Logo.scale-100.png"width="70"height="70"/><iconsrc="res/windows/Square71x71Logo.scale-100.png"width="71"height="71"/><iconsrc="res/windows/Square71x71Logo.scale-240.png"width="170"height="170"/><iconsrc="res/windows/Square150x150Logo.scale-240.png"width="360"height="360"/><iconsrc="res/windows/Square310x310Logo.scale-100.png"width="310"height="310"/><iconsrc="res/windows/Wide310x150Logo.scale-100.png"width="310"height="150"/><iconsrc="res/windows/Wide310x150Logo.scale-240.png"width="744"height="360"/></platform>

See Also:

• Windows 10 platform guidelines for icons.
• Windows 8.1 tiles and icons sizes

Electron

Customizing the Application's Icon

Customized icon(s) can be declared with the<icon> element(s) in theconfig.xml file. There are two types of icons that can be defined, the application icon and the package installer icon. These icons should be defined in the Electron's platform node<platform name="electron">.

One icon can be used for the application and installer, but this icon should be at least512x512 pixels to work across all operating systems.

Notice: If a customized icon is not provided, the Apache Cordova default icons are used.

Notice: macOS does not display custom icons when usingcordova run. It defaults to the Electron's icon.

<platformname="electron"><iconsrc="res/electron/icon.png"/></platform>

You can supply unique icons for the application and installer by setting thetarget attribute. As mentioned above, the installer image should be512x512 pixels to work across all platforms.

<platformname="electron"><iconsrc="res/electron/app.png"target="app"/><iconsrc="res/electron/installer.png"target="installer"/></platform>

For devices that support high-DPI resolutions, such as Apple's Retina display, you can create a set of images with the same base filename but suffix with its multiplier.

For example, if the base image's filenameicon.png and is the standard resolution, thenicon@2x.png will be treated as a high-resolution image that with a DPI doubled from the base.

• icon.png (256px x 256px)
• icon@2x.png (512px x 512px)

If you want to support displays with different DPI densities at the same time, you can put images with different sizes in the same folder and use the filename without DPI suffixes. For example:

<platformname="electron"><iconsrc="res/electron/icon.png"/><iconsrc="res/electron/icon@1.5x.png"/><iconsrc="res/electron/icon@2x.png"/><iconsrc="res/electron/icon@4x.png"target="installer"/></platform>