Twitter: raymondcamden

Address: Lafayette, LA, USA

Note about PhoneGap Build and Splash Screens

04-23-2013 21,160 views Mobile 32 Comments

I'm currently working on my MAX Advanced PhoneGap Build presentation (wait, scratch that, of course I'm done already, I mean, who waits to the last minute???) and ran into an interesting issue. Using a splash screen is rather easy via the PhoneGap Build config.xml file.

To test this feature, I used to quickly create an image sizes 320x480. PhoneGap Build supports multiple splash screens of multiple sizes and densities, but I wanted to see how well a default splash screen would work. I dropped the kitten in my folder and added this to config.xml:

<gap:splash src="splash.png" />

I zipped up my folder, uploaded to PGB, and everything worked fine. I noticed, though, that my splash screen only lasted for about a second. I did some digging and found that you can disable the automatic hide of the splash screen by doing this:

<preference name="auto-hide-splash-screen" value="false" />

I then wrote a bit of JavaScript that made use of the PhoneGap Splash Screen API:

In theory, that should be it, but I noticed something odd. I launched my app, and then saw this:

What the heck? At first I thought I had broken something, but then I noticed the image went away after 5 seconds. I then realized what my issue was... size.

When using the a default splash screen, PhoneGap is able to size it correctly for any device (afaik), but if you keep the splash screen around, it then reverts to the proper size for the device. In my case, I was testing on an iPhone 5. So I created a new image sized 640 by 1136 and added this to my config.xml:

<gap:splash src="retina.png" width="640" height="1136" />

And it worked perfectly. You can see via this exciting YouTube video:

So I guess the take away from this is - while a default splash screen may work on multiple devices, if you are doing anything with the splash screen (like keeping it on screen longer), you want to ensure you build out properly sized images for your supported platforms. Frankly, that's probably the best idea in general anyway.


  • Mike #
    Commented on 04-23-2013 at 1:59 PM
    I've been using a similar method and it works quite well. I start a timer when your js starts loading and subtract that from the current time removing the splash screen after 5 seconds minus that interval. That normalized the load time across iOS and different classes of Android devices.

    Should also note that with PhoneGap 2.5 on Build the splash screen starts out covering the entire screen, then the image shifts down to show signal/batter bar at the top. Reverting to PhoneGap 2.3 fixes the issue.
  • Commented on 04-23-2013 at 2:01 PM
    There is a config setting, <preference name="fullscreen" value="true" />, that should fix this. Have you tried it?
  • Mike #
    Commented on 04-23-2013 at 2:08 PM
    Yes, but that makes the entire app full screen, which is not desired by our clients. They only want the splash to be full screen, which <= 2.3 does.

    Looks like this is fixable if you're not using Build -

    Community Topic -
  • Commented on 04-23-2013 at 4:06 PM
    Ah, cool, thanks for sharing this Mike!
  • Commented on 04-24-2013 at 7:22 AM
    "I then wrote a bit of JavaScript that made use of the PhoneGap Screen Shot API:" -- I think you meant Splash Screen API.
  • radu wifi #
    Commented on 04-24-2013 at 7:24 AM
    Great post, I had this problem but imagined I did something something wrong.
    One the other hand at some early build I had splash was displaying a spinner in the middle that was nice there any XML config setting to trigger spinner how while splash is on?

    Thank you,
  • radu wifi #
    Commented on 04-24-2013 at 7:27 AM
    one mention, I have:
    <preference name="show-splash-screen-spinner" value="true" />

    set but still missing spinner.
  • Commented on 04-24-2013 at 2:15 PM
    @Adam: Fixed, thanks.

    @Radu: Um, if you don't see it in the docs, then I'd say no.
  • Commented on 04-26-2013 at 1:54 AM
    Hi, Mr. Raymond !
    I created splash screen with some code in Activity like this :
          super.setIntegerProperty("splashscreen", R.drawable.splash);
          super.loadUrl("file:///android_asset/www/index.html", 3000);

    and place some images in res/drawable folder.
    its work perfectly ! :)
  • Commented on 04-26-2013 at 5:29 AM
    Mikhuda, right, you can do it via native code too. But this article was specifically about how to do it via PhoneGap Build.
  • Nell #
    Commented on 05-22-2013 at 11:10 PM
    Can you talk about including admob in phonegap build using Dreamweaver. No one seems to know how to do this. If not Dreamweaver then can you do a tutorial with phonegap and admob. Monetization is very important for developers.
  • Commented on 05-23-2013 at 2:32 PM
    I've yet to work with Admob. I tried Google Adsense once for a PG ad (not sure if I was supposed to, but I did ;).

    I'll put this in my "To Blog" email folder, but no promises.

    I don't use DW. My editor of choice is Brackets.
  • Nell #
    Commented on 05-23-2013 at 2:37 PM
    Yes it's against their policies, you have to use admob or they eventually will ban your adsense account. I wish I could use adsense though, alot easier and better.

    On the other hand, what's the differences between Brackets and Dreamweaver?
  • Commented on 05-23-2013 at 2:41 PM
    "On the other hand, what's the differences between Brackets and Dreamweaver?"
    Night and Day. ;)

    Brackets is a light weight editor focused on HTML/JS/CSS development only. Check it out:

    Be warned though, it is still in development so it is missing a few features.
  • Nell #
    Commented on 05-23-2013 at 2:44 PM
    Any advantages over Dreamweaver for strictly phonegap mobile apps?
  • Commented on 05-23-2013 at 2:46 PM
    Hmm, maybe not. I just find Brackets to be more to my liking. DW feels a bit "heavy." Editors are ver much a personal choice though.
  • Nell #
    Commented on 05-23-2013 at 2:53 PM
    ok thanks for the prompt response!

    While I have you on the phone....... I'm currently using json to load wordpress blogs. When I have a blog that have a lot of posts it takes a long time for the application to load while it's retrieving the posts.

    Is there a way I can store the posts locally once it's downloaded, or at least the post titles to a local database. Therefore improving the performance and allowing them to access the posts while offline?

    I did this with sqllite with objective c but it was with xml and objective c. Wondering what would be the best way to do this with phonegap etc..
  • Commented on 05-23-2013 at 2:56 PM
    PhoneGap supports 3 types of local storage:

    1) LocalStorage
    2) WebSQL (which is the same as SQLite pretty much)
    3) FIle System

    Check out the WebSQL stuff. It would be perfect for this.
  • Nell #
    Commented on 05-23-2013 at 2:57 PM
    ok thanks! Do you have any tutorials or examples?
  • Commented on 05-23-2013 at 2:59 PM
    Of course. ;) Search for phonegap here.
  • Nell #
    Commented on 05-23-2013 at 3:01 PM
    I meant with json, websql and phonegap maybe even with wordpress would be awesome.
  • Commented on 05-23-2013 at 3:02 PM
    Right, I do. As I said, search for phonegap, and the titles should lead you to the right place.
  • Nell #
    Commented on 05-23-2013 at 3:06 PM
    ok thanks
  • Commented on 05-23-2013 at 3:11 PM
    WebSQL is broken in Phonegap 2.7 on Android. They recommend using localStorage instead.
  • Commented on 05-23-2013 at 3:12 PM
    Ugh, really? And this comment makes no sense:

    "localStorage is once again persistant, this breaks WebSQL on Android 4.x"

    Why would a fix to localStorage (and who knew it was broken) break WebSQL?
  • Commented on 05-23-2013 at 3:13 PM
    Just read the details. (Which doesn't explain why LocalStorage is involved.) I know that WebSQL is deprecated, but w/o IndexedDB, this is a huge issue. LocalStorage is not appropriate for storing large amounts of ad hoq data.

    Shit. Shit. Shit.
  • nwilliams #
    Commented on 05-28-2013 at 1:16 AM
    Excellent post, however I am having problems getting my splash screen to display, I've gone as far as downloading the phone gap starter app from the internet and changing the config.xml to use my images but when i start the app on my device (nexus 7) i am not seeing the splash screen. Any suggestion as to why the splash screen would not be showing?
  • Commented on 05-28-2013 at 9:24 AM
    Hmm, nothing comes to mind. I'd maybe consider posting the question to the PGB support (and please let us know if you figure it out).
  • Commented on 02-25-2014 at 6:04 PM
    Creating all of the splash pages and icons in different sizes became too time consuming for us. Every time we wanted to change our splash or icon images we had to re-create them in all of the different device sizes. We created a simple tool that allowed us to automate the process and even integrate it into our build process.

    Check it out at:
  • Mike Balmes #
    Commented on 05-23-2014 at 5:31 AM
    Hi guys, i need some help. my splash screen is not working.i don't know what is the problem.may be you can help me
  • Roozbeh #
    Commented on 06-20-2014 at 8:08 AM
    Hi, thx for your great tut. What if we targeting both tablets and mobiles? How could we define a splash screen that supports both horizontal/vertical and both for iphone and ipad screen size?
  • Commented on 06-20-2014 at 8:54 AM
    You can use multiple gap:splash tags. Check the docs for more info.

Post Reply

Please refrain from posting large blocks of code as a comment. Use Pastebin or Gists instead. Text wrapped in asterisks (*) will be bold and text wrapped in underscores (_) will be italicized.

Leave this field empty