Skip to content

Latest commit

 

History

History
274 lines (213 loc) · 9.95 KB

cordova.md

File metadata and controls

274 lines (213 loc) · 9.95 KB

Using Cordova

Cordova is the platform bridge allowing you to build mobile applications using web technologies.

It comes with its own CLI to manage compilation, platforms and plugins that is usually installed globally.

However, we chose to use a local install for Cordova CLI, to allow version locking in package.json. This way, you can use a different Cordova CLI version for each of your mobile projects, independently of the globally installed version. This is also necessary as new updates often break project compilation.

You can manage Cordova CLI updates like any NPM package.

If you do not want this behavior and prefer using your global Cordova install, simply run:

<% if (props.packageManager === 'yarn') { -%>
yarn remove cordova
yarn global add cordova
<% } else { -%>
npm remove cordova --save-dev
npm install -g cordova
<% } -%>

The NPM scripts will then use the global version instead of a local one.

Platform notes

Each Cordova platform may require specific tools to be installed for the command to work properly. You can check anytime if your system meets the requirements for a given platform with:

<% if (props.packageManager === 'yarn') { -%>
yarn run cordova requirements <ios|android>
<% } else { -%>
npm run cordova -- requirements <ios|android>
<% } -%>

iOS

To build the iOS version, you need to install XCode.

To allow launching your app in simulator or device from command line, you need also:

<% if (props.packageManager === 'yarn') { -%>
yarn global add ios-sim
yarn global add ios-deploy
<% } else { -%>
npm install -g ios-sim
npm install -g ios-deploy
<% } -%>

See Cordova documentation for additional information.

Android

To build the Android version, you need to install the Android SDK.

See Cordova documentation for additional information.

Common tasks

Restoring platforms and plugins after a checkout

<%= props.packageManager %> run cordova:prepare

This will restore all your platforms and plugins according to your config.xml file.

Adding a platform

<% if (props.packageManager === 'yarn') { -%>
yarn run cordova platform add <ios|android>
<% } else { -%>
npm run cordova -- platform add <ios|android>
<% } -%>

Adding a plugin

<% if (props.packageManager === 'yarn') { -%>
yarn run cordova plugin add <plugin-name>
<% } else { -%>
npm run cordova -- plugin add <plugin-name>
<% } -%>

Running the application

<% if (props.packageManager === 'yarn') { -%>
yarn run cordova:run <ios|android> [--device]
<% } else { -%>
npm run cordova:run <ios|android> [-- --device]
<% } -%>

Run your application in specified platform emulator or device if you add the --device option.

Packaging and signing apps

To create properly signed application packages for store publication, you have to configure your app provisioning in the build.json file.

Here is an example configuration:

{
  "ios": {
    "release": {
      "developmentTeam": "your_team_id",
      "codeSignIdentity": "iPhone Distribution"
    }
  },
  "android": {
    "release": {
      "keystore": "sign/your_android.keystore",
      "storePassword": "",
      "alias": "your_key",
      "password" : "your_password",
      "keystoreType": ""
    }
  }
}

This information will be used by the <%= props.packageManager %> run cordova:build task to generate production packages.

You can find more detailed documentation in the iOS signing guide or Android signing guide.

Updating plugins

To update a single plugin:

<% if (props.packageManager === 'yarn') { -%>
yarn run cordova plugin update <plugin_name>
<% } else { -%>
npm run cordova -- plugin update <plugin_name>
<% } -%>

Cordova does not include a mass update mechanism for plugins, but you can use the cordova-check-plugins tool:

<% if (props.packageManager === 'yarn') { -%>
yarn global add cordova-check-plugins
<% } else { -%>
npm install -g cordova-check-plugins
<% } -%>

Then run the following commands to perform an interactive update of outdated plugins and save the new versions:

cordova-check-plugins --update=interactive
<% if (props.packageManager === 'yarn') { -%>
yarn run cordova plugin save
<% } else { -%>
npm run cordova -- plugin save
<% } -%>

Updating platforms

<%= props.packageManager %> run cordova platform update <ios|android>

Icon and splash screen

Take a look at the Cordova documentation to know the icon formats for each platform you want to support. The same goes for the splash screen images.

To avoid the "stretched" splash screen effect on Android, you can set this preference in your config.xml:

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

You can also use 9-patch images to further control how your images should be stretched.

Using improved web views

To improve performance and/or compatibility of your app, it is possibly to customize the web view used by Cordova. This is especially useful for devices running Android 4.3 and older, as they use a slow, outdated web view.

By default we enable Ionic WKWebView on iOS.

Using Crosswalk on Android

Note: Crosswalk is not maintained anymore, and have issues with cordova-android versions later than 6.3.0. If you need Crosswalk to support older Android versions, stick to cordova-android@6.3.0.

The Crosswalk plugin allows you to embed a Chromium-based web view in your app instead of the Android system web view.

This allows to greatly improve compatibility and performance on systems using older or customized web views, and use modern browser APIs, at the cost of increased app size and memory footprint.

To add or remove Crosswalk:

<% if (props.packageManager === 'yarn') { -%>
yarn run cordova plugin <add|remove> cordova-plugin-crosswalk-webview
<% } else { -%>
npm run cordova -- plugin <add|remove> cordova-plugin-crosswalk-webview
<% } -%>

By default, build commands will generate separate packages for x86 ad ARM architecture, to reduce download sizes. This behavior can be change to build a single package by modifying this line in config.xml:

<variable name="XWALK_MULTIPLEAPK" value="true" /> <!-- Change to "false" to build single APK -->

Using WKWebView on iOS

The Ionic WebView plugin makes use of the new WKWebView instead of UIWebView, enabling a huge increase in JavaScript performance.

The new web view is only active on iOS 9+ (with a fallback for older version), and has some limitations (see the plugin doc on github for more details), the biggest one being:

  • To perform any XHR request in your app, CORS must be enabled on your server.

To add or remove WKWebView:

<% if (props.packageManager === 'yarn') { -%>
yarn run cordova plugin <add|remove> cordova-plugin-ionic-webview
<% } else { -%>
npm run cordova -- plugin <add|remove> cordova-plugin-ionic-webview
<% } -%>

Security considerations

On a new project, external domain navigation is disabled but loading resources from any domain is enabled by default.

Although XHRs to all domains are enabled in the default whitelist configuration, it doesn't apply when using the ionic-webview cordova plugin versions 2+. Therefore, if your app is a full-stack app or it needs to access any APIs, you'll need to either be sure the CORS headers allow the origin localhost:8080, or remove the ionic-webview plugin. You can find more details about this in the ionic webview documentation. Note that this applies to both ios and android builds.

Before building for production, you should consider restricting domain access to improve your app security. You can find documentation on this regard in the Cordova whitelist guide.

To go further in security considerations, you should consider adding a Content Security Policy in your index.html.

For additional general security information, you can take a look at the Cordova security guide

Development hints

Android build behind corporate proxy with custom SSL certificate

If you use a corporate proxy that intercepts HTTPS requests with a custom certificate, you may encounter issues like peer not authenticated errors. To fix this, you need to add this certificate to the Java trusted certificate store.

Make sure you have write access to your JRE (you may need sudo on Linux and OS X), then use the keytool utility to import it:

keytool -importcert -alias <an_alias> -keystore <java_home>/jre/lib/security/cacerts -file <certificate_file>

The default password for the cacerts file is changeit.

On OS X >10.9, you can use this command to find your java home:

/usr/libexec/java_home

The cacerts file is then located under there in jre/lib/security