Setting mobile application propertiesAs with other AIR applications, you set the basic application properties in the application descriptor file. Mobile applications ignore some of the desktop-specific properties, such as window size and transparency. Mobile applications can also use their own platform-specific properties. For example, you can include an android element for Android apps and an iPhone element for iOS apps. Common settingsSeveral application descriptor settings are important for all mobile device applications. Required AIR runtime versionSpecify the version of the AIR runtime required by your application using the namespace of the application descriptor file. The namespace, assigned in the application element, determines, in large part, which features your application can use. For example, if your application uses the AIR 2.5 namespace, and the user has some future version installed, then your application will still see the AIR 2.5 behavior (even if the behavior has been changed in the future version). Only when you change the namespace and publish an update will your application have access to the new behavior and features. Security fixes are an important exception to this rule. On devices that use a runtime separate from the application, such as Android, the user will be prompted to install or upgrade AIR if they do not have the required version. On devices that incorporate the runtime, such as iPhone, this situation does not occur (since the required version is packaged with the app in the first place). Specify the namespace using the xmlns attribute of the root application element. The following namespaces can be used for mobile applications (depending on which mobile platform you are targeting: iOS only: <application xmlns="http://ns.adobe.com/air/application/2.0"> Android only: <application xmlns="http://ns.adobe.com/air/application/2.5"> AIR 2 is the first version of AIR to support mobile devices; AIR 2.5 is the first to support Android. Application identitySeveral settings should be unique for each application that you publish. These include the ID, the name, and the filename. On Android, the ID is converted to the Android package name by prefixing “air.” to the AIR ID. Thus, if your AIR ID is com.example.MyApp, then the Android package name is air.com.example.MyApp. <id>com.example.MyApp</id> <name>My Application</name> <filename>MyApplication</filename> In addition, if the ID is not a legal package name on the Android operating system, it is converted to a legal name. Hyphen characters are changed to underscores and leading digits in any ID component are preceded by a capital “A”. For example, the ID: 3-goats.1-boat, is transformed to the package name: air.A3_goats.A1_boat. Application versionIn versions of AIR earlier than AIR 2.5, specify the application in the version element. You can use any string. The AIR runtime does not interpret the string; “2.0” is not treated as a higher version than “1.0.” <!-- AIR 2 or earlier --> <version>1.23 Beta 7</version> In AIR 2.5 and later, specify the application version in the versionNumber element. The version element can no longer be used. When specifying a value for versionNumber, you must use a sequence of up to three numbers separated by dots, such as: “0.1.2”. Each segment of the version number can have up to three digits. (In other words, “999.999.999” is the largest version number permitted.) You do not have to include all three segments in the number; “1” and “1.0” are legal version numbers as well. You can also specify a label for the version using the versionLabel element. When you add a version label it is displayed instead of the version number in such places as the Android Application info screen. A version label must be specified for apps that are distributed using the Android Market. If you do not specify a versionLabel value in the AIR application descriptor, then the versionNumber value is assigned to the Android version label field. <!-- AIR 2.5 and later --> <versionNumber>1.23.7<versionNumber> <versionLabel>1.23 Beta 7</versionLabel> Main application SWFSpecify the main application SWF file in the content child of the initalWindow element. When you target devices in the mobile profile, you must use a SWF file (HTML-based applications are not supported). <initialWindow>
<content>MyApplication.swf</content>
</initialWindow>
You must include the file in the AIR package (using ADT or your IDE). Simply referencing the name in the application descriptor does not cause the file to be included in the package automatically. Main screen propertiesSeveral child elements of the initialWindow element control the initial appearance and behavior of the main application screen.
Supported profilesYou can add the supportedProfiles element to specify which device profiles your application supports. Use the mobileDevice profile for mobile devices. When you run your application with the Adobe Debug Launcher (ADL), ADL uses the first profile in the list as the active profile. You can also use the -profile flag when running ADL to select a particular profile in the supported list. If your application runs under all profiles, you can leave the supportedProfiles element out altogether. ADL uses the desktop profile as the default active profile in this case. To specify that your application supports both the mobile device and desktop profiles, and you normally want to test the app in the mobile profile, add the following element: <supportedProfiles>mobileDevice desktop</supportedProfiles> Android settingsOn the Android platform, you can use the android element of the application descriptor to add information to the Android application manifest, which is an application properties file used by the Android operating system. ADT automatically generates the Android Manifest.xml file when you create the APK package. AIR sets a few properties to the values required for certain features to work. Any other properties set in the android section of the AIR application descriptor are added to the corresponding section of the Manifest.xml file. Note: For most AIR applications, you must set the Android permissions
needed by your application within the android element,
but you generally will not need to set any other properties.
You can only set attributes that take string, integer, or boolean values. Setting references to resources in the application package is not supported. Reserved Android manifest settingsAIR sets several manifest entries in the generated Android manifest document to ensure that application and runtime features work correctly. You cannot override the following settings: manifest elementYou cannot set the following attributes of the manifest element:
activity elementYou cannot set the following attributes for the main activity element:
application elementYou cannot set the following attributes of the application element:
Android permissionsThe Android security model requires that each app request permission in order to use features that have security or privacy implications. These permissions must be specified when the app is packaged, and cannot be changed at runtime. The Android operating system informs the user which permissions an app is requesting when the user installs it. If a permission required for a feature is not requested, the Android operating system might throw an exception when your application access the feature, but an exception is not guaranteed. Exceptions are transmitted by the runtime to your application. In the case of a silent failure, a permission failure message is added to the Android system log. In AIR, you specify the Android permissions inside the android element of the application descriptor. The following format is used for adding permissions (where PERMISSION_NAME is the name of an Android permission): <android>
<manifestAdditions>
<![CDATA[
<manifest>
<uses-permission android:name="android.permission.PERMISSION_NAME" />
</manifest>
]]>
</manifestAdditions>
</android>
The uses-permissions statements inside the manifest element are added directly to the Android manifest document. The following permissions are required to use various AIR features:
For example, to set the permissions for an app that impressively requires every permission, you could add the following to the application descriptor: <android>
<manifestAdditions>
<![CDATA[
<manifest>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.DISABLE_KEYGUARD" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
</manifest>
]]>
</manifestAdditions>
</android>
Android custom URI schemesYou can use a custom URI scheme to launch an AIR application from a web page or a native Android application. Custom URI support relies on intent filters specified in the Android manifest, so this technique cannot be used on other platforms. To use a custom URI, add an intent-filter to the application descriptor within the <android> block. Both intent-filter elements in the following example must be specified. Edit the <data android:scheme="my-customuri"/> statement to reflect the URI string for your custom scheme. <android>
<manifestAdditions>
<![CDATA[
<manifest>
<application>
<activity>
<intent-filter>
<action android:name="android.intent.action.MAIN"/>
<category android:name="android.intent.category.LAUNCHER"/>
</intent-filter>
<intent-filter>
<action android:name="android.intent.action.VIEW"/>
<category android:name="android.intent.category.BROWSABLE"/>
<category android:name="android.intent.category.DEFAULT"/>
<data android:scheme="my-customuri"/>
</intent-filter>
</activity>
</application>
</manifest>
]]>
</manifestAdditions>
</android>
An intent filter informs the Android operating system that your application is available to perform a given action. In the case of a custom URI, this means that the user has clicked a link using that URI scheme (and the browser does not know how to handle it). 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 intent-filters. Note: Neither the navigateToURL() function nor
links in a StageWebView instance can open URLs that use a custom
URI scheme.
Android compatibility filteringThe Android operating system uses a number of elements in the application manifest file to determine whether your application is compatible with a given device. Adding this information to the manifest is optional. If you do not include these elements, your application can be installed on any Android device. However, it may not operate properly on any Android device. For example, a camera app will not be very useful on a phone that does not have a camera. The Android manifest tags that you can use for filtering include:
Camera applicationsIf you request the camera permission for your application, Android assumes that the app requires all available camera features, including auto-focus and flash. If your app does not require all camera features, or if the camera is an optional feature, you should set the various uses-feature elements for the camera to indicate that these are optional. Otherwise, users with devices that are missing one feature or that do not have a camera at all, will not be able to find your app on the Android Market. The following example illustrates how to request permission for the camera and make all camera features optional: <android>
<manifestAdditions>
<![CDATA[
<manifest>
<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" android:required="false"/>
<uses-feature android:name="android.hardware.camera.autofocus" android:required="false"/>
<uses-feature android:name="android.hardware.camera.flash" android:required="false"/>
</manifest>
]]>
</manifestAdditions>
</android>
Audio recording applicationsIf you request the permission to record audio, Android also assumes that the app requires a microphone. If audio recording is an optional feature of your app, you can add a uses-feature tag to specify that the microphone is not required. Otherwise, users with devices that do not have a microphone, will not be able to find your app on the Android Market. The following example illustrates how to request permission to use the microphone while still making the microphone hardware optional: <android>
<manifestAdditions>
<![CDATA[
<manifest>
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-feature android:name="android.hardware.microphone" android:required="false"/>
</manifest>
]]>
</manifestAdditions>
</android>
Install locationYou can permit your application to be installed or moved to the external memory card by setting the installLocation attribute of the Android manifest element to either auto or preferExternal: <android>
<manifestAdditions>
<![CDATA[
<manifest android:installLocation="preferExternal"/>
]]>
</manifestAdditions>
</android>
The Android operating system doesn’t guarantee that your app will be installed to the external memory. A user can also move the app between internal and external memory using the system settings app. Even when installed to external memory, application cache and user data, such as the contents of the app-storage directory, shared objects, and temporary files, are still stored in the internal memory. To avoid using to much internal memory, be selective about the data you save to the application storage directory. Large amounts of data should be saved to the SDCard using the File.userDirectory or File.documentsDirectory locations (which both map to the root of the SD card on Android). Application iconsThe following table lists the icon sizes used on each mobile platform:
On Android, the icons specified in the application descriptor are used as the application Launcher icon. The application Launcher icon should be supplied as a set of 36x36-, 48x48-, and 72x72-pixel PNG images. These icon sizes are used for low-density, medium-density, and high-density screens, respectively. Specify the path to the icon files in the icon element of the application descriptor file: <icon>
<image36x36>assets/icon36.png</image36x36>
<image48x48>assets/icon48.png</image48x48>
<image72x72>assets/icon72.png</image72x72>
</icon>
If you do not supply an icon of a given size, the next largest size is used and scaled to fit. iOS settingsSee the Packager for iPhone guide for information about creating an application descriptor for an iOS app. Ignored settingsApplications on mobile devices ignore application settings that apply to native windows or desktop operating system features. The ignored settings are:
|
|