August 2018

Why current Ionic apps don’t work with Android 4.x any more - and suggested solutions

You are on this page because you have problems with your Ionic app on Android 4.x (probably Android 4.4, KitKat) and are getting this error:

Android 4.4, Application Error: Couldn’t connect to the server. (http://localhost:8080/)

Application Error
Couldn’t connect to the server.
(http://localhost:8080/)
[ OK ]

Application Error
net::ERR_CONNECTION_REFUSED
(http://localhost:8080/)
[ OK ]

Problem

Back in October 2017 Ionic introduced cordova-plugin-ionic-webview to support WKWebView in iOS apps (instead of the traditional but deprecated UIWebView) and since then added it to new Ionic apps by default. Back then this only applied to iOS.

But on July 23rd 2018 they released version 2.0 of the plugin, that also included changes to the webview used on Android. The Android webview now uses a local webserver at localhost:8080 to show your app instead of requesting the files directly from the file system.

Unfortunately this change also included this bit in the documentation:

Requirements

[…]

Android: Android 5.0+ and cordova-android 6.4+

And that is the problem: cordova-plugin-ionic-webview, which is part of any newly created or updated Ionic app, just doesn’t support Android earlier than 5.0 any more, which of course means your app will not work on Android 4.x.

To confirm that you are running a 2.x version of the plugin, use the command ionic cordova plugins.

Solutions

0. Get the problem heard

Before you do anything else, check the open Pull Requests of cordova-plugin-ionic-webview and thumbs-up any PR that adds support for older Android versions like e.g. this one. You might also want to create an issue or vote and comment on existing issues about the problem.

1. Find out if you can avoid supporting Android 4.x devices

Android 4.4 (KitKat) was released in October 31, 2013 and its continued use makes Android apps much harder to develop and support. Check the general market numbers and especially usage numbers of your own apps already in the Play Console if you might be able to drop support for Android 4.x. That would solve the problem.

2. Downgrade the webview

cordova-plugin-ionic-webview used to work on Android 4.x just fine before 2.x was released. Naturally one option is to downgrade the plugin in your app to the last version that supported Android 4.x:

ionic cordova plugin add [email protected]

Depending on how your app is built, you might have to execute this in the context of some other commands to make sure it is applied:

ionic cordova plugin rm cordova-plugin-ionic-webview
ionic cordova plugin add [email protected]
ionic cordova platforms remove android
rm -rf plugins
ionic cordova build android

Please note that of course then you are not getting any of the new features of [email protected], which includes any bug fixes or performance improvements (see a list of changes in 2.x)

Be also away that if you are using Ionic Native’s Ionic Webview wrapper, you have to uninstall it as it only works with cordova-plugin-ionic-webview >= 2.x as well.

3. Use a different webview altogether

If you are not comfortable with using [email protected], you might look into using another webview. Although I strongly do not recommend that, here are some options:

If there are any other solutions, please let me know in the comments below.