Would you like to contribute to the Titanium docs? To get started, sign up for an account on the Appcelerator Wiki and sign our CLA.

Skip to end of metadata
Go to start of metadata

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 both the Google Play and Apple 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 or the TiCons CLI, created by Titan Fokke Zandbergen.

Contents

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

Google Play / App Store graphics aren't bundled into your finished app. 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.

Mobile Web graphics are uploaded to your web server. In general, they must be placed in the "web root" of the site that hosts your Mobile Web app. The build scripts should take care of this for you. But you can override or upload your own graphics as well.

Pre-rendered icons on iOS

By default, iOS will modify the icon graphic you supply to add rounded corners, a drop shadow, and a reflective shine. The graphics here shows the before (left) and after (right) effects of this transformation. Apple recommends that your icon graphic have 90-degree corners, does not apply any shine or gloss, and does not use any alpha transparency.

 

You cannot prevent the rounded corners or drop shadow from being applied. But you can override the reflective shine by providing a "prerendered" icon and making a change in the tiapp.xml file. You might do so to apply your own shine effects. To prevent the default shine from being applied, update the following key in the tiapp.xml to have the value true.

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 (or Resources/iphone) directory. 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 directory. There are a couple of platform specific considerations:

Android splash screen considerations

For Android, you can either use the default.png file or create a nine-patch image.

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 for directions on using the draw9patch tool or refer to the Android nine-patch image specification 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]/ 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:


Icon

Do not place the splash screen image in the drawable folder (without a suffix). Android may scale the image improperly. If you want to use one image for the entire application, place it in the drawable-nodpi folder.

 

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

    Icon

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

    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 of the user's display. Examine the Resources/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. 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 or Resources/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.

Icon

Do not use the <supports-screens/> element with the android:anyDensity attribute set to false to disable multiple density support. Google does not recommend changing the default value. Setting this attribute to false may cause undesired behavior.

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.  For more information, see iOS Human Interface Guidelines: Icons and Image Sizes.

iOS Device

Purpose

Dimensions

DPI

File name

Titanium folder location

iPhone 4/4S/5/5C/5S/6
iPod touch 5th generation

App icon

120 x 120

72

appicon-60@2x.png

Resources or Resources/iphone

iPhone 6 PlusApp Icon180 x 18072appicon-60@3x.pngResources or Resources/iphone

iPad non-retina

App icon

76 x 76

72

appicon-76.png

Resources or Resources/iphone

iPad retina

App icon

152 x 152

72

appicon-76@2x.png

Resources or Resources/iphone

Universal non-retina

Spotlight

40 x 40

72

appicon-Small-40.png

Resources or Resources/iphone

Universal retina

Spotlight

80 x 80

72

appicon-Small-40@2x.png

Resources or Resources/iphone

Universal non-retinaSettings29 x 2972appicon-Small.pngResources or Resources/iphone
Universal retinaSettings58 x 5872appicon-Small@2x.pngResources or Resources/iphone
iPhone 6 PlusSettings87 x 8772appicon-Small@3x.pngResources or Resources/iphone

iPhone 4/4S

Splash screen

640 x 960

72

Default@2x.png

Resources or Resources/iphone

iPhone 5/5C/5S
iPod touch 5th generation

Splash screen

640 x 1136

72

Default-568h@2x.png

Resources or Resources/iphone

iPhone 6Splash screen750 x 133472Default-667h@2x.pngResources or Resources/iphone
iPhone 6 Plus landscapeSplash screen2208 x 124272Default-Landscape-736h@3x.pngResources or Resources/iphone
iPhone 6 Plus portraitSplash screen1242 x 220872Default-Portrait-736h@3x.pngResources or Resources/iphone

iPad non-retina landscape

Splash screen

1024 x 768

72

Default-Landscape.png

Resources or Resources/iphone

iPad non-retina portrait

Splash screen

768 x 1024

72

Default-Portrait.png

Resources or Resources/iphone

iPad retina landscape

Splash screen

2048 x 1536

72

Default-Landscape@2x.png

Resources or Resources/iphone

iPad retina portrait

Splash screen

1536 x 2048

72

Default-Portrait@2x.png

Resources or Resources/iphone

Any device with a non-retina display for ad-hoc builds

App list in iTunes

512 x 512

72

iTunesArtwork (no ext)

Resources or Resources/iphone

Any device with a retina display for ad-hoc builds

App list in iTunes

1024 x 1024

72

iTunesArtwork@2x (no ext)

Resources or Resources/iphone

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.  The status bar should not be included in the screen shot.

For more information, see iTunes Connect Developer Guide: iTunes Connect App Properties.

iTunes Connect graphics

Purpose

Dimensions

DPI

Filename

Specs

One (1) required

Large app icon

1024 x 1024

72

any

JPG or PNG, flattened, no transparency

One (1) required

iPhone 4/4S screenshot

  • fullscreen: 960x640 or 640x960
  • no status bar: 960x600 or 640x920

72

any

JPG or PNG, flattened, no transparency

One (1) required

iPhone 5/5C/5S and iPod 5 screenshot

  • fullscreen: 1136x640 or 640x1136
  • no status bar: 1136x600 or 640x1096

72

any

JPG or PNG, flattened, no transparency

One (1) requirediPhone 6 screenshot1334x750, 750x133472anyJPG or PNG, flattened, no transparency
One (1) requirediPhone 6 Plus screenshot2208x1242, 1242x220872anyJPG or PNG, flattened, no transparency

One (1) required

iPad screenshot

  • non-retina, fullscreen: 1024x768 or 768x1024
  • non-retina, no status bar: 1024x728 or 768x1004
  • retina, fullscreen: 2048x1536 or 1536x2048
  • retina, no status bar: 2048x1496 or 1536x2008

72

any

JPG or PNG, flattened, no transparency

Older Devices

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

iOS Device

Purpose

Dimensions

DPI

File name

Titanium folder location

iPhone/iPod non-retina 

App icon

57 x 57

72

appicon.png

Resources or Resources/iphone

iPhone/iPod retina (iOS 6 and prior)

App icon

114 x 114

72

appicon@2x.png

Resources or Resources/iphone

iPad 1 & 2 (iOS 6 and prior)

App icon

72 x 72

72

appicon-72.png

Resources or Resources/iphone

iPad 3 (iOS 6 and prior)

App icon

144 x 144

72

appicon-72@2x.png

Resources or Resources/iphone

iPhone/iPod non-retina

Spotlight & settings

29 x 29

72

appicon-Small.png

Resources or Resources/iphone

iPhone/iPod retina (iOS 6 and prior)

Spotlight & settings

58 x 58

72

appicon-Small@2x.png

Resources or Resources/iphone

iPad 1 & 2 (iOS 6 and prior)

Spotlight & settings

50 x 50

72

appicon-Small-50.png

Resources or Resources/iphone

iPad Retina (iOS 6 and prior)

Spotlight

100 x 100

72

appicon-Small-50@2x.png

Resources or Resources/iphone

iPad Retina (iOS 6 and prior)

Settings

58 x 58

72

appicon-Small@2x.png

Resources or Resources/iphone

iPhone non-retina

Splash screen

320 x 480

72

Default.png

Resources or Resources/iphone

iPad 1 landscape

Splash screen

1024 x 768

72

Default-Landscape.png

Resources or Resources/iphone

iPad 1 portrait

Splash screen

768 x 1024

72

Default-Portrait.png

Resources or Resources/iphone

Android graphic asset requirements and options

Splash Screen

See the Android splash screen considerations section.

Launcher Icon

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

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.

DensityDPIDimensionsTitanium folder location and filename
ldpi12036 x 36platform/android/res/drawable-ldpi/appicon.png
mdpi16048 x 48platform/android/res/drawable-mdpi/appicon.png
hdpi24072 x 72platform/android/res/drawable-hdpi/appicon.png
xhdpi32096 x 96platform/android/res/drawable-xhdpi/appicon.png
xxhdpi480144 x 144platform/android/res/drawable-xxhdpi /appicon.png

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 and Android Action Bar.

DensityDPIDimensionsTitanium folder location
ldpi12018 x 18Resources/android/images/res-ldpi/
mdpi16024 x 24Resources/android/images/res-mdpi/
hdpi24036 x 36Resources/android/images/res-hdpi/
xhdpi32048 x 48Resources/android/images/res-xhdpi/
xxhdpi48072 x 72Resources/android/images/res-xxhdpi/

Notification Icons

The notification icon is displayed on the status bar when the application generates a notification.  For more information, see Android Notifications.

DensityDPIDimensionsTitanium folder location
ldpi12018 x 18platform/android/res/drawable-ldpi/
mdpi16024 x 24platform/android/res/drawable-mdpi/
hdpi24036 x 36platform/android/res/drawable-hdpi/
xhdpi32048 x 48platform/android/res/drawable-xhdpi/
xxhdpi48072 x 72platform/android/res/drawable-xxhdpi/

Small / 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.

DensityDPIDimensionsTitanium folder location
ldpi12012 x 12Resources/android/images/res-ldpi/
mdpi16016 x 16Resources/android/images/res-mdpi/
hdpi24024 x 24Resources/android/images/res-hdpi/
xhdpi32032 x 32Resources/android/images/res-xhdpi/
xxhdpi48048 x 48Resources/android/images/res-xxhdpi/

Google Play Assets

The following table summarizes the Google Play requirements when submitting an application. 

Google Play graphics

Purpose

Dimensions

DPI

File name

Specs

One (1) required

Large app icon

512 x 512

72

any

32-bit PNG or JPG

Min of two (2) required

Screenshots

320 x 480, 480 x 800, or 480 x 854

72

any

24-bit PNG or JPG, no alpha channel

Optional

Promotional graphic

180 x 120

72

any

24-bit PNG or JPG, no alpha channel

Optional

Feature graphic

1024 x 500

72

any

24-bit PNG or JPG, no alpha channel

Optional

YouTube video link

 

 

 

30 sec to 2 min works best

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.

Android screen type

Purpose

Dimensions

DPI

File name

Titanium folder location

Any

App icon

128 x 128

72

appicon.png

Resources or Resources/android

Rectangular, landscape, HDPI

Splash screen

800 x 480

240

default.png

Resources/android/images/res-long-land-hdpi

Rectangular, landscape, LDPI

Splash screen

400 x 240

120

default.png

Resources/android/images/res-long-land-ldpi

Rectangular, portrait, HDPI

Splash screen

480 x 800

240

default.png

Resources/android/images/res-long-port-hdpi

Rectangular, portrait, LDPI

Splash screen

240 x 400

120

default.png

Resources/android/images/res-long-port-ldpi

Square-ish, landscape, HDPI

Splash screen

800 x 480

240

default.png

Resources/android/images/res-notlong-land-hdpi

Square-ish, landscape, LDPI

Splash screen

320 x 240

120

default.png

Resources/android/images/res-notlong-land-ldpi

Square-ish, landscape, MDPI

Splash screen

480 x 320

160

default.png

Resources/android/images/res-notlong-land-mdpi

Square-ish, portrait, HDPI

Splash screen

480 x 800

240

default.png

Resources/android/images/res-notlong-port-hdpi

Square-ish, portrait, LDPI

Splash screen

240 x 320

120

default.png

Resources/android/images/res-notlong-port-ldpi

Square-ish, portrait, MDPI

Splash screen

320 x 480

160

default.png

Resources/android/images/res-notlong-port-mdpi

Mobile Web graphic asset requirements and options

Icons and splash screens for Mobile Web apps are not packaged into an IPA/APK file in the way they are for a native app. Instead, you supply graphics along with the rest of your app's HTML/CSS/JavaScript files. Then, using <link> tags within the HTML, you specify which graphics to use as the splash screen or app icon. That app icon, which Apple calls a "web clip" icon, will be used only when a user saves a shortcut/bookmark to your web app on their device's home screen.

The Titanium Mobile Web build process takes care of the "heavy lifting" for you. Simply follow the recommendations in the preceding tables for appicon and splash screen names and dimensions. During the build process, Titanium will rename and move files as necessary, then add the required <link> tags to your app's HTML files. Simply upload the resulting file set to your web server.

Here's an example of the results of building a Titanium project for Mobile Web; this project used the Titanium default file names (e.g. appicon.png) for the source graphics.

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 standard name in the Resources/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 directory.

For example, suppose you have the following filesystem:

  • 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 directory. Name the files using the same naming convention as described in the iOS graphic asset requirements and options section.  Currently, the default splash screen in the  Resources/iphone  directory takes precedence over the localized splash screen images. This issue will be fixed in the future, where the localized splash screen image takes precedence over the default splash screen image.

For example, suppose you have the following filesystem:

  • i18n
    • en
      • Default.png
      • Default@2x.png
      • Default-568h@2x.png
    • es
      • Default.png

In this example, each iPhone version has a unique splash screen image for English, but for Spanish, only one image is used.

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.

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 build.  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 512x512 version of your applications icon in PNG format.
  2. Save the PNG file to your application Resources folder as iTunesArtwork.png
  3. Right-click the file in Studio and choose rename. Remove the .png extension from the filename, make it simply 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

Summary

In this chapter, 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.

  • No labels