Note about PhoneGap Build and Splash Screens

This post is more than 2 years old.

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.

Raymond Camden's Picture

About Raymond Camden

Raymond is a senior developer evangelist for Adobe. He focuses on document services, JavaScript, 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 Mike posted on 4/23/2013 at 10: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.

Comment 2 by Raymond Camden posted on 4/23/2013 at 11:01 PM

There is a config setting, <preference name="fullscreen" value="true" />, that should fix this. Have you tried it?

Comment 3 by Mike posted on 4/23/2013 at 11: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 -


Comment 4 by Raymond Camden posted on 4/24/2013 at 1:06 AM

Ah, cool, thanks for sharing this Mike!

Comment 5 by Adam Tuttle posted on 4/24/2013 at 4:22 PM

"I then wrote a bit of JavaScript that made use of the PhoneGap Screen Shot API:" -- I think you meant Splash Screen API.

Comment 6 by radu wifi posted on 4/24/2013 at 4:24 PM

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,

Comment 7 by radu wifi posted on 4/24/2013 at 4:27 PM

one mention, I have:
<preference name="show-splash-screen-spinner" value="true" />

set but still missing spinner.

Comment 8 by Raymond Camden posted on 4/24/2013 at 11:15 PM

@Adam: Fixed, thanks.

@Radu: Um, if you don't see it in the docs, then I'd say no.

Comment 9 by Mkhuda posted on 4/26/2013 at 10: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 ! :)

Comment 10 by Raymond Camden posted on 4/26/2013 at 2:29 PM

Mikhuda, right, you can do it via native code too. But this article was specifically about how to do it via PhoneGap Build.

Comment 11 by Nell posted on 5/23/2013 at 8:10 AM

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.

Comment 12 by Raymond Camden posted on 5/23/2013 at 11: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.

Comment 13 by Nell posted on 5/23/2013 at 11: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?

Comment 14 by Raymond Camden posted on 5/23/2013 at 11: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.

Comment 15 by Nell posted on 5/23/2013 at 11:44 PM

Any advantages over Dreamweaver for strictly phonegap mobile apps?

Comment 16 by Raymond Camden posted on 5/23/2013 at 11: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.

Comment 17 by Nell posted on 5/23/2013 at 11: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..

Comment 18 by Raymond Camden posted on 5/23/2013 at 11: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.

Comment 19 by Nell posted on 5/23/2013 at 11:57 PM

ok thanks! Do you have any tutorials or examples?

Comment 20 by Raymond Camden posted on 5/23/2013 at 11:59 PM

Of course. ;) Search for phonegap here.

Comment 21 by Nell posted on 5/24/2013 at 12:01 AM

I meant with json, websql and phonegap maybe even with wordpress would be awesome.

Comment 22 by Raymond Camden posted on 5/24/2013 at 12:02 AM

Right, I do. As I said, search for phonegap, and the titles should lead you to the right place.

Comment 23 by Nell posted on 5/24/2013 at 12:06 AM

ok thanks

Comment 24 by Adam Tuttle posted on 5/24/2013 at 12:11 AM

WebSQL is broken in Phonegap 2.7 on Android. They recommend using localStorage instead.

Comment 25 by Raymond Camden posted on 5/24/2013 at 12:12 AM

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?

Comment 26 by Raymond Camden posted on 5/24/2013 at 12:13 AM

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.

Comment 27 by nwilliams posted on 5/28/2013 at 10: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?

Comment 28 by Raymond Camden posted on 5/28/2013 at 6:24 PM

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).

Comment 29 by Klaus Barkhausen posted on 2/26/2014 at 5:04 AM

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:

Comment 30 by Mike Balmes posted on 5/23/2014 at 2:31 PM

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

Comment 31 by Roozbeh posted on 6/20/2014 at 5:08 PM

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?

Comment 32 by Raymond Camden posted on 6/20/2014 at 5:54 PM

You can use multiple gap:splash tags. Check the docs for more info.