App-Related Resources

Aside from the images and media files your app presents on screen, there are some specific resources that iOS itself requires your app to provide. The system uses these resources to determine how to present your app on the user’s home screen and, in some cases, how to facilitate interactions with other parts of the system.

App Store Required Resources

There are several things that you are required to provide in your app bundle before submitting it to the App Store:

The Information Property List File

The information property list (Info.plist) file contains critical information about your app’s configuration and must be included in your app bundle. Every new project you create in Xcode has a default Info.plist file configured with some basic information about your project. You can modify this file to specify additional configuration details for your app.

Your app’s Info.plist file must include the following keys:

You might also want to include the following keys in your app’s Info.plist file, depending on the behavior of your app:

The Info.plist file itself is a property list file that you can edit manually or using Xcode. Each new Xcode project contains a file called <project_name>-Info.plist, where <project_name> is the name of your Xcode project. This file is the template that Xcode uses to generate the actual Info.plist file at build time. When you select this file, Xcode displays the property list editor that you can use to add or remove keys or change the value of a key. For information about how to configure the contents of this file, see Property List Editor Help.

For details about the keys you can include in the Info.plist file, see Information Property List Key Reference.

Declaring the Required Device Capabilities

The UIRequiredDeviceCapabilities key lets you declare the hardware or specific capabilities that your app needs in order to run. All apps are required to have this key in their Info.plist file. The App Store uses the contents of this key to prevent users from downloading your app onto a device that cannot possibly run it.

The value of the UIRequiredDeviceCapabilities key is either an array or a dictionary that contains additional keys identifying features your app requires (or specifically prohibits). If you specify the value of the key using an array, the presence of a key indicates that the feature is required; the absence of a key indicates that the feature is not required and that the app can run without it. If you specify a dictionary instead, each key in the dictionary must have a Boolean value that indicates whether the feature is required or prohibited. A value of true indicates the feature is required and a value of false indicates that the feature must not be present on the device. If a given capability is optional for your app, do not include the corresponding key in the dictionary.

Table 5-1 lists the keys that you can include in the array or dictionary for the UIRequiredDeviceCapabilities key. You should include keys only for the features that your app absolutely requires. If your app can run without a specific feature, do not include the corresponding key.

Table 5-1  Dictionary keys for the UIRequiredDeviceCapabilities key

Key

Description

accelerometer

Include this key if your app requires (or specifically prohibits) the presence of accelerometers on the device. Apps use the Core Motion framework to receive accelerometer events. You do not need to include this key if your app detects only device orientation changes.

armv6

Include this key if your app is compiled only for the armv6 instruction set. (iOS 3.1 and later)

armv7

Include this key if your app is compiled only for the armv7 instruction set. (iOS 3.1 and later)

auto-focus-camera

Include this key if your app requires (or specifically prohibits) autofocus capabilities in the device’s still camera. Although most developers should not need to include this key, you might include it if your app supports macro photography or requires sharper images in order to perform some sort of image processing.

bluetooth-le

Include this key if your app requires (or specifically prohibits) the presence of Bluetooth low-energy hardware on the device. (iOS 5 and later.)

camera-flash

Include this key if your app requires (or specifically prohibits) the presence of a camera flash for taking pictures or shooting video. Apps use the UIImagePickerController interface to control the enabling of this feature.

front-facing-camera

Include this key if your app requires (or specifically prohibits) the presence of a forward-facing camera. Apps use the UIImagePickerController interface to capture video from the device’s camera.

gamekit

Include this key if your app requires (or specifically prohibits) Game Center. (iOS 4.1 and later)

gps

Include this key if your app requires (or specifically prohibits) the presence of GPS (or AGPS) hardware when tracking locations. (You should include this key only if you need the higher accuracy offered by GPS hardware.) If you include this key, you should also include the location-services key. You should require GPS only if your app needs location data more accurate than the cellular or Wi-fi radios might otherwise provide.

gyroscope

Include this key if your app requires (or specifically prohibits) the presence of a gyroscope on the device. Apps use the Core Motion framework to retrieve information from gyroscope hardware.

location-services

Include this key if your app requires (or specifically prohibits) the ability to retrieve the device’s current location using the Core Location framework. (This key refers to the general location services feature. If you specifically need GPS-level accuracy, you should also include the gps key.)

magnetometer

Include this key if your app requires (or specifically prohibits) the presence of magnetometer hardware. Apps use this hardware to receive heading-related events through the Core Location framework.

microphone

Include this key if your app uses the built-in microphone or supports accessories that provide a microphone.

opengles-1

Include this key if your app requires (or specifically prohibits) the presence of the OpenGL ES 1.1 interfaces.

opengles-2

Include this key if your app requires (or specifically prohibits) the presence of the OpenGL ES 2.0 interfaces.

peer-peer

Include this key if your app requires (or specifically prohibits) peer-to-peer connectivity over a Bluetooth network. (iOS 3.1 and later)

sms

Include this key if your app requires (or specifically prohibits) the presence of the Messages app. You might require this feature if your app opens URLs with the sms scheme.

still-camera

Include this key if your app requires (or specifically prohibits) the presence of a camera on the device. Apps use the UIImagePickerController interface to capture images from the device’s still camera.

telephony

Include this key if your app requires (or specifically prohibits) the presence of the Phone app. You might require this feature if your app opens URLs with the tel scheme.

video-camera

Include this key if your app requires (or specifically prohibits) the presence of a camera with video capabilities on the device. Apps use the UIImagePickerController interface to capture video from the device’s camera.

wifi

Include this key if your app requires (or specifically prohibits) access to the networking features of the device.

For detailed information on how to create and edit property lists, see Information Property List Key Reference.

Declaring Your App’s Supported Document Types

If your app is able to open existing or custom file types, your Info.plist file should include information about those types. Declaring file types is how you let the system know that your app is able to open files of the corresponding type. The system uses this information to direct file requests to your app at appropriate times. For example, if the Mail app receives an attachment, the system can direct that attachment to your app to open.

When declaring your app’s supported file types, you typically do not configure keys in your Info.plist file directly. In the Info tab of your target settings, there is a Document Settings section that you can use to specify your app’s supported types. Each document type that you add to this section can represent one file type or several file types. For example, you can define a single document type that represents only PNG images or one that represents PNG, JPG, and GIF images. The decision to represent one file type or multiple file types depends on how your app presents the files. If it presents all of the files in the same way—that is, with the same icon and with the same basic code path—then you can use one document type for multiple file types. If the code paths or icons are different for each file type, you should declare different document types for each.

For each document type, you must provide the following information at a minimum:

  • A name. This is a localizable string that can be displayed to the user if needed.

  • An icon. All files associated with a document type share the same icon.

  • The file types. These are uniform type identifier (UTI) strings that identify the supported file types. For example, to specify the PNG file type, you would specify the public.png UTI. UTIs are the preferred way to specify file types because they are less fragile than filename extensions and other techniques used to identify files.

Ultimately, Xcode converts your document type information into a set of keys and adds them to the CFBundleDocumentTypes key in your app’s Info.plist file. The CFBundleDocumentTypes key contains an array of dictionaries, where each dictionary represents one of your declared document types and includes the name, icon, file type, and other information you specified.

For more information on the keys you use to declare your app’s document types, see Information Property List Key Reference. For information about how to open files passed to your app by the system, see “Handling URL Requests.”

App Icons

Every app must provide an icon to be displayed on a device’s Home screen and in the App Store. An app may actually specify several different icons for use in different situations. For example, an app can provide a small icon to use when displaying search results and can provide a high-resolution icon for devices with Retina displays.

Regardless of how many different icons your app has, you specify them using the CFBundleIcons key in the Info.plist file. The value of that key is an array of strings, each of which contains the filename of one of your icons. The filenames can be anything you want, but all image files must be in the PNG format and must reside in the top level of your app bundle. (Avoid using interlaced PNGs.) When the system needs an icon, it choose the image file whose size most closely matches the intended usage.

Table 5-2 lists the dimensions of the icons to include for apps built for iOS 7 and later.

Table 5-2  Icon dimensions (iOS 7 and later)

Icon

Idiom

Size

Usage

App icon (required)

iPhone

60 x 60 pixels

120 x 120 pixels (@2x)

This is the main icon for apps running on iPhone and iPod touch in iOS 7 and later.

App icon (required)

iPad

76 x 76 pixels

152 x 152 pixels (@2x)

This is the main icon for apps running on iPad in iOS 7 and later.

Spotlight search results icon (recommended)

All devices

40 x 40 pixels

80 x 80 pixels (@2x)

This is the icon displayed for Spotlight search results in iOS 7 and later.

Settings icon

All devices

29 x 29 pixels

58 x 58 pixels (@2x)

This is the icon used by the Settings app in iOS 7 and later.

Table 5-3 lists the dimensions of the icons you can include for apps built for iOS 6.1 and earlier.

Table 5-3  Icon dimensions (iOS 6.1 and earlier)

Icon

Idiom

Size

Usage

App icon (required)

iPhone

57 x 57 pixels

114 x 114 pixels (@2x)

This is the main icon for apps running on iPhone and iPod touch in iOS 6.1 and earlier.

App icon (required)

iPad

72 x 72 pixels

144 x 144 pixels (@2x)

This is the main icon for apps running on iPad.

Small icon for Spotlight search results and Settings (recommended)

iPhone

29 x 29 pixels

58 x 58 pixels (@2x)

This is the icon displayed in conjunction with search results on iPhone and iPod touch. This icon is also used by the Settings app on all devices.

Small icon for Spotlight search results and Settings (recommended)

iPad

50 x 50 pixels

100 x 100 pixels (@2x)

This is the icon displayed in conjunction with search results on iPad.

When specifying icon files using the CFBundleIcons key, it is best to omit the filename extensions of your image files. If you include a filename extension, you must explicitly add the names of all image files (including any high-resolution variants). When you omit the filename extension, the system automatically detects high-resolution variants of your file, even if they are not included in the array.

If your iPhone app is running in iOS 3.1.3 or earlier, the system does not look for icons using your Info.plist file. The CFBundleIcons key was introduced in iOS 5.0 and the CFBundleIconFiles key was introduced in iOS 3.2. Instead of using these keys, the system looks for icon files with specific filenames. Although the sizes of the icons are the same as those in Table 5-2, if your app supports deployment on iOS 3.1.3 and earlier, you must use the following filenames when naming your icons:

Apps being distributed via ad-hoc distribution may also include a 512 x 512 pixel version of their icon in the CFBundleIcons key. The name of this file must be iTunesArtwork and not have a filename extension. The high resolution version of this icon should be 1024 x 1024 pixels and have the name iTunesArtwork@2x. Do not include this icon in your app bundle if you are not distributing your app via ad-hoc distribution.

For more information about the CFBundleIcons key, see Information Property List Key Reference. For information about creating your app icons, see iOS Human Interface Guidelines.

App Launch (Default) Images

When the system launches an app on any type of device, it temporarily displays a static launch image on the screen. Your app provides this image, with the image contents usually containing a prerendered version of your app’s default user interface. The purpose of this image is to give the user immediate feedback that the app launched. It also gives your app time to initialize itself and prepare its initial set of views for display. When your app is ready to run, the system removes the image and displays your app’s windows and views.

Every app must provide at least one launch image. This image is typically in a file named Default.png that displays your app’s initial screen in a portrait orientation. However, you can also provide other launch images to be used under different launch conditions. All launch images must be PNG files and you should avoid using interlaced PNGs. The name of each launch image conveys its purpose and how it is used. It is recommended that you use the following format for launch image filenames:

<basename><usage_specific_modifiers><scale_modifier><device_modifier>.png

The <basename> portion of the filename is either the string Default or a custom string that you specify using the UILaunchImageFile key in your app’s Info.plist file. The <scale_modifier> portion is the optional string @2x and should be included only for images intended for use on Retina displays. Other optional modifiers may also be included in the name, and several standard modifiers are discussed in the sections that follow. You must use these modifiers if your app targets iOS 6.1 or earlier.

Specify the launch images for your app in your Xcode project settings. In Xcode 5.0, specify these images on the General tab of your project settings; in older versions of Xcode, this tab may have a different name. Xcode places your launch image files at the top-level of the app bundle and configures other project settings as appropriate. Specifically, Xcode adds the UILaunchImages key to your app’s Info.plist file automatically if your app runs on iOS 7 or later. That key tells the system the name of your app’s launch image files. For earlier versions of iOS, the system uses the launch image filenames to decide which image to load.

Table 5-4 lists the dimensions for launch images in iOS apps. For all dimensions, the image width is listed first, followed by the image height. For precise information about which size launch image to use and how to prepare your launch images, see iOS Human Interface Guidelines.

Table 5-4  Typical launch image dimensions

Device

Portrait

Landscape

iPhone and iPod touch

320 x 480 pixels

640 x 960 pixels (@2x)

Not supported

iPhone 5 and iPod touch (5th generation)

640 x 1136 pixels (@2x)

Not supported

iPad

768 x 1024 pixels

1536 x 2048 pixels (@2x)

1024 x 768 pixels

2048 x 1536 pixels (@2x)

To demonstrate the naming conventions, suppose your iOS app’s Info.plist file included the UILaunchImageFile key with the value MyLaunchImage. The standard resolution version of the launch image would be named MyLaunchImage.png and would be in a portrait orientation (320 x 480). The high-resolution version of the same launch image would be named MyLaunchImage@2x.png. If you did not specify a custom launch image name, these files would need to be named Default.png and Default@2x.png, respectively.

To specify default launch images for iPhone 5 and iPod touch (5th generation) devices, include the modifier string -568h immediately after the <basename> portion of the filename. Because these devices have Retina displays, the @2x modifier must always be included with launch images for the devices. For example, the default launch image name for a device is Default-568h@2x.png. (If your app has the UILaunchImageFile key in its Info.plist file, replace the Default portion of the string with your custom string.) The -568h modifier should always be the first one in the list. You can also insert other modifiers after the -568h string as described below.

For more information about the UILaunchImageFile and UILaunchImages keys, see Information Property List Key Reference. You can provide localized versions of your launch images if necessary.

Providing Launch Images for Different Orientations

In iOS 3.2 and later, an iPad app can provide both landscape and portrait versions of its launch images. Each orientation-specific launch image must include a special modifier string in its filename. The format for orientation-specific launch image filenames is as follows:

<basename><orientation_modifier><scale_modifier><device_modifier>.png

Table 5-5 lists the possible modifiers you can specify for the <orientation_modifier> value in your image filenames. As with all launch images, each file must be in the PNG format. These modifiers are supported for launch images used in iPad apps only; they are not supported for apps running on iPhone or iPod touch devices.

Table 5-5  Launch image orientation modifiers

Modifier

Description

-PortraitUpsideDown

Specifies an upside-down portrait version of the launch image. A file with this modifier takes precedence over a file with the -Portrait modifier for this specific orientation.

-LandscapeLeft

Specifies a left-oriented landscape version of the launch image. A file with this modifier takes precedence over a file with the -Landscape modifier for this specific orientation.

-LandscapeRight

Specifies a right-oriented landscape version of the launch image. A file with this modifier takes precedence over a file with the -Landscape modifier for this specific orientation.

-Portrait

Specifies the generic portrait version of the launch image. This image is used for right-side up portrait orientations and takes precedence over the Default.png image file (or your custom-named replacement for that file). If a file with the -PortraitUpsideDown modifier is not specified, this file is also used for upside-down portrait orientations as well.

-Landscape

Specifies the generic landscape version of the launch image. If a file with the -LandscapeLeft or -LandscapeRight modifier is not specified, this image is used instead. This image takes precedence over the Default.png image file (or your custom-named replacement for that file).

(none)

If you provide a launch image file with no orientation modifier, that file is used when no other orientation-specific launch image is available. For apps running on systems earlier than iOS 3.2, you must name this file Default.png.

For example, if you specify the value MyLaunchImage in the UILaunchImageFile key, the custom landscape and portrait launch images for your iPad app would be named MyLaunchImage-Landscape.png and MyLaunchImage-Portrait.png. If you do not specify a custom launch image filename, you would use the names Default-Landscape.png and Default-Portrait.png.

No matter which launch image is displayed by the system, your app always launches in a portrait orientation initially and then rotates as needed to the correct orientation. Therefore, your application:didFinishLaunchingWithOptions: method should always assume a portrait orientation when setting up your window and views. Shortly after the application:didFinishLaunchingWithOptions: method returns, the system sends any necessary orientation-change notifications to your app’s window, giving it and your app’s view controllers a chance to reorient views using the standard process.

For more information about how your view controllers manage the rotation process, see “Creating Custom Content View Controllers” in View Controller Programming Guide for iOS.

Providing Device-Specific Launch Images

Universal apps must provide launch images for both the iPhone and iPad idioms. Because iPhone apps require only one launch image in a portrait orientation, whereas iPad apps typically require different images for portrait and landscape orientations, you can usually do without device-specific modifiers. However, if you create multiple launch images for each idiom, the names of device-specific image files are likely to collide. In that situation, you can append a device modifier to filenames to indicate that they are for a specific platform only. The following device modifiers are recognized for launch images in iOS 4.0 and later:

  • ~ipad. The launch image should be loaded on iPad devices only.

  • ~iphone. The launch image should be loaded on iPhone or iPod touch devices only.

Because device modifiers are not supported in iOS 3.2, the minimal set of launch images needed for a universal app (running in iOS 3.2 and later) would need to be named Default.png and Default~iphone.png. In that case, the Default.png file would contain the iPad launch image (for all orientations) and the Default~iphone.png file would contain the iPhone version of the image. (To support high-resolution displays, you would also need to include a Default@2x~iphone.png launch image.)

Providing Launch Images for Custom URL Schemes

If your app supports one or more custom URL schemes, it can also provide a custom launch image for each URL scheme. When the system launches your app to handle a URL, it displays the launch image associated with the scheme of the given URL. In this case, the format for your launch image filenames are as follows:

<basename>-<url_scheme><scale_modifier><device_modifier>.png

The <url_scheme> modifier is a string representing the name of your URL scheme name. For example, if your app supports a URL scheme with the name myscheme, the system looks for an image with the name Default-myscheme.png (or Default-myscheme@2x.png for Retina displays) in the app’s bundle. If the app’s Info.plist file includes the UILaunchImageFile key, the base name portion changes from Default to the custom string you provide in that key.

The Settings Bundle

Apps that want to display preferences in the Settings app must include a Settings bundle resource. A Settings bundle is a specially formatted bundle that sits at the top of your app’s bundle directory and contains the data needed to display your app’s preferences.

Xcode provides support for creating a Settings bundle resource and adding it to your app. Inside the Settings bundle, you place one or more property list files and any images associated with your preferences. Each property-list file contains special keys and values that tell the Settings app how to display different pages of your preferences. Changes to your app’s preferences are stored in the user defaults database and are accessible to your app using an NSUserDefaults object.

For detailed information about how to create a Settings bundle, see Preferences and Settings Programming Guide.

Localized Resource Files

Because iOS apps are distributed in many countries, localizing your app’s content can help you reach many more customers. Users are much more likely to use an app when it is localized for their native language. When you factor your user-facing content into resource files, localizing that content is a relatively simple process.

Before you can localize your content, you must internationalize your app in order to facilitate the localization process. Internationalizing your app involves factoring out any user-facing content into localizable resource files and providing language-specific project (.lproj) directories for storing that content. It also means using appropriate technologies (such as date and number formatters) when working with language-specific and locale-specific content.

For a fully internationalized app, the localization process creates new sets of language-specific resource files for you to add to your project. A typical iOS app requires localized versions of the following types of resource files:

For information about the internationalization and localization process, see Internationalization Programming Topics. For information about the proper way to use resource files in your app, see Resource Programming Guide.

Loading Resources Into Your App

Putting resources into your bundle is the first step but at runtime, you need to be able to load those resources into memory and use them. Resource management is broken down basically into two steps:

  1. Locate the resource.

  2. Load the resource.

  3. Use the resource.

To locate resources, you use an NSBundle object. A bundle object understands the structure of your app’s bundle and knows how to locate resources inside it. Bundle objects even use the current language settings to choose an appropriately localized version of the resource. The pathForResource:ofType: method is one of several NSBundle methods that you can use to retrieve the location of resource files.

Once you have the location of a resource file, you have to decide the most appropriate way to load it into memory. Common resource types usually have a corresponding class that you use to load the resource:

The following example shows how to load an image stored in a resource file in the app’s bundle. The first line gets the location of the file in the app’s bundle (also known as the main bundle here). The second line creates a UIImage object using the data in the file at that location.

NSString* imagePath = [[NSBundle mainBundle] pathForResource:@"sun" ofType:@"png"];
UIImage* sunImage = [[UIImage alloc] initWithContentsOfFile:imagePath];

For more information about resources and how to access them from your app, see Resource Programming Guide.