Documentation splashscreen

[NiklasMerz]

Feature Request

Motivation

We should make the documentation for the splashscreen easier to find and understand. Some people approached me and asked for help because getting the splashscreens right can be hard.

Status quo

• The splashscreen feature for Android and iOS have been moved to the platforms.
• We have a quite good page for splashscreens but it's oddly placed in the menu at Refrence -> Core Features -> Splashscreen. I think it should be right the the next to the icons in Create Apps
• We still show the old plugin doc if you click on: Plugins -> Splashscreen : https://cordova.apache.org/docs/en/11.x/reference/cordova-plugin-splashscreen/index.html
• Some information is only buried in the PR: https://github.com/apache/cordova-android/pull/1441

Room for improvement

I will talk to some people and try to make a few small changes that improve this. Feel free to help here:

• [ ] Move docs page in menu and make it easier to find
• [ ] Check page content and add information if necessary
• [ ] Test instructions
• [ ] Link to example SVG for splashscreen from our template

Any further ideas?

[Simone4e]

Can someone add an example of that res/screen/android/splashscreen.xml file?

Because at the moment I have the structure mentioned in the documentation but we don't know how to create a good xml.

[breautek]

Can someone add an example of that res/screen/android/splashscreen.xml file?

Because at the moment I have the structure mentioned in the documentation but we don't know how to create a good xml.

The cordova hello world app uses https://github.com/apache/cordova-android/blob/master/templates/project/res/drawable/ic_cdv_splashscreen.xml

However, it looks like it's not really following the recommended sizing. Cordova uses the Icon with background setting, so the android docs states:

App icon with an icon background: this must be 240×240 dp and fit within a circle 160 dp in diameter.

Looks like our vector is a 512x512dp instead of 240x240. It still does the job appearently but I'd probably recommend trying to follow the Android suggested sizing here.

To parse out what android expects, it expects 240x240dp canvas with your "icon" graphic fitting inside 160dp circle in the center. Everything outside of that circle is an unsafe area that might be masked away. It may be clipped when drawn, or during any android animations.

Note that android expects an Android Vector Drawable (AVD) which is different from an SVG. I believe a SVG may work but android doesn't implement a full SVG feature set and using something that android doesn't have implement will result in a crash. Android Studio does have a tool to convert SVGs and and PSD files into AVDs.

dp refers to display independent pixel. It's a size relative to Android's base density, which is mdpi. You can use these values as is if you're authoring a vector as vectors can be scaled appropriately on-the-fly. Alternatively you can author a PNG, but you'll have to scale them up to the max resolution you intend to support. For example, xxxhdpi is ~4x the density of the base mdpi, so you'll need to multiply all dp units by 4. Therefore a correct PNG canvas is 960x960 px with 640 px diameter circle.

Personally I use rasterized PNGs in my projects with no problems but they are less efficient and not recommended by Android. Namely because importing PSDs using that aforementioned tool doesn't appear to work for me :/

[Simone4e]

Can someone add an example of that res/screen/android/splashscreen.xml file? Because at the moment I have the structure mentioned in the documentation but we don't know how to create a good xml.

The cordova hello world app uses https://github.com/apache/cordova-android/blob/master/templates/project/res/drawable/ic_cdv_splashscreen.xml

However, it looks like it's not really following the recommended sizing. Cordova uses the Icon with background setting, so the android docs states:

App icon with an icon background: this must be 240×240 dp and fit within a circle 160 dp in diameter.

Looks like our vector is a 512x512dp instead of 240x240. It still does the job appearently but I'd probably recommend trying to follow the Android suggested sizing here.

To parse out what android expects, it expects 240x240dp canvas with your "icon" graphic fitting inside 160dp circle in the center. Everything outside of that circle is an unsafe area that might be masked away. It may be clipped when drawn, or during any android animations.

Note that android expects an Android Vector Drawable (AVD) which is different from an SVG. I believe a SVG may work but android doesn't implement a full SVG feature set and using something that android doesn't have implement will result in a crash. Android Studio does have a tool to convert SVGs and and PSD files into AVDs.

dp refers to display independent pixel. It's a size relative to Android's base density, which is mdpi. You can use these values as is if you're authoring a vector as vectors can be scaled appropriately on-the-fly. Alternatively you can author a PNG, but you'll have to scale them up to the max resolution you intend to support. For example, xxxhdpi is ~4x the density of the base mdpi, so you'll need to multiply all dp units by 4. Therefore a correct PNG canvas is 960x960 px with 640 px diameter circle.

Personally I use rasterized PNGs in my projects with no problems but they are less efficient and not recommended by Android. Namely because importing PSDs using that aforementioned tool doesn't appear to work for me :/

In my old version project my xml was:

      <splash density="land-hdpi" src="res/screen/android/drawable-hdpi/screen.png" />
      <splash density="land-mdpi" src="res/screen/android/drawable-mdpi/screen.png" />
      <splash density="land-xhdpi" src="res/screen/android/drawable-xhdpi/screen.png" />
      <splash density="land-xxhdpi" src="res/screen/android/drawable-xxhdpi/screen.png" />
      <splash density="land-xxxhdpi" src="res/screen/android/drawable-xxxhdpi/screen.png" />
      <splash density="port-hdpi" src="res/screen/android/drawable-hdpi/screen.png" />
      <splash density="port-mdpi" src="res/screen/android/drawable-mdpi/screen.png" />
      <splash density="port-xhdpi" src="res/screen/android/drawable-xhdpi/screen.png" />
      <splash density="port-xxhdpi" src="res/screen/android/drawable-xxhdpi/screen.png" />
      <splash density="port-xxxhdpi" src="res/screen/android/drawable-xxxhdpi/screen.png" />

That code resizes the image, is there no way to use similar code for the new version using variants in PNG?

[breautek]

That code resizes the image, is there no way to use similar code for the new version using variants in PNG?

Two things I think worth mentioning on this:

1. The android's splashscreen system is vastly different than what Cordova had implemented via the splashscreen plugin. What you get to control is the background colour of the splashscreen and a small area, about the same size as an app icon, that's about it. So those existing launch screens that you had before will not work on Android's splashscreen system.

2. I'm not sure on the rationale on this, but Cordova writes the splashscreen icon asset to the drawable-nodpi directory, which effectively tells Android that that asset is to be used for all densities. I'm not sure if this is a requirement of Android's splashscreen API.

Generally speaking, the ....../src/res/ directory has several sub directories like mipmap-<density> where you can place different resolution images by density and the android system will pick up the appropriate one to use. But I'm not sure if Android obeys this for the splashscreen given that Cordova doesn't seem to do this. Cordova via splashscreen settings doesn't expose this, but once you have a working splashscreen image, you could try using

<resource-file src="mySrc/res/android/xxxhdpi-splashicon.png" target="res/mipmap-xxxhdpi/ic_cdv_splashscreen.png" />

But honestly, I don't really see the point in doing that unless if you actually have problems rendering xxxhdpi assets on lower end devices. And if that's the case, might be better just to get an AVD instead.

[Simone4e]

That code resizes the image, is there no way to use similar code for the new version using variants in PNG?

Two things I think worth mentioning on this:

1. The android's splashscreen system is vastly different than what Cordova had implemented via the splashscreen plugin. What you get to control is the background colour of the splashscreen and a small area, about the same size as an app icon, that's about it. So those existing launch screens that you had before will not work on Android's splashscreen system.
2. I'm not sure on the rationale on this, but Cordova writes the splashscreen icon asset to the drawable-nodpi directory, which effectively tells Android that that asset is to be used for all densities. I'm not sure if this is a requirement of Android's splashscreen API.

Generally speaking, the ....../src/res/ directory has several sub directories like mipmap-<density> where you can place different resolution images by density and the android system will pick up the appropriate one to use. But I'm not sure if Android obeys this for the splashscreen given that Cordova doesn't seem to do this. Cordova via splashscreen settings doesn't expose this, but once you have a working splashscreen image, you could try using

<resource-file src="mySrc/res/android/xxxhdpi-splashicon.png" target="res/mipmap-xxxhdpi/ic_cdv_splashscreen.png" />

But honestly, I don't really see the point in doing that unless if you actually have problems rendering xxxhdpi assets on lower end devices. And if that's the case, might be better just to get an AVD instead.

I think currently using a simple PNG directly with <preference name="AndroidWindowSplashScreenAnimatedIcon" value="res/screen/android/drawable-xxhdpi/screen.png" />, you mentioned earlier changing the diameter of the circle it contains the image, is there the relative xml code string?

[breautek]

you mentioned earlier changing the diameter of the circle it contains the image, is there the relative xml code string?

I'm not really sure if I'm really understanding the question here. If you're asking what XML places the icon in that circle, it's the AndroidWindowSplashScreenAnimatedIcon preference itself. The supplied image is the 240dpx240dp canvas, that should have it's content fitting inside a 160dp diameter circle.

If you're asking if I have an XML vector that draws a circle then No... I don't have sample XML that does that on hand, but that circle is imaginary, unless if you want to draw an actual circle. It's just that your icon content should fit inside that space and not use the edges/corners of the canvas.

See this example graphic...

This is an example provided by Android. Their GMail logo fits within the 160dp diameter circle and does not exceed the space outside of it. The "circle" is not visible, it's just used to describe how to author your graphic.

[dpogue]

Having just gone through an exercise in updating an older app to newer Cordova Android, I can say with confidence that the splashscreen docs for Android are not helpful at all. There's no "How to upgrade from <splash> to vector drawables" guidance, and not even mention that <splash> isn't used anymore. It does not make clear that you need to use an Android-specific preference instead (because it makes those preferences around like advanced features, particularly when it's named "Animated Icon") and it's not obvious why the links to Google are all about adaptive icons in the context of a splashscreen.

I read the docs, and came away with nothing; tracked down the release blog post for Cordova Android@11, and came away with nothing; and only figured out that <splash> isn't used anymore when I clicked from the blog post into the pull request and read through the changes to prepare.js.