Using Remote Chrome DevTools to Debug Android* Cordova* Apps

Using the Google* Chrome browser on your workstation with Chrome* DevTools running on your Android device (remote CDT) is a very powerful debugging environment. Using remote CDT, you can debug a built app as it runs directly on your device. Nearly 100 percent of the functionality of Chrome DevTools is available to you; it's as if you are debugging a browser app on your local workstation.

This scenario works for three situations:

  • An Android-built app installed on a USB-connected Android 4.4+ device, with developer options enabled.
  • Android Crosswalk-built app installed on a USB-connected Android 4.1+ device, with developer options enabled.
  • Running your app in Android App Preview app installed on a USB-connected Android 4.4+ device, with developer options enabled.

The differing 4.1+ and 4.4+ version requirements (in the bullets above) are not typos. Remote debug of an Android WebView requires at least Android 4.4 on the device, whereas remote debug of an Android Crosswalk WebView works on devices with Android 4.1 (or greater). The Google Chrome Remote Debugging WebViews document specifically states the Android 4.4 requirement; however, this restriction does not apply to remote debug of an Android Crosswalk WebView app (an app built with Crosswalk).

Before attempting to use this debug technique, confirm that you have USB debug properly enabled on your workstation and your Android device. Installing the Android USB debug driver on Windows development systems can be particularly difficult; follow Installing the Android Debug Bridge (ADB) USB Driver on a Windows Computer for help with this process.

You may encounter issues with adb on your workstation, especially in situations where there are multiple (competing) versions of adb. The Intel XDK ships with a copy of adb, as does the Google Chrome browser, the Firefox browser, Android Studio, Eclipse and many other Android development and debug tools you might have installed on your system. See Android Debug Bridge and What do I do if Intel XDK stops detecting my Android* device? for additional help with the adb utility.

The key to being able to remotely debug your built application using Chrome DevTools is to build and install a "debuggable" APK onto your Android device.

  • If you are using Cordova CLI, use the "cordova build --debug" command to create a debuggable APK.

  • If you are using PhoneGap Build, use the "No key selected" signing option to create a debuggable APK.

The Intel XDK <preference name="debuggable" value="true" /> option that was used by the Intel XDK build system is obsolete. This tag was unique to the Intel XDK build system (which has been retired) and is ignored by PhoneGap Build and Cordova CLI.

Once your debuggable app is built, do the following:

  • Install the "debuggable" app onto your Android device.
  • Attach your Android device to your workstation via USB.
  • Start the app on your Android device.
  • Start desktop Chrome on your workstation.
  • Type chrome://inspect in the desktop Chrome URL address bar.
  • Locate your app in the list of debuggable WebViews (see the image).
  • Push the "inspect" link under your app.

The instructions above assume you have confirmed that all the conditions necessary for a remote CDT debug session are in place:

  • developer options have been enabled on your Android device
  • USB debug drivers are installed and working on your workstation
  • there are no adb version conflicts on your workstation

The order of the instructions is flexible, you do not need to follow the steps precisely as presented above to establish a remote CDT debugging session.

Debugging a built app does not require rebuilding your app to test changes or experiment with your code. The best debugging experience will come from taking advantage of the interactive JavaScript console to redefine functions within your app and then run those redefined functions directly from the console or restart your app, in situ, using the window.location.reload() function. An example of using this technique can be seen in this video, starting at about 18:30. The video is demonstrating the use of the weinre debugger, but the debugging techniques can also be applied to remote CDT and remote Web Inspector when debugging a built app.

For additional information on how to use Chrome DevTools to debug your HTML5 app, see Chrome DevTools on the Google Developers portal.

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