iOS Settings

Settings that apply only to iOS devices are placed within the <iPhone> element in the application descriptor. The iPhone element can have an InfoAdditions element, a requestedDisplayResolution element, an Entitlements element, an externalSwfs element, and a forceCPURenderModeForDevices element as children.

The InfoAdditions element lets you specify key-value pairs that are added to the Info.plist settings file for the application. For example, the following values set the status bar style of the application and state that the application does not require persistent Wi-Fi access.
<InfoAdditions> 
    <![CDATA[ 
        <key>UIStatusBarStyle</key> 
        <string>UIStatusBarStyleBlackOpaque</string> 
        <key>UIRequiresPersistentWiFi</key> 
        <string>NO</string> 
    ]]> 
</InfoAdditions>

The InfoAdditions settings are enclosed in a CDATA tag.

Th Entitlements element lets you specify key-value pairs added to the Entitlements.plist settings file for the application. Entitlements.plist settings provide application access to certain iOS features, such as push notifications.

For more detailed information on Info.plist and Entitlements.plist settings, see the Apple developer documentation.

Supporting background tasks on iOS

Adobe AIR 3.3 and higher supports multitasking on iOS by enabling certain background behaviors:

  • Audio

  • Location updates

  • Networking

  • Opting out of background app execution

Note: With swf-version 21 and its earlier versions, AIR does not support background execution on iOS and Android when render mode direct is set. Due to this restriction, Stage3D based apps cannot execute background tasks like audio playback, location updates, network upload or download, etc. iOS does not allow OpenGLES or rendering of calls in the background. Applications which attempt to make OpenGL calls in the background are terminated by iOS. Android does not restrict applications from either making OpenGLES calls in the background or performing other background tasks like audio playback. With swf-version 22 and later, AIR mobile applications can execute in the background when renderMode direct is set. The AIR iOS runtime results in an ActionScript error (3768 - The Stage3D API may not be used during background execution) if OpenGLES calls are made in the background. However, there are no errors on Android because its native applications are allowed to make OpenGLES calls in the background. For optimal utilization of mobile resource, do not make rendering calls while an application is executing in the background.

Background audio

To enable background audio playback and recording, include the following key-value pair in the InfoAdditions element:

<InfoAdditions> 
    <![CDATA[ 
       <key>UIBackgroundModes</key> 
           <array> 
               <string>audio</string> 
            </array> 
    ]]> 
</InfoAdditions>

Background location updates

To enable background location updates, include the following key-value pair in the InfoAdditions element:

<InfoAdditions> 
    <![CDATA[ 
        <key>UIBackgroundModes</key> 
        <array> 
               <string>location</string> 
         </array> 
    ]]> 
</InfoAdditions>
Note: Use this feature only when necessary, as location APIs are a significant drain on the battery.

Background networking

To execute short tasks in the background, your application sets the NativeApplication.nativeApplication.executeInBackground property to true.

For example, your application may start a file upload operation after which the user moves another application to the front. When the application receives an upload completion event, it can set NativeApplication.nativeApplication.executeInBackground to false.

Setting the NativeApplication.nativeApplication.executeInBackground property to true does not guarantee the application will run indefinitely, as iOS imposes a time limit on background tasks. When iOS stops background processing, AIR dispatches the NativeApplication.suspend event.

Opting out of background execution

Your application can explicitly opt out of background execution by including the following key-value pair in the InfoAdditions element:

<InfoAdditions> 
    <![CDATA[ 
       <key>UIApplicationExitsOnSuspend</key> 
       <true/> 
    ]]> 
</InfoAdditions>

Reserved iOS InfoAdditions settings

AIR sets several entries in the generated Info.plist file to ensure that application and runtime features work correctly. You cannot define the following settings:

CFBundleDisplayName

CFBundleExecutable

CFBundleIconFiles

CFBundleIdentifier

CFBundleInfoDictionaryVersion

CFBundlePackageType

CFBundleResourceSpecification

CFBundleShortVersionString

CFBundleSupportedPlatforms

CFBundleVersion

CTAutoOrients

CTInitialWindowTitle

CTInitialWindowVisible

CTIosSdkVersion

CTMaxSWFMajorVersion

DTPlatformName

DTSDKName

MinimumOSVersion (reserved till 3.2)

NSMainNibFile

UIInterfaceOrientation

UIStatusBarHidden

UISupportedInterfaceOrientations

Note: You can define the MinimumOSVersion. The MinimumOSVersion definition is honoured in Air 3.3 and later.

Supporting different iOS device models

For iPad support, include the proper key-value settings for UIDeviceFamily within your InfoAdditions element. The UIDeviceFamily setting is an array of strings. Each string defines supported devices. The <string>1</string> setting defines support for the iPhone and iPod Touch. The <string>2</string> setting defines support for the iPad. If you specify only one of these strings, only that device family is supported. For example, the following setting limits support to the iPad:

<key>UIDeviceFamily</key> 
    <array> 
        <string>2</string> 
    </array>>

The following setting supports both device families (iPhone/iPod Touch and iPad):

<key>UIDeviceFamily</key> 
<array> 
    <string>1</string> 
    <string>2</string> 
</array>

Additionally, in AIR 3.7 and higher, you can use the forceCPURenderModeForDevices tag to force CPU render mode for a specified set of devices and enable GPU render mode for remaining iOS devices.

You add this tag as a child of the iPhone tag and specify a space-separated list of device model names. For a list of valid device model names, see forceCPURenderModeForDevices.

For example, to use CPU mode in old iPods, iPhones, and iPads and enable GPU mode for all other devices, specify the following in the application descriptor:

... 
<renderMode>GPU</renderMode> 
... 
<iPhone> 
... 
   <forceCPURenderModeForDevices>iPad1,1 iPhone1,1 iPhone1,2 iPod1,1 
   </forceCPURenderModeForDevices> 
</iPhone>

High-resolution displays

The requestedDisplayResolution element specifies whether your application should use the standard or high resolution mode on iOS devices with high-resolution screens.

<requestedDisplayResolution>high</requestedDisplayResolution>

In high-resolution mode, you can address each pixel on a high-resolution display individually. In the standard mode, the device screen will appear to your application as a standard resolution screen. Drawing a single pixel in this mode will set the color of four pixels on the high-resolution screen.

The default setting is standard. Note that for targeting iOS devices, you use the requestedDisplayResolution element as a child of the iPhone element (not the InfoAdditions element or initialWindow element).

If you want to use different settings on different devices, specify your default value as the requestedDisplayResolution element’s value. Use the excludeDevices attribute to specify devices that should use the opposite value. For example, with the following code, high resolution mode is used for all devices that support it except 3rd-generation iPads, which use standard mode:

<requestedDisplayResolution excludeDevices="iPad3">high</requestedDisplayResolution>

The excludeDevices attribute is available in AIR 3.6 and later.

iOS custom URI schemes

You can register a custom URI scheme to allow your application to be invoked by a link in a web page or another, native application on the device. To register a URI scheme, add a CFBundleURLTypes key to the InfoAdditions element. The following example registers a URI scheme named com.example.app to allow an application to be invoked by URLs with the form: example://foo.

<key>CFBundleURLTypes</key> 
<array> 
    <dict> 
         <key>CFBundleURLSchemes</key> 
        <array> 
            <string>example</string> 
        </array> 
        <key>CFBundleURLName</key> 
        <string>com.example.app</string> 
    </dict> 
</array>

When your application is invoked through a custom URI, the NativeApplication object dispatches an invoke event. The URL of the link, including query parameters, is placed in the arguments array of the InvokeEvent object. You can use any number of custom URI schemes.

Note: Links in a StageWebView instance cannot open URLs that use a custom URI scheme.
Note: If another application has already registered a scheme, then your application cannot replace it as the application registered for that URI scheme.

iOS compatibility filtering

Add entries to a UIRequiredDeviceCapabilities array within the InfoAdditions element if your application should only be used on devices with specific hardware or software capabilities. For example, the following entry indicates that an application requires a still camera and a microphone:

<key>UIRequiredDeviceCapabilities</key> 
<array> 
    <string>microphone</string> 
    <string>still-camera</string> 
</array>

If a device lacks the corresponding capability, the application cannot be installed. The capability settings relevant to AIR applications include:

telephony

wifi

sms

still-camera

auto-focus-camera

front-facing-camera

camera-flash

video-camera

accelerometer

location-services

gps

microphone

AIR 2.6+ automatically adds armv7 and opengles-2 to the list of required capabilities.

Note: You do not need to include these capabilities in the application descriptor in order for your application to use them. Use the UIRequiredDeviceCapabilities settings only to prevent users from installing your application on devices on which it cannot function properly.

Exiting instead of pausing

When a user switches away from an AIR application it enters the background and pauses. If you want your application to exit completely instead of pausing, set the UIApplicationExitsOnSuspend property to YES:

<key>UIApplicationExitsOnSuspend</key> 
<true/>

Minimize download size by loading external, asset-only SWFs

You can minimize your initial application download size by packaging a subset of the SWFs used by your application and loading the remaining (asset-only) external SWFs at runtime using the Loader.load() method. To use this feature, you must package the application such that ADT moves all ActionScript ByteCode (ABC) from the externally loaded SWF files to the main application SWF, leaving a SWF file that contains only assets. This is to conform with the Apple Store’s rule that forbids downloading any code after an application is installed.

ADT does the following to support externally loaded SWFs (also called stripped SWFs):

  • Reads the text file specified in the <iPhone> element’s <externalSwfs> subelement to access the line-delimited list of SWFs to be loaded at execution time:

    <iPhone> 
       ... 
       <externalSwfs>FilewithPathsOfSWFsThatAreToNotToBePackaged.txt</externalSwfs> 
    </iPhone>
  • Transfers the ABC code from each externally loaded SWF to the main executable.

  • Omits the externally loaded SWFs from the .ipa file.

  • Copies the stripped SWFs to the .remoteStrippedSWFs directory. You host these SWFs on a web server and your application loads them, as necessary, at runtime.

You indicate the SWF files to be loaded at runtime by specifying their names, one per line in a text file, as the following example shows:

assets/Level1/Level1.swf 
assets/Level2/Level2.swf 
assets/Level3/Level3.swf 
assets/Level4/Level4.swf

The file path specified is relative to the application descriptor file. Additionally, you must specify these swfs as assets in the adt command.

Note: This feature applies to standard packaging only. For fast packaging (using for example, using interpreter, simulator, or debug) ADT does not create stripped SWFs.