Updated as of 4/13/2015
Ionic and Crosswalk
With our latest CLI update, we’re excited to introduce the ability to package modern rendering engines within your app for Cordova, starting with Crosswalk for Android. Crosswalk provides Android developers a bundled Chrome webview for their projects, resulting in better performance and predictability!
Our team is passionate about making hybrid mobile development awesome, and we’re so grateful to our committed, enthusiastic community for helping us succeed in our mission.
Getting Started With Crosswalk
First, make sure you get the latest Ionic CLI, and then you can easily create an app, add the Android platform, and add Crosswalk to the project.
npm install ionic -g ionic start my_app cd my_app ionic browser add crosswalk ionic run android
Previous Ionic Project
npm install ionic -g cd existing_app ionic browser add crosswalk ionic run android
Specifying a version of Crosswalk
ionic browser list #Find the version of Crosswalk you want.
ionic browser add email@example.com #Install stable version 10.39.235.15.
Building for separate architectures
Update: Previously, you needed an environment variable to build multiple architectures. Due to some changes to the underlying Cordova Android library, you no longer need to specify the environment variable to build multiple APKs. This should happen by default by running
ionic build android.
If you have a device connected and run
ionic run android, it will auto detect that architecture type and only build and run for that device.
Please note that running these steps will alter your Android project, so you’ll want to use version control to handle changes from Crosswalk.
These commands should set you up with a custom Android build with Crosswalk. You can run the project as you normally would.
To confirm that it was, in fact installed, open Chrome DevTools and confirm that it says “Chrome 37” or greater.
We’d love to ask you to help out the cause by testing and giving feedback. This is your chance to help several open source projects at once: Cordova, Crosswalk, and Ionic!
10 Questions You Might Have:
We’ve put together this Q & A to answer questions you might have about Crosswalk. Please don’t hesitate to contact us if you have questions that aren’t answered here!
- What is Crosswalk?
- Crosswalk is an open source project that allows you to specify a version of Chrome to use as your web browser in Android. The compiled app will have your code hosted inside of this Chrome webview.
- Why should I use Crosswalk?
- Older versions of Android devices (4.0-4.3) use Android’s default browser, which has significantly less performance and standards compliance than modern Chrome. Using Crosswalk gives you a specific and more performant version of Chrome to use on all Android devices, in order to reduce fluctuations and fragmentation among devices.
- How does Crosswalk improve Cordova Android apps?
- By designating a specific version of Chrome, you can skip the unexpected behavior from browsers that vary from device to device. Crosswalk also provides improved performance and ease of debugging.
- What can I expect, performance and size-wise?
- How do I try it out?
npm install -g ionic
- How do I report errors?
- If you encounter any errors, please type
ionic infoand paste that information to our Ionic CLI issues on github
- If you encounter any errors, please type
- What should I look for when testing?
- Improved performance on older Android devices, with the ability to debug using Chrome DevTools.
- Testing any of the core Cordova plugins, such as Camera, GPS, etc.
- Report weird behavior while building or running the app.
- Report differences between using Crosswalk and not; for example, your splash screen no longer shows.
- How do I debug with Crosswalk / Chrome?
- Fire up Chrome DevTools and go to Chrome Inspect Devices.
- What are the architectures for Android devices, and why do they exist?
- There are two main Architectures for Android – x86 and ARM. The reason for the two is that the device providers choose to use a separate processor. With different processors, we’ll need to compile them separately. Using Crosswalk, you may specify that you want two separate builds for x86 / Arm to keep your build size down. If you make a single build, you will have to bundle both versions of Crosswalk (x86/Arm) and have a larger build size (~50-60 MB).
- Why the switch to Gradle for Android?
- The Cordova Android team has decided to move away from Ant towards more of a Gradle-based build scenario. In this upgrade, you may see alternative build messages from Gradle, instead of your normal Ant messages.
CLI Roadmap (tentative)
It’s really important to us that we keep our users informed about what we’re working on. Here’s a roadmap that covers where we’ve been and where we’re going. Thanks for joining us on the journey!
1.3 Milestones (1/7/2014 – 1/12/2015)
- Crosswalk Browser introduction & installation.
- Info command for environment-specific info.
- Error reporting from CLI – helps us respond to errors faster and be proactive about errors.
- Individual help commands – now the CLI gives more info about the individual commands
ionic help serve.
1.3.1 Milestones (1/12/2015 -1/14/2015)
- Specify a version of Crosswalk to use –
ionic browser add firstname.lastname@example.org.
- See all the browsers available to install –
ionic browser list. NOTE: Only stable releases are allowed for now.
- Fixed a bug related to
- Caching the Crosswalk downloads – once you’ve installed a version in a project, running
ionic browser add crosswalkwill not re-download the webviews.
1.3.2 Milestones (1/14/2015 – 1/23/2015)
- Quick fix for the
ionic uploadcommand – fixed an issue with the cookies from the request.
1.3.3 Milestones (1/23/2015 – onward)
- Add a release option that removes unused files and minifies/uglifies to give you smaller builds.
- Add the ability to specify Beta/Canary builds of Crosswalk.
- Provide a way to release Android builds post 4.4 without Crosswalk.
- Make using the CLI easier with tab complete.
Crosswalk Updates as of 4/13/2015
In the last month, the Ionic CLI has updated the version of Cordova Android that it uses to the latest commits. Some of these changes have caused some issues for users.
Issues running ionic platform add
Users that run
ionic platform add android after running
ionic browser add crosswalk may run into the following issue:
Plugin doesn't support this project's cordova-android version. cordova-android: 3.7.1, failed version requirement: >=4.0.0-dev
When you run
ionic browser add crosswalk, the CLI downloads Cordova Android 4.0.0-dev, along with a Cordova Crosswalk Engine plugin. The Crosswalk plugin requires Cordova Android 4.0.0 and will not work properly without it.
When you run
ionic platform add android, you are then removing Cordova Android 4.0.0 and trying to install Cordova Android 3.7.1 (if you are using the latest Cordova CLI).
Right away, this will fail, due to the Crosswalk engine plugin. If you wish to stop using the Crosswalk plugin, please run
ionic browser remove crosswalk.
If this was unintentional, simply run
ionic browser add crosswalk again to allow the CLI to install that Cordova Android 4.0.0 version. Otherwise, you can run
ionic platform add ./engine/cordova-android-c0.6.1 to freshly install the downloaded 4.0.0 version of Cordova Android.
You may also remove the Crosswalk Engine plugin. Find the name
ionic plugin ls and then
ionic plugin rm cordova-plugin-crosswalk-webview.
Issues with Crosswalk not loading external resources
Using the latest changes from Cordova Android 4.0.0, the Cordova team has removed the Whitelisting capabilities of Cordova to now reside in a whitelist plugin.
This plugin has not been released yet but is required to allow whitelisting to work properly with Cordova android 4.0.
To get around this issue, please install the plugin using this command:
ionic plugin add https://github.com/apache/cordova-plugin-whitelist.
That should temporarily get you around that issue until the Cordova team releases that plugin to the Cordova Plugin registry.