Skip to main content

Delivering Mobile Apps

 

Applies only to Mobile Apps
OutSystems

Use Custom Splash Screens

By default, mobile applications have a custom splash screen displaying the main color defined in the app creation wizard. This splash screen is displayed after the Operating Systems loads your app (black screen) and after the WebView finishes loading the content (white screen).

It is possible to change the look of your app even before it is fully loaded by customizing the native splash screen. This way you make sure that the end-user has a fluid experience from the moment they open your app by replacing the black to white screen transition with an image of your choice.

Before you start

To use a custom image as your app's native splash screen you need to create .png versions of your custom image for all the Android/iOS splash screen sizes.

Customizing the native splash screen

To use a custom image as your app's native splash screen follow these steps:

  1. Create a ZIP file containing all the .png versions of your custom image for all the Android/iOS splash screen sizes.

  2. In the Data tab of your app's main Module, right-click the Resources folder and import the ZIP file as a Resource.

    Leave the Deploy Action property as Do Nothing.

  3. Select the application module, go to its properties and add the Splash Screens JSON template to the Extensibility Configurations property:

  4. In the Extensibility Configurations, replace <path_to_resources_file> with the name of the ZIP file and replace each one of the <path_to_splash_screen_image> with the correspondent splash screen image location inside the ZIP file.

    Ensure that you define the splash screen and the image path for all sizes and densities available, otherwise, you'll get an error when generating your mobile application.
  5. To make this change available to users, publish and generate a new mobile application package and distribute it.

Further customization of splash screen behavior

You can further customize the behavior of the native splash screen by adding new preferences, in the Extensibility Configurations, using the following syntax:

{
    "preferences": {
        "<target-platform>": [
            {
                "name": "<preference>",
                "value": "<preference-value>"
            }
        ]
    }
}

Where <target-platform> is the target mobile platform that can be set as global, android or ios. Check the Splash screen available preferences table for available values for <preference> and <preference-value>.

Do not forget that you must publish and generate a new mobile application package and distribute it in order to make the splash screen preferences visible to the end-users.

Devices screen sizes and densities

For Android

Width
(px)
Height
(px)
Density
240 360 port-ldpi (120 dpi)
320 480 port-mdpi (160 dpi)
480 720 port-hdpi (240 dpi)
640 960 port-xhdpi (320 dpi)
960 1440 port-xxhdpi (480 dpi)
1280 1920 port-xxxhdpi (640 dpi)
360 240 land-ldpi (120 dpi)
480 320 land-mdpi (160 dpi)
720 480 land-hdpi (240 dpi)
960 640 land-xhdpi (320 dpi)
1440 960 land-xxhdpi (480 dpi)
1920 1280 land-xxxhdpi (640 dpi)

For iOS

Width
(px)
Height
(px)
Device
320 480 All non-retina iPhones and iPods
640 960 iPhone 4/4s (portrait)
640 1136 iPhone 5/5s/SE (portrait)
750 1334 iPhone 6/6s/7/8 (portrait)
1242 2208 iPhone 6+/6s+/7+/8+ (portrait)
2208 1242 iPhone 6+/6s+/7+/8+ (landscape)
1125 2436 iPhone X (portrait)
2436 1125 iPhone X (landscape)
768 1024 All non-retina iPads (portrait)
1024 768 All non-retina iPads (landscape)
1536 2048 All retina iPads (portrait)
2048 1536 All retina iPads (landscape)

Splash screens JSON Template

In the template below, <path_to_resources_file> is the path to the ZIP file and each <path_to_splash_screen_image> is the path to the .png version of your custom image specific to certain splash screen size.
The snippet inside the "splashcreens" tag defines the splash screen image location in the ZIP file for every splash screen size for both platform ("ios" and "android").
The last part of the template uses a "preferences" tag to set a new preference, "SplashScreenDelay", that applies to both mobile platforms ("global" tag), and that displays the native splash screen for 3 seconds before automatically hiding it. To make sure the native splash screen is shown, you must define this preference since the default value for "SplashScreenDelay" is 0.

{
    "resource" : "<path_to_resources_file>",
    "splashscreens" : {
        "ios" : [{
            "resource" : "<path_to_splash_screen_image>",
            "width" : "320",
            "height" : "480"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "width" : "640",
            "height" : "1136"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "width" : "640",
            "height" : "960"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "width" : "750",
            "height" : "1334"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "width" : "1242",
            "height" : "2208"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "width" : "2208",
            "height" : "1242"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "width" : "1125",
            "height" : "2436"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "width" : "2436",
            "height" : "1125"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "width" : "768",
            "height" : "1024"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "width" : "1024",
            "height" : "768"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "width" : "1536",
            "height" : "2048"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "width" : "2048",
            "height" : "1536"
        }],
        "android" : [{
            "resource" : "<path_to_splash_screen_image>",
            "density" : "port-ldpi"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "density" : "port-mdpi"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "density" : "port-hdpi"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "density" : "port-xhdpi"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "density" : "port-xxhdpi"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "density" : "port-xxxhdpi"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "density" : "land-ldpi"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "density" : "land-mdpi"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "density" : "land-hdpi"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "density" : "land-xhdpi"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "density" : "land-xxhdpi"
        },
        {
            "resource" : "<path_to_splash_screen_image>",
            "density" : "land-xxxhdpi"
        }]
    },
    "preferences": {
        "global": [
            {
                "name": "SplashScreenDelay",
                "value": "3000"
            }
        ]
    }
}

Splash screen available preferences

Preference Possible Values Platform Support
AutoHideSplashScreen True or False iOS and Android
SplashScreenDelay Number iOS and Android
FadeSplashScreen True or False iOS and Android
FadeSplashScreenDuration Number iOS and Android
SplashMaintainAspectRatio True or False Android
SplashShowOnlyFirstTime True or False Android

See the descriptions of the available splash screen preferences to check how they work.