Expected App Behaviors

Every new Xcode project comes configured to run right away in iOS Simulator or on a device. But simply being able to run on a device does not mean that your app is ready to ship on the App Store. Every app requires some amount of customization to ensure a good experience for the user. Customizations can range from providing an icon for your app to making architectural-level decisions about how your app presents and uses information. This chapter describes the behaviors that all apps are expected to handle and that you should consider early in the planning process.

Providing the Required Resources

Every app you create must have the following set of resources and metadata so that it can be displayed properly on iOS devices:

These resources are required for all apps but are not the only ones you should include. There are many keys that Xcode does not include in your app’s Info.plist file by default. Most of the additional keys are important only if you incorporate specific features into your app. For example, an app that uses the microphone should include the NSMicrophoneUsageDescription key and provide the user with information about how the app intends to use it.

The App Bundle

When you build your iOS app, Xcode packages it as a bundle. A bundle is a directory in the file system that groups related resources together in one place. An iOS app bundle contains the app executable file and supporting resource files such as app icons, image files, and localized content. Table 1-1 lists the contents of a typical iOS app bundle, which for demonstration purposes is called MyApp. This example is for illustrative purposes only. Some of the files listed in this table may not appear in your own app bundles.

Table 1-1  A typical app bundle

File

Example

Description

App executable

MyApp

The executable file contains your app’s compiled code. The name of your app’s executable file is the same as your app name minus the .app extension.

This file is required.

The information property list file

Info.plist

The Info.plist file contains configuration data for the app. The system uses this data to determine how to interact with the app.

This file is required and must be called Info.plist. For more information, see The Information Property List File.

App icons

Icon.png

Icon@2x.png

Icon-Small.png

Icon-Small@2x.png

Your app icon is used to represent your app on the device’s Home screen. Other icons are used by the system in appropriate places. Icons with @2x in their filename are intended for devices with Retina displays.

An app icon is required. For information about specifying icon image files, see App Icons.

Launch images

Default.png

Default-Portrait.png

Default-Landscape.png

The system uses this file as a temporary background while your app is launching. It is removed as soon as your app is ready to display its user interface.

At least one launch image is required. For information about specifying launch images, see App Launch (Default) Images.

Storyboard files (or nib files)

MainBoard.storyboard

Storyboards contain the views and view controllers that the app presents on screen. Views in a storyboard are organized according to the view controller that presents them. Storyboards also identify the transitions (called segues) that take the user from one set of views to another.

The name of the main storyboard file is set by Xcode when you create your project. You can change the name by assigning a different value to the UIMainStoryboardFile key in the Info.plist file.) Apps that use nib files instead of storyboards can replace the UIMainStoryboardFile key with the NSMainNibFile key and use that key to specify their main nib file.

The use of storyboards (or nib files) is optional but recommended.

Ad hoc distribution icon

iTunesArtwork

If you are distributing your app ad hoc, include a 512 x 512 pixel version of your app icon. This icon is normally provided by the App Store from the materials you submit to iTunes Connect. However, because apps distributed ad hoc do not go through the App Store, your icon must be present in your app bundle instead. iTunes uses this icon to represent your app. (The file you specify should be the same one you would have submitted to the App Store, if you were distributing your app that way.)

The filename of this icon must be iTunesArtwork and must not include a filename extension. This file is required for ad hoc distribution but is optional otherwise.

Settings bundle

Settings.bundle

If you want to expose custom app preferences through the Settings app, you must include a settings bundle. This bundle contains the property list data and other resource files that define your app preferences. The Settings app uses the information in this bundle to assemble the interface elements required by your app.

This bundle is optional. For more information about preferences and specifying a settings bundle, see Preferences and Settings Programming Guide.

Nonlocalized resource files

sun.png

mydata.plist

Nonlocalized resources include things like images, sound files, movies, and custom data files that your app uses. All of these files should be placed at the top level of your app bundle.

Subdirectories for localized resources

en.lproj

fr.lproj

es.lproj

Localized resources must be placed in language-specific project directories, the names for which consist of an ISO 639-1 language abbreviation plus the .lproj suffix. (For example, the en.lproj, fr.lproj, and es.lproj directories contain resources localized for English, French, and Spanish.)

An iOS app should be internationalized and have a language.lproj directory for each language it supports. In addition to providing localized versions of your app’s custom resources, you can also localize your app icon, launch images, and Settings icon by placing files with the same name in your language-specific project directories.

For more information, see Internationalizing Your App.

For more information about the structure of an iOS app bundle, see Bundle Programming Guide. For information about how to load resource files from your bundle, see Resource Programming Guide.

The Information Property List File

Xcode uses information from the General, Capabilities, and Info tabs of your project to generate an information property list (Info.plist) file for your app at compile time. The Info.plist file is a structured file that contains critical information about your app’s configuration. It is used by the App Store and by iOS to determine your app’s capabilities and to locate key resources. Every app must include this file.

Although the Info.plist file provided by Xcode includes default values for all of the required entries, most apps require some changes or additions. Whenever possible, use the General and Capabilities tabs to specify the configuration information for your app. Those tabs contain the most common configuration options available for apps. If you do not see a specific option on either of those tabs, use the Info tab.

For options where Xcode does not provide a custom configuration interface, you must provide appropriate keys and values directly using the Xcode property list editor. The Custom iOS Target Properties section of the Info tab contains a summary of the entries to be included in the Info.plist file. By default, Xcode displays human-readable descriptions of the intended feature but each feature actually corresponds to a unique key in the Info.plist file. Most keys are optional and used infrequently, but there are a handful of keys that you should consider when defining any new project:

  • Declare your app’s required capabilities in the Info tab. The Required device capabilities section contains information about the device-level features that your app requires to run. The App Store uses the information in this entry to determine the capabilities of your app and to prevent it from being installed on devices that do not support features your app requires. For more information, see Declaring the Required Device Capabilities.

  • Apps that require a persistent Wi-Fi connection must declare that fact. If your app talks to a server across the network, you can add the Application uses Wi-Fi entry to the Info tab of your project. This entry corresponds to the UIRequiresPersistentWiFi key in the Info.plist file. Setting this key to YES prevents iOS from closing the active Wi-Fi connection when it has been inactive for an extended period of time. This key is recommended for all apps that use the network to communicate with a server.

  • Newsstand apps must declare themselves as such. Include the UINewsstandApp key to indicate that your app presents content from the Newsstand app.

  • Apps that define custom document types must declare those types. Use the Document Types section of the Info tab to specify icons and UTI information for the document formats that you support. The system uses this information to identify apps capable of handling specific file types. For more information about adding document support to your app, see Document-Based App Programming Guide for iOS.

  • Apps can declare any custom URL schemes they support. Use the URL Types section of the Info tab to specify the custom URL schemes that your app handles. Apps can use custom URL schemes to communicate with each other. For more information about how to implement support for this feature, see Using URL Schemes to Communicate with Apps.

  • Apps must provide purpose strings (sometimes called “usage descriptions”) for accessing user data and certain app features. When there is a privacy concern about an app accessing user data or device capabilities, iOS prompts the user and requests permission on behalf of your app. An app must explain to the user, by way of a purpose string defined in its Info.plist file, why it requires access. If your app attempts to gain access without having provided a corresponding purpose string, your app exits.

    The data and features that require user permission are described in Table 1-2. Purpose strings are described in the Cocoa Keys chapter of Information Property List Key Reference.

For detailed information about the keys and values you can include in the Info.plist file, see Information Property List Key Reference.

Declaring the Required Device Capabilities

All apps must declare the device-specific capabilities they need to run. Xcode includes a Required device capabilities entry in your project’s Info tab and populates it with some minimum requirements. You can add values to this entry to specify additional requirements for your app. The Required device capabilities entry corresponds to the UIRequiredDeviceCapabilities key in your app’s Info.plist file.

The value of the UIRequiredDeviceCapabilities key is either an array or 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.

For detailed information on the values you can include for the UIRequiredDeviceCapabilities key, see Information Property List Key Reference.

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.

New Xcode projects include image asset entries for your app’s icon images. To add icons, assign the corresponding image files to the image assets of your project. At build time, Xcode adds the appropriate keys to your app’s Info.plist file and places the images in your app bundle.

For information about designing your app icons, including the sizes of those icons, see iOS Human Interface Guidelines.

App Launch (Default) Images

When the system launches an app for the first time on a device, it temporarily displays a static launch image on the screen. This image is your app’s launch image and it is a resource that you specify in your Xcode project. Launch images provide the user with immediate feedback that your app has launched while giving your app time to prepare its initial user interface. When your app’s window is configured and ready to be displayed, the system swaps out the launch image for that window.

When a recent snapshot of your app’s user interface is available, the system prefers the use of that image over the use of your app’s launch images. The system takes a snapshot of your app’s user interface when your app transitions from the foreground to the background. When your app returns to the foreground, it uses that image instead of a launch image whenever possible. In cases where the user has killed your app or your app has not run for a long time, the system discards the snapshot and relies once again on your launch images.

New Xcode projects include image asset entries for your app’s launch images. To add launch images, add the corresponding image files to the image assets of your project. At build time, Xcode adds the appropriate keys to your app’s Info.plist file and places the images in your app bundle.

For information about designing your app’s launch images, including the sizes of those images, see iOS Human Interface Guidelines.

Supporting User Privacy

Designing for user privacy is important. Most iOS devices contain personal data that the user might not want to expose to apps or to external entities. If your app accesses or uses data inappropriately, the user might respond by deleting your app.

Access user or device data only with the user’s informed consent obtained in accordance with applicable law. In addition, take appropriate steps to protect user and device data and be transparent about how you use it. Here are some best practices that you can take:

Table 1-2 lists the types of resource and data authorizations supported by iOS. For each item, the table shows the purpose-string key and the API to use to check authorization status.

For some protected data and resources, iOS frameworks provide dedicated API for checking and requesting authorization, as described in Table 1-2.

Because a user can change authorization at any time by using Settings, check authorization status before accessing any of these items. (Some features, notably motion and HomeKit, do not provide dedicated API for checking system authorization status. See Table 1-2 for details.)

Table 1-2  Data and resources protected by system authorization settings

Data or resources

Purpose-string Info.plist keys

System authorization APIs

Bluetooth peripherals

NSBluetoothPeripheralUsageDescription

Use the state property of the CBCentralManager class to check system-authorization status for using Bluetooth peripherals.

Calendar data

NSCalendarsUsageDescription

Use the authorizationStatusForEntityType: method of the EKEventStore class to check system-authorization status for accessing calendar data.

Camera

NSCameraUsageDescription

Use the deviceInputWithDevice:error: method of the AVCaptureDeviceInput class to check system-authorization status for using device cameras.

Contacts

NSContactsUsageDescription

Use the authorizationStatusForEntityType: method of the CNContactStore class to check system-authorization status for accessing contact data.

Health sharing

NSHealthShareUsageDescription

Use the authorizationStatusForType: method of the HKHealthStore class to check system-authorization status for accessing health data.

To request authorization, use the requestAuthorizationToShareTypes:readTypes:completion: method.

Health updating

NSHealthUpdateUsageDescription

Use the authorizationStatusForType: method of the HKHealthStore class to check system-authorization status for accessing health data.

To request authorization, use the requestAuthorizationToShareTypes:readTypes:completion: method.

HomeKit

NSHomeKitUsageDescription

When your app first attempts to access a property of the HMHomeManager class, the system presents an authorization request to the user.

Location

NSLocationAlwaysUsageDescription, NSLocationWhenInUseUsageDescription

Use the authorizationStatus method of the CLLocationManager class to check system-authorization status for accessing location data.

To request authorization, use the requestWhenInUseAuthorization or the requestAlwaysAuthorization method.

Microphone

NSMicrophoneUsageDescription

Use the recordPermission method of the AVAudioSession class to check system-authorization status for using device microphones.

To request authorization, use the requestRecordPermission: method.

Motion

NSMotionUsageDescription

Check for a CMErrorNotAuthorized error from the queryActivityStartingFromDate:toDate:toQueue:withHandler: method of the CMMotionActivityManager class to check system-authorization status for accelerometer access.

Music and the media library

NSAppleMusicUsageDescription

Use the authorizationStatus method of the ALAssetsLibrary class to check system-authorization status for accessing media assets.

Photos

NSPhotoLibraryUsageDescription

Use the authorizationStatus method of the PHPhotoLibrary class to check system-authorization status for accessing the photo library.

Reminders

NSRemindersUsageDescription

Use the authorizationStatusForEntityType: method of the EKEventStore class to check system-authorization status for accessing reminder data.

Siri

NSSiriUsageDescription

Use the siriAuthorizationStatus method of the INPreferences class to check system-authorization status for using Siri.

To request authorization for your app to use SiriKit, use the requestSiriAuthorization: method.

Speech recognition

NSSpeechRecognitionUsageDescription

Use the authorizationStatus authorizationStatus method of the SFSpeechRecognizer class to check system-authorization status for using speech recognition.

To request authorization for your app to use speech recognition, use the requestAuthorization method.

TV provider

NSVideoSubscriberAccountUsageDescription

Use the checkAccessStatusWithOptions:completionHandler: method of the VSAccountManager class to check system-authorization status for accessing the user’s video service subscription information.

To request authorization, use the enqueueResourceAuthorizationRequest:completionHandler: method.

View Table 1-2 as a starting point for your app’s privacy behaviors and not as a comprehensive checklist. This table’s contents evolves across iOS updates.

Internationalizing Your App

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 and Localization Guide. For information about the proper way to use resource files in your app, see Resource Programming Guide.