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 when creating the app. This splash screen has the main color defined in the app creation wizard that, when the app is opened, is adapted to the screen sizes. But, there are situations in which you want to use a customized image in the splash screen and have version specific to map the screen size.

Specify Custom Splash Screen Images

To change the splash screen and use your own splash screen image, providing multiple versions regarding the device screen size or density:

  1. Create (if not yet created) a zip file and add all the Android/iOS splash screens sizes (.png image format).

  2. Open the main application module and import the new or the updated zip file to the resources folder.

  3. Select the application module, go to its properties and open the Extensibility Configurations property.

  4. In the Extensibility Configurations value window, you must create a JSON object (if not yet created), where you can specify all the information about the splash screens to use. If not yet specified, start by indicating the resource file that contains the splash screens.

  5. Add the “splashscreens” tag to indicate that you want to change the splash screens of your application.

  6. For each mobile platform, specify the size (iOS) and density (Android) and the correspondent splash screen location in the zip folders. Ensure that you define the splash screen for all size and densities available, otherwise, you'll get an error when generating your mobile application (the example below is just for reference). Check the JSON template for the splash screens sizes and densities to avoid mistakes.

  7. To make this change available for the users, publish and generate a new mobile application and distribute it.

Devices Screen Sizes and Densities

For iOS

Width Height Device
320 480 All non-retina iPhones and iPods
640 1136 -
640 960 iPhone 4/4s/5/5s (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)

For Android

Width Height 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)

Splash Screens JSON Template

{
    "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"
        }]
    }
}

Configure Custom Splash Screen Behavior

You can also modify the behavior of the custom splash screens using the Extensibility Configurations window:

  1. Use the "preferences" tag to indicate that you want to change a preference of your application.

  2. Define the mobile platforms for which you are trying to customize the splash screen behavior (in the example below, we are defining a preference for the splash screens in both platforms Android and iOS).

  3. Now, just add your preference. Check the list of preferences available.

  4. To make the splash screen preferences visible to the users, publish and generate a new mobile application package and distribute it.

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.