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
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
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:
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.
To enable background
audio playback and recording, include the following key-value pair
in the InfoAdditions element:
Background location updates
background location updates, include the following key-value pair
in the InfoAdditions element:
Note: Use this feature only when
necessary, as location APIs are a significant drain on the battery.
To execute short
tasks in the background, your application sets the NativeApplication.nativeApplication.executeInBackground property
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.
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
application can explicitly opt out of background execution by including
the following key-value pair in the InfoAdditions element:
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:
(reserved till 3.2)
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.The <string>3</string> setting
defines support for the tvOS. If you specify only one of these strings,
only that device family is supported. For example, the following
setting limits support to the iPad:
The following setting supports both device families (iPhone/iPod
Touch and iPad):
The following setting limits support for tvOS:
Note: If UIDeviceFamily is not provided and tvOS provisioning is given, then the UIDeviceFamily value equal to 3 is added automatically in the final IPA that is generated.
Note: Following warnings appear if there is a mismatch between the provisioning profile and the UIDeviceFamily value:
Warning: Provisioning profile specified for tvOS, ignoring iOS UIDeviceFamily value(s).
Warning: Provisioning profile specified for iOS, ignoring tvOS UIDeviceFamily value(s).
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:
<forceCPURenderModeForDevices>iPad1,1 iPhone1,1 iPhone1,2 iPod1,1
The requestedDisplayResolution element
specifies whether your application should use the standard or high resolution
mode on iOS devices with high-resolution screens.
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:
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.
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
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:
If a device lacks the corresponding capability, the application
cannot be installed. The capability settings relevant to AIR applications
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
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:
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
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.
For Geolocation support, add one of the following key-value
pairs to the InfoAdditions element:
<string>Sample description to allow geolocation always</string>
<string>Sample description to allow geolocation when application is in foreground</string>
<string>Sample description to allow geolocation always and when application is in foreground</string>