Using the Crosswalk for Android Build Option

IMPORTANT: As of February, 2017, the Crosswalk Project has been retired. Crosswalk 23 was the last version of the Crosswalk library produced by the Crosswalk team. You can continue to build for the Crosswalk library using Cordova CLI or PhoneGap Build, but no further updates to the Crosswalk library will occur beyond version 23 (FYI: the Crosswalk 23 library for Android is based on the Chromium 53 runtime release).

This article provides an overview of the information you need to get started building mobile Cordova apps for Android using the Crosswalk WebView. Read Crosswalk Overview for more details regarding the Crosswalk runtime and API and Why Use Crosswalk? to understand the tradeoffs between using the Crosswalk WebView versus the built-in Android WebView.

Creating an Android-Crosswalk App

Android-Crosswalk apps are like any other HTML5 Cordova mobile app, they use the same source code that you use for your Cordova for Android, iOS and Windows platforms and they use Cordova plugins to extend your HTML5 APIs beyond the "standard" HTML5 APIs. Android-Crosswalk provides two basic advantages over building just for Android:

  • A high-performance runtime (aka WebView), when compared to the native Android runtime.
  • Consistent runtime features on all Android devices, which is not possible with the native Android runtime.

To convert your Android app to an Android-Crosswalk app simply select the "Optimize with Crosswalk" checkbox in the Android Build Settings on the Projects tab.

Existing HTML5 applications will run on Android-Crosswalk, including mobile applications that use standard Apache Cordova* APIs and plugins, with little or no changes required. The Crosswalk HTML5 runtime is based on, and compatible with, the same HTML5 runtime found in the desktop Chrome browser.

Debugging and Previewing on Device

Use the Debug tab to preview your app in the Android-Crosswalk WebView. Follow the on-screen instructions to connect your Android 4.0 (or higher) device via USB to your development system. If you only want to preview your app press the "launch" icon (the play symbol). You can debug your app from this tab using the "bug" icon.

The Debug tab ALWAYS runs your app inside an Android-Crosswalk WebView on your USB-attached Android device, for the most accurate rendition of a built Android-Crosswalk application. Android-Crosswalk builds are limited to use on Android 4.0 and higher platforms.

If you preview your app using the Test tab, or by using Intel App Preview directly, your app runs in the native Android WebView on your device, it does NOT run inside the Android-Crosswalk WebView when run in App Preview.

Debugging and Previewing in the Intel XDK

If you have an Android 4.0 (or higher) device, it is easiest and most accurate to preview and debug using the Debug tab. If you do not have access to an appropriate Android device you can debug your Android-Crosswalk app in the Simulate tab. The Simulate tab employs a Chromium* HTML5 runtime, which supports many of the same APIs as Crosswalk, but not all. In particular, the simulator does not support the following Android-Crosswalk APIs:

  • Presentation
  • Vibration
  • Device Orientation and Acceleration

Building an Android-Crosswalk APK

When you select "Optimize with Crosswalk" in the Build Settings section of the Projects tab, the Intel XDK build system packages your Android app with the Android-Crosswalk runtime. 

Android-Crosswalk builds created with the Intel XDK are limited to use on Android platforms. Use the iOS build option to create an iOS IPA file, etc. When you choose the "Optimize with Crosswalk" option you are building a standard Android APK.

Keep in mind the following when building an Android-Crosswalk app:

  • There are two options available to build your Android-Crosswalk app: embedded and shared. It is important to understand the pros and cons of these options. More details are available in Choosing Crosswalk Build Options: Shared or Embedded.

  • When you choose the embedded build option, the build server generates two APKs: one for x86 devices and one for ARM architecture devices; this is done automatically for you. The resulting APKs will only run on devices that match the corresponding CPU architecture (the x86 APK runs on x86 devices and the ARM APK runs on ARM devices). You must submit both APKs when publishing to an Android app store, in order to reach the maximum audience and minimize issues associated with your users downloading an incorrect APK image. See Submitting Multiple Crosswalk APKs to the Google Play Store* for details about submitting multiple APKs. If you follow this procedure the Android store will automatically deliver the correct APK to your end users' devices.

  • Select the plugins corresponding to the Cordova APIs your app needs using the Plugin Manager on the Projects tab. The Android-Crosswalk build system uses standard Cordova plugins, they are not included automatically when you select the "Optimize for Crosswalk" build setting. Documentation for the core Cordova plugins and their corresponding APIs are available on the Cordova documentation website.

  • Specify the specific version of Crosswalk you wish to use in the Android-Crosswalk Build Settings section of the Projects tab (the version applies only to the embedded build option). The Crosswalk Version pulldown determines which version of the Crosswalk HTML5 runtime will be included with your app. This option also directs the Debug tab regarding how to build a custom debug module for preview and debug.

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