# Icons and Splash Screens

# Objective

In this chapter, you will learn how to set a custom icon and splash screen for your Titanium app. App icons are required by the Google Play, Apple App Store, and Microsoft App Store when you submit your apps. Splash screens add a critically important notification to users that your app is in the process of loading.

To help quickly generate assets for your project, we recommend using the TiCons website tool (opens new window) or the TiCons CLI (opens new window), created by Titan Fokke Zandbergen.

# Icons, splash screens, and store requirements

Titanium provides you with a default icons and splash screens for development purposes. But you'll obviously want to include your own when it comes time to distribute. Depending on your app type, target platform, and distribution choices, you might need to create many variations of these graphics. First, let's cover some basic considerations.

# Location for your graphics

Generally, graphics files can all be put in the Resources directory. However, if you want to provide different app icons for iOS and Android (both get called appicon.png), you could instead put them into the Resources/android and Resources/iphone directories. For Alloy, it is app/assets/iphone and app/assets/android. If you're providing Android density-specific versions of splash screens (launch images), you'll need to put them within the correct folder within the Resources/android/images (or app/assets/android/images for Alloy) hierarchy as shown in the tables below. If you're providing density-specific app icons for Android, you'll need to follow the instructions below to create a folder hierarchy into which you'll place your icons. For Alloy, place your icons in app/assets or the related platform-specific sub-directory. It is recommended to use a centralized DefaultIcon.png icon with 1024 x 1024 pixels that will generate all app-icons automatically.

Google Play, App Store, or Microsoft Store graphics aren't bundled into your finished app, only within your project directory. Instead, you upload them to the respective app store control panels. As such, you can store those files anywhere and name them with any logical name.

# Build scripts for iOS icons

To include an icon in your iOS .ipa file, all you need to do is include the correctly-named file in your Resources/ (Alloy: app/assets/) folder. The Titanium build scripts will copy those icons to the final .ipa, ready for you to upload to Apple.

# Splash screens

You can change but not remove the splash screen that is shown as your app loads. To do so, simply replace the default.png file with your own graphic. You can provide platform-specific versions by placing this file in the Resources/platform_name (Alloy: app/assets/platform_name) directory. There are a couple of platform specific considerations:

# Android splash screen considerations

# Android 12+

Beginning with Android 12 you will see the icon as a splash screen. For more details check the Android guides (opens new window). Make sure you use Adaptive icons (opens new window). A useful tutorial can be found at from zero to app (opens new window).

If you want to change the background color use this in your theme:

tiapp.xml (adjust the name to match our app activity in this form: xx.xx.<AppName>Activity:

<application >
	<activity android:name="com.myapp.MyAppActivity" android:theme="@style/Theme.Custom.Splash" />
</application>

theme:

<style name="Theme.Custom.Splash" parent="@style/Theme.MaterialComponents.NoActionBar">
  <item name="android:windowBackground">@drawable/background_cropped</item>
  <item name="android:windowSplashScreenBackground">@color/orange</item>
</style>

drawable/background_cropped.xml:

<?xml version="1.0" encoding="utf-8"?>
<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
	<item android:drawable="@color/orange"/>
	<item>
		<bitmap android:src="@drawable/background" android:gravity="center"/>
	</item>
</layer-list>

(drawable/background.png is the logo).

# Android <12

For Android, you can either use the default.png file or create a nine-patch image (opens new window).

Since Android devices are available in different screen sizes and densities, Google recommends using a nine-patch image as the recommended graphics format to support different devices. A nine-patch image is a PNG with regions specified as stretchable or not stretchable. For example, if you have an image with a logo centered against a solid background, you can create a nine-patch image with the area around the logo as stretchable. If the image needs to be stretched for a larger device, the solid background color will be stretched, leaving the logo untouched.

To create a nine-patch image, you can either use the Android SDK draw9patch tool or a graphics editor. If you are using a graphics editor, create a one-pixel transparent or white border around your PNG image, then change the top and left border to black pixels where you want the image to stretch. Mark the entire right and bottom borders with black pixels to indicate the drawable areas when the image is scaled. If you do not specify the whole image as drawable, the image may not scale properly, causing it to be squished in part of the screen. For more information, refer to the Android Draw 9-Patch help tutorial (opens new window) for directions on using the draw9patch tool or refer to the Android nine-patch image specification (opens new window) for information on creating a nine-patch image in a graphics editor.

Name the file default.9.png, place it in the Resources/android folder and remove the default.png image. If both of these files exist, the build will fail with an error.

To use multiple density-specific splash screen images, copy your nine-patch image(s) to . / platform/android/res/drawable[-xdpi]/ (Alloy: app/platform/android/...) in your project root directory (not the Resources folder), where xdpi can be a density group to specify more than one image for different screen densities or use the -nodpi suffix to have it support all resolutions. Rename the file(s) to background.9.png. For example, the following project specifies splash images for multiple densities (note: For Alloy, it's relative to your app/ directory as described above):

SampleProjectClassic
├── app
├── platform
│   └── android
│       └── res
│           ├── drawable-ldpi
│           │   └─── background.9.png
│           ├── drawable-mdpi
│           │   └─── background.9.png
│           ├── drawable-hdpi
│           │   └─── background.9.png
│           └── drawable-xhdpi
│           │   └─── background.9.png
│           └── drawable-xxhdpi
│           │   └─── background.9.png
│           └── drawable-xxxhdpi
│               └─── background.9.png
├── Resources
└── tiapp.xml

# Splash screen with a custom theme

If you are using a custom theme to display the splash screen, override the default root activity to use the custom theme:

1. Create a theme XML file in the ./platform/android/res/values/ (Alloy: app /platform/android/res/values/) folder. Do NOT name the file theme.xml. Titanium uses this name as its default theme file, which is required to build the application. If you create a file called theme.xml, it will overwrite the default Titanium one and break the build process. Add the windowBackground items to the custom theme referencing the background nine-patch image.

   ⚠️ Warning

   Only add the windowBackground items only to the theme of the default root activity. If you add windowBackground items to other themes for other activities, the image may not be displayed properly.

   platform/android/res/values/mytheme.xml

   <?xml version="1.0" encoding="utf-8"?>
   <resources>
     <style name="Theme.MyTheme" parent="Theme.AppCompat">
         <item name="windowBackground">@drawable/background</item>
         <item name="android:windowBackground">@drawable/background</item>
     </style>
   </resources>
   

2. Build your application once to generate the build/android/AndroidManifest.xml. Open the file and copy the activity node that contains your default root activity. The android:name attribute will contain the name of your application.

   build/android/AndroidManifest.xml

   <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.sample" android:versionCode="1" android:versionName="1.0">
     <uses-sdk android:minSdkVersion="17" android:targetSdkVersion="25"/>
     <application android:icon="@drawable/appicon" android:label="AlloyNinePatch" android:name="AlloyninepatchApplication" android:debuggable="false" android:theme="@style/Theme.AppCompat">
       <activity android:name=".YourapplicationnameActivity" android:label="@string/app_name" android:theme="@style/Theme.Titanium" android:configChanges="keyboardHidden|orientation|screenSize">
         <intent-filter>
           <action android:name="android.intent.action.MAIN"/>
           <category android:name="android.intent.category.LAUNCHER"/>
         </intent-filter>
       </activity>
       <activity android:name="org.appcelerator.titanium.TiActivity" android:configChanges="keyboardHidden|orientation|screenSize"/>
       <activity android:name="org.appcelerator.titanium.TiTranslucentActivity" android:configChanges="keyboardHidden|orientation|screenSize" android:theme="@style/Theme.AppCompat.Translucent"/>
       <activity android:name="ti.modules.titanium.ui.android.TiPreferencesActivity" android:configChanges="screenSize"/>
     </application>
     <uses-permission android:name="android.permission.INTERNET"/>
     <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
     <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
     <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
     <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
     <uses-permission android:name="android.permission.ACCESS_MOCK_LOCATION"/>
   </manifest>
   

3. Paste the default root activity into the Android section of your tiapp.xml file inside the <application> element. You may need to add the <manifest> and <application> elements to the <android> element of your tiapp.xml file. In the activity's android:theme attribute, replace Theme.Titanium with the name of your custom theme:

   tiapp.xml

   <ti:app xmlns:ti="http://ti.appcelerator.org">
       ...
       <android xmlns:android="http://schemas.android.com/apk/res/android">
           <manifest>
               <application>
                   <activity android:name=".YourapplicationnameActivity" android:label="@string/app_name" android:theme="@style/Theme.MyTheme" android:configChanges="keyboardHidden|orientation|screenSize">
                       <intent-filter>
                           <action android:name="android.intent.action.MAIN"/>
                           <category android:name="android.intent.category.LAUNCHER"/>
                       </intent-filter>
                   </activity>
               </application>
           </manifest>
       </android>
       ...
   </ti:app>
   

For additional information on themes, see Android Themes.

By default, when you create a new project, Android uses the name default.png for the splash screen (with a lowercase "d"). The dimensions and location where you place that that file vary according to the target device density and screen size. These characteristics correspond to the density and generalized size (opens new window) of the user's display. Examine the Resources/android/images (Alloy: app/assets/android/images) folder and you'll find a series of folders with names like res-long-land-hdpi (which corresponds to a device with a "long"/rectangular screen in landscape orientation with an HDPI screen).

Titanium provides default splash screen graphics of the appropriate size in each of the folders inside Resources/android/images(Alloy: app/assets/android/images). You can use those as a guide to creating the images for your app. Simply create each graphic with your own, matching the size and density.

If you do not want to provide separate images for each density and orientation in your project, delete the folders. Then, provide a single default.png file in either Resources (Alloy: app/assets) or Resources/android (Alloy:app/assets/android) to match the dimensions that most closely match the device you expect most of your users to be running. Keep in mind that this could result in a splash screen that is stretched or compressed suboptimally for your users' devices.

# iOS splash screen considerations

iOS uses various splash screen (launch) images depending on the target device. The naming details are provided in the tables below. Match case and naming precisely.

# iOS graphic asset requirements and options

The following table summarizes some of the requirements for application graphic assets. All files must be in PNG format. Any non-PNG file will be ignored. For Alloy projects, place the assets in the app/assets, app/assets/iphone or app/assets/ios folder. For classic Titanium projects, place the assets in the Resources, Resources/iphone or Resources/ios folder.

For all icon files (image files prefixed with appicon), the images need to be square, that is, the height and width must be equal. Icon files cannot have an alpha channel. If you omit any appicon files and have a file called DefaultIcon.png in the root folder of the project that is 1024 x 1024px, the Titanium SDK will generate any missing icon files from the file. If any app icon files are missing, the build will fail. The build will not fail if you omit spotlight and settings icons.

For launch image files (image files prefixed with Default), if you omit any files, the build will not fail.

For the iTuneArtwork files, if you omit any iTunesArtwork file and have a file called DefaultIcon.png in the root folder of the project, the Titanium SDK will generate any missing iTuneArtwork files. The image must be at least 1024 x 1024px to generate the iTunesArtwork and iTunesArtwork@2x files. If any files are omitted, the build will not fail.

Application icons and launch images are added to the Asset Catalog to support App Thinning. Due to this change, you can no longer reference the image assets from the filesystem. For example, you can no longer set the backgroundImage property to a launch image. Note that the localized launch images in the i18n folder are not supported in Asset Catalog.

For more information, see iOS Human Interface Guidelines: Icons and Image Sizes (opens new window).

# iTunes Connect assets

The following table summarizes the iTunes Connect requirements for submitting an application. You need to provide at least one screenshot for each device the application supports.

For more information, see iTunes Connect Developer Guide: Screenshot specifications (opens new window).

# Older devices

The following table summarizes the graphic assets for devices no longer supported by the current Titanium SDK.

# Android graphic asset requirements and options

# Splash Screen

See the Android splash screen considerations section for details!

# Launcher icon

The launcher icon is used by the user to start your application. It should be a 32-bit PNG with an optional alpha channel for transparency. For more information, see the Android Launcher Icons design guide (opens new window).

By default, a newly created Titanium application uses the Resources/android/appicon.png file. The filename must match the name specified in the icon element in your tiapp.xml file.

# Action bar icons

The action bar icons represent individual actions in the action bar. They should be a 32-bit PNG with an alpha channel for transparency. To reference the images in your JavaScript code, prefix the image name with the /images/ directory (with the leading slash). For more information, see the Android Action Bar Icons design guide (opens new window) and Android Action Bar. If you set the target SDK to Android 5.0 (API 21) or higher, the action bar icons may not display. Google is discouraging the use of icons in toolbars starting with API 21.

# Notification icons

The notification icon is displayed on the status bar when the application generates a notification. Notification icons should only be a white-on-transparent background image. For more information, see Android Notifications.

# Small and contextual icons

These icons are used to display the status of actions or items. To reference the images in your JavaScript code, prefix the image name with the /images/ directory (with the leading slash). For more information, see the Android Iconography guide (opens new window).

# Google Play assets

The following table summarizes the Google Play requirements (opens new window) when submitting an application.

# Previous Recommendations

The following table lists the current file attributes created and used for a default Titanium project. These specifications work well as a baseline for handheld devices but not for tablet devices. Tablet devices need images with larger dimension. You need to experiment with multiple devices to see what works well for your application.

# Localized splash screens

The Android and iOS platforms support using localized splash screen images, that is, displaying a different splash screen based on the user's language or locale.

# Android

For the Android platform, place the images in res subfolders suffixed with the ISO 639-1 (opens new window) standard name in the Resources/android/images (Alloy: app/assets/android/images) directory. These folder names may also include the screen qualifiers for density-, orientation-, and ratio-specific resources. The localized splash screen images take precedence over non-localized splash screen images in the Resources/android/images (Alloy: app/assets/android/images) directory.

For example, suppose you have the following filesystem (classic app, for Alloy relatively to the app/assets/android directory):

• Resources

  • android

    • images

      • res-en

        • default.png

      • res-es

        • default.png

      • res-fr-long-land-hdpi

        • default.png

      • res-long-land-hdpi

        • default.png

In this example, both English and Spanish use one splash screen image to support all screen types. For French, the localized splash screen image is only used for high-density, long screens in landscape mode. The image in the res-long-land-hdpi folder is ignored for English, French, and Spanish.

# iOS

For the iOS platform, place your splash screen images in the individual language folders in the i18n (Alloy: app/i18n) directory. Name the files using the same naming convention as described in the iOS graphic asset requirements and options section.

For example, suppose you have the following filesystem:

• i18n

  • en

    • Default@2x.png

    • Default-568h@2x.png

    • Default-667h@2x.png

    • Default-Portrait-736h@3x.png

    • Default-Portrait-2436h@3x.png

  • es

    • Default@2x.png

    • Default-568h@2x.png

    • Default-667h@2x.png

    • Default-Portrait-736h@3x.png

    • Default-Portrait-2436h@3x.png

In this example, each iOS device has a unique splash screen image for English and Spanish. Add more languages like "es" for Spain for "de" for Germany.

# Density-specific Android icons

On Android, the appicon.png is referenced directly from the Android project and does not pass through Titanium. To use density specific versions of the appicon you will need to create a folder structure in the root of the app that looks something like this:

• <app>/platform/android/res/drawable

• <app>/platform/android/res/drawable-hdpi

As you can see, you'd place density-specific versions of the appicon.png in the respective folders. Additional information about directory naming and device characteristic qualifiers can be found in the Android documentation at http://developer.android.com/guide/practices/screens_support.html#qualifiers (opens new window).

# Adding your iTunes artwork to your project

Adding iTunes artwork to your project gives your app a polished look when you are testing or deploying to end users. iTunes artwork is only used for Ad-Hoc builds. Do not include this file when distributing your application to the App Store. In order to get your application's icon to appear in iTunes there are a few simple steps to follow.

1. Create a 512 x 512px and 1024 x 1024px (Retina) version of your applications icon in PNG format.

2. Save the PNG file to your application Resources/iphone (Alloy: app/assets/iphone) folder as iTunesArtwork.png and iTunesArtwork@2x.png

3. Right-click the file in Studio and choose rename. Remove the .png extension from the filename, make it simply iTunesArtwork and iTunesArtwork.

4. Do a clean build of your project for device.

With those steps you should see your application icon show up in iTunes.

# References and further reading

• Additional information about resolution-specific and platform-specific images is covered in Images and ImageView APIs

• Supporting multiple screen sizes in Android (opens new window)

• App Icons on iPhone, iPad and Apple Watch (opens new window)

• iOS Design Themes & Human Interface Guidelines (opens new window)

# Summary

In this document, you learned how to set a custom icon and splash screen for your Titanium app. With this material covered, we move on to the final section of this chapter, which discusses how we deal with the platform specific UI components in a cross platform manner with Titanium.