Some examples of Android PhoneGap Config Settings

This post is more than 2 years old.

One thing I don't really play a lot with are config.xml files on Android. The config.xml file is a powerful way to specify settings like icons, splash screens, and the like. You can find the high level docs for this feature here: Project Settings. A few days ago Simon MacDonald wrote up some details about new Android features and specifically called out another blog post by Joe Bowser about new config.xml settings for Android: What else is new in Cordova Android 2.4.0

I took this as an opportunity to really look at the Android-specific config.xml settings. You can see this list below (taken from the docs):

  1. useBrowserHistory (boolean, defaults to true) - set to false if you want to use the history shim that was used to work around the hashtag error present in Android 3.x prior to the history fix. (Note: This setting will be deprecated in April 2013)
  2. loadingDialog - Display a native loading dialog when loading the app. Format for the value is "Title, Message"
  3. loadingPageDialog - Display a native loading dialog when loading sub-pages. Format for the value is "Title, Message"
  4. errorUrl - Set the error page for your application. Should be located in your Android project in file://android_asset/www/
  5. backgroundColor - Set the background color for your application. Supports a four-byte hex value, with the first byte representing alpha value, and the following three bytes with standard RGB values. (i.e. 0x00000000 = Black)
  6. loadUrlTimeoutValue - How much time Cordova should wait before throwing a timeout error on the application.
  7. keepRunning (boolean, defaults to true) - Determines whether Cordova will keep running in the background or not
  8. splashscreen - The name of the file minus its extension in the res/drawable directory. If you have multiple assets, they all must share this common name in their respective directories.

Some of these made sense to me, and some made sense but I had never actually seen them in action. I played a bit with them and took some screen shots I thought I'd share with my readers.


As the docs specify, you literally use a "Title, Message" format. Ie: <preference name="loadingDialog" value="Raymond, Was Here" />

And here it is in action...


I assumed this would fire between page loads, but I never saw this actually display. Maybe it only shows up if a page takes more than N seconds to load. I'm just throwing this out there in case anyone can confirm it actually works.


The docs say it should be located in file://android_asset/www/. So I made a file, error.html, and tried this:

<preference name="errorUrl" value="error.html" />

But that doesn't work. You need to use a file-based URL. Maybe that's assumed by the docs, but it wasn't clear to me. This is what works:

<preference name="errorUrl" value="file:///android_asset/www/error.html" />

I mentioned to Simon that this setting seems a bit extreme. I mean, why would I link to and use the wrong URL, but certainly in a "real" application with some size in it this would be possible.


Yep, works fine, but only if you don't forget the first value is alpha and accidentally leave it at 0. Here is an example:

<preference name="backgroundColor" value="0xff38c0f4" />

And the result:


I had two issues with this, both of which Joe helped me understand. First, why would you use this versus the gap:splash stuff you see documented at PhoneGap Build? Well, mainly because the gap:splash stuff is PhoneGap Build only. The splashscreen setting will work fine without Build. Secondly, you still have to get into the Java code to actually have this show up. Joe discusses this in a comment to me and it is relatively simple to implement. (And as he points out, soon we should able to skip editing the Java as well.)

Raymond Camden's Picture

About Raymond Camden

Raymond is a developer advocate for HERE Technologies. He focuses on JavaScript, serverless and enterprise cat demos. If you like this article, please consider visiting my Amazon Wishlist or donating via PayPal to show your support. You can even buy me a coffee!

Lafayette, LA

Archived Comments

Comment 1 by maddom73 posted on 3/2/2013 at 4:38 AM

I'm developing an android app using phonegap 2.4.0 and jquery mobile 1.3.0. I've got some problems to stream youtube videos: in fullscreen mode the app crashes. I use iframe to embed videos and I can't manage to find any good solutions around the web. Can you help me?

Comment 2 by Raymond Camden posted on 3/2/2013 at 8:49 PM

Nothing really comes to mind. You could try the InAppBrowser instead.

Comment 3 by abhisek armasha posted on 5/1/2013 at 4:28 PM

for videos I am using Open in new window..child browser.

[Deleted by Raymond Camden]

Comment 4 by Raymond Camden posted on 5/1/2013 at 5:39 PM

Abhisek, in the future, please post a Gist or Pastebin link. I've edited your comment as it was 99% code.

Comment 5 by Navjot Singh posted on 5/29/2013 at 11:37 AM

Hi Raymond,

This is a good article, with demo example(loadingDialog). But when i used it in my android config.xml file but doesn't work for me. I want to know that how can i call it in code or it's working by default.

Comment 6 by Raymond Camden posted on 5/29/2013 at 6:06 PM

Um, so, what? Not sure I understand you.

Comment 7 by Bobby French posted on 10/30/2014 at 4:56 AM

Hi Raymond,
Did you get any answer to see if loadingPageDialog really works?

Comment 8 by Raymond Camden posted on 11/2/2014 at 12:32 AM

I don't believe so.

Comment 9 by chandru posted on 10/20/2015 at 4:01 PM

hi I am building a phonggap build where in the config.xml source a site url is given instead of index.html , it is working fine in android, but for error handling I am using,

<preference name="ErrorUrl" value="file:///myErrorPage.html"/>

I used the above syntax as wellas other syntax like <preference name="ErrorUrl" value="file:///android/www/myErrorPage.html"/> and created android/www folder and placed the file, but always i get application error- network error occured unable to find myerrorpage.html, im not sure what to do next, my directory structure is config.xml, res (which contains all icons)l , splash.png.

All icons and splash screen working, only this error url is not working, could you please help?

Comment 10 by chandru posted on 10/20/2015 at 4:15 PM

pls find the attached screenshot

Comment 11 (In reply to #9) by Raymond Camden posted on 10/20/2015 at 5:54 PM

I'd ping the PG Build folks for this - sorry.