Using the Crosswalk for Android Build Option

You can create, preview, debug, profile and package your Android* Crosswalk* applications all from within the Intel® XDK; there is no need to install any additional software. 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

Crosswalk applications are like any other HTML5 Cordova mobile app, they use the same source code that you use to build for iOS, Windows and other Cordova platforms and use standard 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).

You have several options available to create a new Android application that uses the Crosswalk webview:

  • Use "Templates" and then add your own code.
  • Use "Samples and Demos" and modify existing code and add your own code.

Many existing HTML5 application will run on Android Crosswalk, including mobile applications that use standard Apache Cordova* APIs and plugins.

Debugging and Previewing on Device

Use the Debug tab to preview your app in the Crosswalk webview. Follow the on-screen instructions to connect your Android 4.x (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. And use the Profile tab to profile your app's CPU and memory usage.

The Debug and Profile tabs ALWAYS run your app inside a Crosswalk webview on your USB-attached Android device, for the most accurate rendition of a built Android Crosswalk application. Crosswalk builds are limited to use on Android 4.x and higher platforms.

If you preview your app using the Test tab, or by using App Preview directly, your app runs in the native Android webview on your device, it will NOT run inside the Crosswalk webview when previewed using this approach.

Debugging and Previewing in the Intel XDK

If you have an Android 4.x (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 Crosswalk app in the Emulate tab. The Emulate tab employs a modern Chromium* web runtime, which supports many of the same APIs as Crosswalk, but not all of them. In particular, the emulator does not support the following Crosswalk APIs:

  • Presentation
  • Vibration
  • Device Orientation and Acceleration

Building an Android Crosswalk APK

The Intel XDK includes an option to package your app with the Crosswalk runtime, so that it is ready to submit to an Android store. To do this, click the Build tab and select the Android Crosswalk build target.

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 build for Android Crosswalk it is not necessary to also build for Android.

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

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

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

  • Select the plugins corresponding to the Cordova APIs you are using in your application on the Projects tab. Specifics regarding Crosswalk support and exceptions for Cordova APIs can be found on the Crosswalk wiki. Documentation for the standard Cordova plugins and their corresponding APIs are available on the Cordova documentation website.

  • Specify the version of Crosswalk you wish to build for in the Android Crosswalk Build Settings section of the Projects tab (applies only to the embedded build option). The Crosswalk Version pulldown determines the version of Crosswalk (ergo, the version of the Chromium webview) that will be included with your app. This option also directs the Debug and Profile tabs regarding which version of the App Preview debug module to install onto your Android test device for preview, debug and profiling.

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