Developing AIR Apps For Android
Developing AIR Apps For Android
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
Copyright 2010 Adobe Systems Incorporated and its licensors. All rights reserved. Developing Adobe AIR Applications for Android Prerelease This prerelease version of the Software may not contain trademarks and copyright notices that will appear in the commercially available version of the Software. This guide is protected under copyright law, furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide. This guide is licensed for use under the terms of the Creative Commons Attribution Non-Commercial 3.0 License. This License allows users to copy, distribute, and transmit the guide for noncommercial purposes only so long as (1) proper attribution to Adobe is given as the owner of the guide; and (2) any reuse or distribution of the guide contains a notice that use of the guide is governed by these terms. The best way to provide notice is to include the following link. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ Adobe, the Adobe logo, Adobe AIR, ActionScript, AIR, Flash, Flash Builder, Flash Lite, Flex, MXML, and Pixel Bender are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Macintosh is a trademark of Apple Inc., registered in the United States and other countries. ActiveX and Windows are registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Java is a trademark or registered trademark of Sun Microsystems, Inc. in the United States and other countries. All other trademarks are the property of their respective owners. Updated Information/Additional Third Party Code Information available at http://www.adobe.com/go/thirdparty. Portions include software under the following terms: This product includes software developed by the Apache Software Foundation (http://www.apache.org/). This product includes software developed by Fourthought, Inc. (http://www.fourthought.com). MPEG Layer-3 audio compression technology licensed by Fraunhofer IIS and Thomson Multimedia (http://www.iis.fhg.de/amm/). This software is based in part on the work of the Independent JPEG Group. Speech compression and decompression technology licensed from Nellymoser, Inc. (www.nellymoser.com). Video in Flash Player is powered by On2 TrueMotion video technology. 1992-2005 On2 Technologies, Inc. All Rights Reserved. http://www.on2.com. This product contains either BSAFE and/or TIPEM software by RSA Security, Inc.
Sorenson Spark video compression and decompression technology licensed from Sorenson Media, Inc. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA Notice to U.S. Government End Users: The Software and Documentation are Commercial Items, as that term is defined at 48 C.F.R. 2.101, consisting of Commercial Computer Software and Commercial Computer Software Documentation, as such terms are used in 48 C.F.R. 12.212 or 48 C.F.R. 227.7202, as applicable. Consistent with 48 C.F.R. 12.212 or 48 C.F.R. 227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States. Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
Contents
Getting Started ................................................................................................................................... 5 Workflow for developing and testing an AIR for Android app ................................................................. 5 Available Documentation.......................................................................................................................... 5 Flash Platform tool support ...................................................................................................................... 5 Installing the Android SDK ........................................................................................................................ 6 Creating a Hello World application ........................................................................................................... 7 Setting the path environment variable ................................................................................................... 18 Building AIR applications for Android ........................................................................................... 21 Android icon art ...................................................................................................................................... 21 Setting application properties ................................................................................................................ 21 Packaging an Android application ........................................................................................................... 23 Installing Adobe AIR and AIR for Android apps....................................................................................... 24 Running an Android application on a device .......................................................................................... 25 Running AIR applications in the Android emulator ................................................................................ 26 Debugging an application on the device ................................................................................................. 27 Distributing an AIR for Android application ............................................................................................ 28 Supported Flash and AIR APIs ....................................................................................................... 29 Designing AIR applications for Android......................................................................................... 31 Improve display object performance ...................................................................................................... 31 Information density ................................................................................................................................ 32 Fonts and text input ................................................................................................................................ 32 Application design considerations .......................................................................................................... 32 Saving application state .......................................................................................................................... 33 Screen orientation changes .................................................................................................................... 33 Hit targets ............................................................................................................................................... 33 Memory allocation .................................................................................................................................. 33 Drawing API ............................................................................................................................................. 34 Event bubbling ........................................................................................................................................ 34 Optimizing video performance ............................................................................................................... 34
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
Reducing application file size .................................................................................................................. 34 Differences between Android and iPhone development ....................................................................... 35 Miscellaneous development notes ......................................................................................................... 35
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
1.
This chapter includes information on setting up your development environment. It also includes a Hello World example.
Available Documentation
In addition to this document, the following documentation is available: Release notes (on the Adobe prerelease website) Building Adobe AIR applications ActionScript 3.0 Reference for the Adobe Flash Platform
See the release notes for a comprehensive list of AIR for Android issues.
May 19, 2010 Instructions for updating the AIR SDKs used in Flash Builder and Flash CS4 Professional are provided in the release notes. To develop an AIR for Android application using the command-line tools, you will need a recent Flex SDK and the AIR 2.5 SDK available on the AIR for Android prerelease website. Use the Android SDK tools to install the application on a device or Android emulator. AIR for Android does not support HTML-based applications. The desktop version of the Flex framework is not recommended for use on mobile devices. Adobe is working on a mobile update for the Flex framework, code named Slider. For more information, see http://labs.adobe.com/technologies/flex/mobile/.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
Create a project
1. Open Flash Professional CS5 2. Create a new AIR for Android project. The Flash Professional home screen includes a link to create an AIR for Android application. You can also select File > New > AIR, and then select the AIR for Android template. 3. Save the document as HelloWorld.fla
Since this tutorial isnt really about writing code, just use the Text tool to write, Hello, World! on the stage:
1. Select File > AIR for Android Settings. 2. In the General tab, make the following settings:
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
May 19, 2010 Output File: Hello.apk App name: Hello App ID: Hello Version 1.0.0 Aspect ratio: Portrait
3. On the Deployment tab, make the following settings: Certificate: Point to a valid AIR code-signing certificate. You can click the Create button to create a new certificate. (Android apps deployed via the Android Marketplace must have certificates that are valid for 25 years.) Enter the certificate password in the Password field. Android deployment type: Release After Publish: Select both options Enter the path to the ADB tool in the tools subdirectory of the Android SDK.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
If you have not already done so, install Adobe AIR on the device. Make sure that you install the correct runtime for your device OS or emulator. 1. Make sure that USB debugging is enabled on your device. You can turn USB debugging on in the Settings app under Applications > Development. 2. Connect your device to your computer with a USB cable. 3. Open a command or terminal window. 4. Test the device connection by running the ADB devices command: If your device is not listed, make sure that USB debugging is enabled on your device. You can turn USB debugging on in the Settings app under Applications > Development. 5. Install the AIR runtime, if you have not already done so, using the ADB install command:
adb install pathToRuntime/Runtime.apk adb devices
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
May 19, 2010 When running ADB from the command line, it is often convenient to add the SDK tools folder to your path environment variable. For help on setting the path, see Setting the path environment variable. 6. Make sure that USB debugging is enabled on your device. You can turn USB debugging on in the devices Settings app under Applications > Development. 7. Connect the device to your computer with a USB cable. 8. Select File > Publish. Flash Professional CS5 creates the APK file and installs the app on the connected Android device. Before you can reinstall an app, you must remove the current version. Do this most easily from the Android Settings app, using the Applications>Manage Applications section.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
10
May 19, 2010 Hello WorldUsing Flash Builder Flash Builder doesnt fully support the building and packaging of AIR for Android apps at this time. You can program and compile an ActionScript application (Flex is not recommended), but packaging the .apk file and installing it on a device must be done using command-line tools outside of Flash Builder.
Create a project
1. From the Flash Builder file menu, select New > Flex Project The New Flex Project opens:
2. Enter a name for the project and choose the Desktop application type. 3. Use the Flex SDK containing the AIR 2.5 SDK for the project Flex SDK version. (Click Configure Flex SDK to add it to the list of available SDKs, if necessary.) 4. Click Next twice.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
11
5. Assign HelloWorld.as as the name of the main application file. Do not use .mxml as the extension. Write the code 6. Click Finish to create the project.
For this simple exercise, just create a TextField object, assign it some text, and add it to the stage. The finished HelloWorld.as file should look like the following:
package { import flash.display.Sprite; import flash.text.TextField;
public class HelloWorld extends Sprite { public function HelloWorld() { var textField:TextField = new TextField(); textField.text = "Hello, World!"; stage.addChild( textField ); } }
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
12
Although you can use the application descriptor file provided by Flash Builder as is, a few changes can make development easier. So, set visible to true, and supportedProfiles to mobileDevice. The finished application descriptor, with all the optional elements and comments removed, should look like the following: <?xml version="1.0" encoding="utf-8" standalone="no"?> <application xmlns="http://ns.adobe.com/air/application/2.5"> <id>test.example.HelloWorld</id> <filename>HelloWorld</filename> <name>HelloWorld</name> <version>v1</version> <supportedProfiles>mobileDevice</supportedProfiles> <initialWindow> <content> <!--This value will be overwritten by Flash Builder in the output app.xml--> </content> <visible>true</visible> </initialWindow> </application>
<application xmlns="http://ns.adobe.com/air/application/2.5">
Flash Builder automatically creates an application descriptor file for you. The <application> element of the descriptor should indicate that you are using AIR 2.5:
(If a different namespace is listed, you may not be using the correct AIR SDK.)
Compile Package
This is a simple example. There are other settings that you can use in the application descriptor file. For example, you can add <fullScreen>true</fullScreen> to the initialWindow element to build a full-screen application. Flash Builder automatically builds the project and places the result in the bin-debug folder. You should now have two files in this folder, HelloWord.swf and HelloWorld-app.xml.
At this step, the process of creating an AIR for Android becomes different from your normal AIR-onthe-desktop workflow. To package an AIR for Android application, you must run the ADT tool from the command line. You will need a code signing certificate to complete this step. A self-signed certificate created with ADT is sufficient. When running ADT from the command line, it is often convenient to add the SDK bin folder to your path environment variable. For help on setting the path, see Setting the path environment variable. The following example demonstrates running ADT from the Windows command line. The procedure on Mac and Linux is essentially the same. 1. Open a command or terminal window. 2. Change the current directory to the bin-debug folder in your HelloWorld Android project folder. For example: 3. Run the ADT package command, setting the -target flag to apk:
cd C:\ AndroidProjects\HelloWorld - Android\bin-debug adt -package -target apk -storetype pkcs12 -keystore ../codesigningCert.p12 HelloWorld.apk HelloWorld-app.xml HelloWorld.swf
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
13
May 19, 2010 Install on the device or emulator Use the Android Debug Bridge (ADB) tool to install the Android package on your device. 1. Connect your device to your computer with a USB cable. 2. Open a command or terminal window. 3. Test the device connection by running the ADB devices command: If your device is not listed, make sure that USB debugging is enabled on your device. You can turn USB debugging on in the Settings app under Applications > Development. 4. Install the Adobe AIR, if you have not already done so, using the ADB install command. Make sure that you install the correct runtime for your device or emulator. 5. Install the application with the ADB install command: Note, if you have both an emulator running and a device attached, add either the -d or -e flag before the install command to specify which target to install to. For example, to install to the device, use:
adb -d install pathToApp/HelloWorld.apk adb install pathToRuntime/Runtime.apk adb install pathToApp/HelloWorld.apk adb devices
Before you can reinstall an app, you must remove the current version. Do this most easily from the Android Settings app, using the Applications>Manage Applications section. Launch Prerelease note: Currently, the -r flag does not reliably uninstall an AIR application APK package.
To launch the HelloWorld application in the same way you launch any other installed app.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
14
May 19, 2010 Hello WorldUsing the Flex and AIR SDK command-line toolss To create an AIR for Android application without using Flash Builder or Flash Professional, you can use the command-line tools provided in the Flex and AIR SDKs. You should overlay a working copy of the Flex SDK with the latest prerelease AIR SDK. This example uses amxmlc from the Flex SDK and ADT from the AIR SDK.
Setup
Before getting started, you must download the AIR 2.5 SDK from the Adobe prerelease website. Make a copy of the Flex SDK you want to use and overlay the new AIR SDK over it. Instructions are included in the release notes. You can obtain a new copy of the Flex SDK from http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4, if needed. You will also need to download the Android SDK tools. See the Developing AIR applications for Android document, available on the Adobe prerelease website for more information about getting and using the Android tools. You must have Java version 1.6 or later installed on your development computer. You can obtain the latest version of Java from http://www.java.com/en/download. Mac OS ships with a version of Java installed. When running the development tools from the command line, it is often convenient to add the SDK folders containing the tools to your path environment variable. For help on setting the path, see Setting the path environment variable.
Create a folder in a convenient location. Create two files within this folder: HelloWorld.as HelloWorld-app.xml
public class HelloWorld extends Sprite { public function HelloWorld() { var textField:TextField = new TextField(); textField.text = "Hello, World!"; stage.addChild( textField ); } }
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
<?xml version="1.0" encoding="utf-8" standalone="no"?> <application xmlns="http://ns.adobe.com/air/application/2.5"> <id>test.example.HelloWorld</id> <filename>HelloWorld</filename> <name>HelloWorld</name> <version>v1</version> <supportedProfiles>mobileDevice</supportedProfiles> <initialWindow>
Open the HelloWorld-app.xml file in a text editor and copy the following XML code into it:
15
Compile
This is a simple example. There are other settings that you can use in the application descriptor file. For example, you can add <fullScreen>true</fullScreen> to the initialWindow element to build a full-screen application. Use amxmlc from the Flex SDK to compile the app into a SWF file.
When running the Flex and AIR tools from the command line, it is often convenient to add the SDK bin path to your path environment variable (see Setting the path environment variable for help). The rest of this example demonstrates running the tools from the Windows command line. The procedure on Mac and Linux is essentially the same. 1. Open a command or terminal window. 2. Change the current directory to the folder in which you created the HelloWorld.as file. For example: 3. Run amxmlc to compile the application:
cd C:\AndroidProjects\HelloWorld - Android amxmlc HelloWorld.as
Package
adl HelloWorld-app.xml
The SWF file is created. You can run the application on the desktop using ADL, if desired:
To package an AIR for Android application, use the AIR ADT tool. You will need a code signing certificate to complete this step. A self-signed certificate created with ADT is sufficient. (Instructions for creating a code signing certificate are included in Building Adobe AIR applications.) 1. Open a command or terminal window. 2. Change the current directory to the folder in which you created the HelloWorld.as file. 3. Run the ADT package command, setting the target flag to apk:
adt -package -target apk -storetype pkcs12 -keystore ../codesigningCert.p12 HelloWorld.apk HelloWorld-app.xml HelloWorld.swf
Use the Android Debug Bridge (ADB) tool to install the Android package on your device.
The ADB tool is part of the Android SDK, which you can download from: http://developer.android.com/sdk/index.html. Once you have the Android SDK installed, you can continue. 1. Connect your device to your computer with a USB cable. 2. Open a command or terminal window. 3. Test the device connection by running the ADB devices command: If your device is not listed, make sure that USB debugging is enabled on your device. You can turn USB debugging on in the Settings app under Applications > Development. 4. Install the AIR runtime, if you have not already done so, using the ADB install command. Make sure you install the correct runtime for your device or emulator.
adb devices
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
16
5. Install the application with the ADB install command: Note, if you have both an emulator running and a device attached, add either the -d or -e flag before the install command to specify which target to install to. For example, to install to the device, use:
adb -d install pathToApp/HelloWorld.apk
Before you can reinstall an app, you must remove the current version. Do this most easily from the Android Settings app, using the Applications>Manage Applications section.
Prerelease note: Currently, the -r flag does not reliably uninstall an AIR application APK package.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
17
Setting the PATH on Linux and Mac OS using the Bash shell
echo $PATH
When you type a command in a terminal window, the shell, a program that reads what you typed and tries to respond appropriately, must first locate the command program on your file system. The shell looks for commands in a list of directories stored in an environment variable named $PATH. To see what is currently listed in the path, type:
/usr/bin:/bin:/usr/sbin:/usr/local/bin:/usr/x11/bin
This returns a colon-separated list of directories that should look something like this: The goal is to add a couple of directories to the list so that the shell can find the ADT tool from the AIR SDK and the ADB tool from the Android SDK. Assuming that you have put the AIR SDK at /Users/fred/SDKs/AIR and the Android SDK at /Users/fred/SDKs/android, then the following command will add the necessary directories to the path: Note: If your path contains blank space characters, escape them with a backslash, as in the following:
/Users/fred\ jones/SDKs/AIR\ 2.5\ SDK/bin echo $PATH adt -version adb devices export PATH=$PATH:/Users/fred/SDKs/AIR/bin:/Users/fred/SDKs/android/tools
You can use the echo command again to make sure it worked:
/usr/bin:/bin:/usr/sbin:/usr/local/bin:/usr/x11/bin:/Users/fred/SDKs/AIR/bin:/Users/fred/SDKs/android/tools
So far so good. You should now be able to type the following commands and get an encouraging response:
If your modified your $PATH variable correctly, the first command should report the version of ADT. The second command should list the Android emulators and devices attached on your machine. There is still one problem, however; the next time you fire up a new terminal window, you will notice that the new entries in the path are no longer there. The command to set the path must be run every time you start a new terminal. A common solution to this problem is to add the command to one of the start-up scripts used by your shell. On Mac OS, you can create the file, .bash_profile, in the ~/username directory and it will be run every time you open a new terminal window. On Ubuntu, the start-up script run when you launch a new terminal window is .bashrc. Other Linux distributions and shell programs have similar conventions. To add the command to the shell start-up script: 1. Change to your home directory:
cd
2. Create the shell configuration profile (if necessary) and redirect the text you type to the end of the file. Use the appropriate file for your operating system and shell. You can use .bash_profile on Mac OS and .bashrc on Ubuntu, for example. 3. Type the text to add to the file:
cat >> .bash_profile export PATH=$PATH:/Users/cward/SDKs/android/tools:/Users/cward/SDKs/AIR/bin
End the text redirection by pressing CTRL-SHIFT-D on the keyboard. 4. Display the file to make sure everything is okay:
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
18
5. Open a new terminal window to check the path: Your path additions should be listed. Setting the PATH on Windows
set path
If you later create a new version of one of the SDKs into different directory, be sure to update the path command in the configuration file. Otherwise, the shell will continue to use the old version.
When you open a command window on Windows, that window inherits the global environment variables defined in the system properties. One of the important variables is the path, which is the list of directories that the command program searches when you type the name of a program to run. To see what is currently included in the path when you are using a command window, you can type:
Path=C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem
This will show a list of semicolon-separated list of directories that looks something like: The goal is to add a couple of directories to the list so that the command program can find the ADT tool from the AIR SDK and the ADB tool from the Android SDK. Assuming that you have put the AIR SDK at C:\SDKs\AIR and the Android SDK at C:\SDKs\android, you can add the proper path entries with the following procedure: 1. Open the System Properties dialog by right-clicking on the My Computer icon and choosing Properties from the menu. 2. Under the Advanced tab, click the Environment Variables button. 3. Select the Path entry in the System variables section of the Environment Variables dialog 4. Click Edit. 5. Scroll to the end of the text in the Variable value field. 6. Enter the following text at the very end of the current value: 7. Click OK in all the dialogs to save the path.
adt -version adb devices ;C:\SDKs\AIR\bin;C:\SDKs\Android\tools
If you have any command windows open, realize that their environments are not updated. Open a new command window and type the following commands to make sure the paths are set up correctly:
If you later change the location of the SDKs, or add a new version, remember to update the path variable.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
19
If you do not supply an icon of a given size, the next largest size is used and scaled to fit. If you do not supply any icons, a default system icon is used. In Flash Professional CS5, you can specify these icons in the AIR for Android Settings dialog box. Select File > AIR for Android Settings. (For AIR for Android support in Flash Professional CS5, install the AIR for Android prerelease extension for Flash Professional CS5, included at the prerelease site.)
The application descriptor file is an XML file containing properties for the entire application, such as its name, version, copyright, and other settings. The application descriptor file is XML file with the following format:
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
21
May 19, 2010 Note the AIR 2.5 namespace declaration. This is required for AIR apps on Android. You can also set application properties in Flash Professional CS5. Setting application properties in the application descriptor file The application descriptor file includes the following elements. The <id> element uniquely identifies your application. The recommended form is a dot-delimited, reverse-DNS-style string, such as "com.company.AppName". Do not include hyphen character in the id. Note that the Android package ID is the value of the id element in the application descriptor file with "app." prepended to the front. The <filename> element defines the name used for the APK installer file. The <name> element is the application name displayed on the device. Make sure that this name is not too long to be displayed. The <version> element helps users to determine which version of your application they are installing. The <initialWindow> element contains the following child elements to specify the properties for of the initial appearance of the application: The <content> element identifies the root SWF file to compile into the iPhone application. <visible>true</visible> This is a required setting. The<fullScreen> element specifies whethter the application uses the entire screen of the Android device (true) or not (false). The <aspectRatio> element specifies that the initial aspect ratio of the application is in portrait mode (rather than landscape). You can specify <aspectRatio>portrait</aspectRatio> or <aspectRatio>landscape</aspectRatio>. The <autoOrients> element specifies whether the orientation of content in the application automatically reorients as the device itself changes physical orientation. The default value is true. You can cancel automatic orientation by calling the preventDefault() method of an orientationChanging event dispatched by the Stage object.
stage.align = StageAlign.TOP_LEFT; stage.scaleMode = StageScaleMode.NO_SCALE;
When using auto-orientation, for best results set the align property of the Stage to the following:
Specifying <profiles>mobileDevice</profiles> Limits the application to be compiled into the mobile device profile. This profile currently only supports iPhone applications. There are three supported profiles: desktopA desktop AIR application. extendedDesktopA desktop AIR application with support for the native process API. mobileDeviceAn AIR application for a mobile device.
Setting application properties in Flash Professional CS5 Flash Professional CS5 generates an application descriptor file based on the settings in the Application & Installer Settings dialog box. However, you can also edit the application descriptor file
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
The <icon> element contains the following child elements to specify the icons used by the application:
22
May 19, 2010 in a text editor. Flash Professional names the application descriptor file by adding -app.xml to your project name. For example, the application descriptor file for a HelloWorld project is named HelloWorld-app.xml. To set application properties in Flash Professional CS5, select File > AIR Android Settings. The Application & Installer Settings dialog box (for AIR Android apps), includes three tabs: General, Deployment, and Icons. In the General tab, make the following settings: Output File: the name of the APK file App name: The name of the app, which is displayed on the Android device App ID: A unique name for the app, such as com.example.myApp Version The version of the app, such as 1.0.0 Aspect ratio: The initial aspect ratio of the application On the Deployment tab, make the following settings: Certificate: Point to a valid AIR code-signing certificate. You can click the Create button to create a new certificate. (Android apps deployed via the Android Marketplace must have certificates that are valid for 25 years.) Enter the certificate password in the Password field. Android deployment type: Release or debug After Publish: Options to install and launch the application on a connected device Enter the path to the ADB tool in the tools subdirectory of the Android SDK. On the Icons tab, add the paths to the icon PNG files (defined in the previous section).
SIGNING_OPTIONS are the same as the normal AIR code signing parameters.
output-package is the name for the APK file. You can add the .apk extension to this name. If you specify no extension, the packager adds the .apk extension. FILE_OPTIONS are the normal parameters for identifying the application descriptor file, output file, and the files to package. You must run this command from the directory containing the application files.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
23
May 19, 2010 The following example assumes that: 1. The path to the ADT tool is on your path definition. (See Setting the path environment variable for help.) 2. You are running the command from the directory containing the application source files. The source files are myApp-app.xml (the application descriptor file), myApp.swf, and an icons directory. 3. You have a code-signing certificate named codesign.p12 in the parent directory. This certificate must be valid through 2033 in order for the app to be distributed through the Android Marketplace. (See Distributing an AIR for Android application on page 28.) Running this example, ADT will ask you for the password. You can also specify the password right after the certificate name (codesign.p12 in this example).
adt -target apk -storetype pkcs12 -keystore ../codesign.p12 myApp.apk myApp.air adt -package -target apk -storetype pkcs12 -keystore ../codesign.p12 myApp.apk myApp-app.xml myApp.swf icons
You can also create an APK package from an AIR or AIRI file:
The AIR file must use the AIR 2.5 namespace in the application descriptor file. The file should also include icons sized correctly for Android. (See Android icon art on page 21.) To create a version of the app that you can use with a debugger, use apk-debug as the target and specify connection options. For more information, see Debugging an application on the device on page 27. Note: Developer Serge Jespers has created Package Assistant Pro, an AIR application that assists you in packaging AIR apps for Android. You can download the application at http://www.webkitchen.be/package-assistant-pro/.
You can use the ADB application, included in the Android SDK, to install an Android package: 1. Connect your Android device to your computer using a USB cable. On Windows, you might need to install the Android USB driver, which is available in the Android SDK. You can also launch the Android Emulator instead of connecting an Android device. 2. In the device Settings app, go to Applications > Development and enable USB debugging. 3. To test whether the ADB tool can connect to your device, run: You should see your device and any running emulators listed in the command output. (If your USB-connected device or running emulator isnt listed, run the ADB kill-server command and try again.)
adb devices
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
24
May 19, 2010 4. You must uninstall any existing version of the application before installing a new version. You can uninstall applications from the device Settings app under Applications > Manage applications. You can also use the adb uninstall command to uninstall applications. Use the -d flag to target a device; use -e to target an emulator:
adb -d install app.com.example.myApp adb -e install app.com.example.myApp adb -shell pm list packages
Note that the Android package name is the application descriptor file id element value with app. added as a prefix. You can use the adb -shell pm command to list all packages installed on a device: 5. To install the AIR runtime, run the install command. Use the -d flag to target a device; use -e to target an emulator:
adb -d install Runtime_Device_yyyymmdd.apk adb -d install myApp.apk adb -e install Runtime_Emulator_yyyymmdd.apk
Prerelease note: Using the -r flag with adb install (indicating a reinstall) does not currently work reliably with the AIR runtime or AIR application APK files. We suggest you always perform an adb uninstall prior to calling adb install to ensure that your application is properly installed on your Android device or the Android Emulator. You can also uninstall using the Settings app on the device. See http://developer.android.com/guide/developing/tools/adb.html for ADB documentation on the Android Developers website. Installing via a URL
To enable installation of Android packages directly from the web browser, open the Settings app on the device or emulator. In Applications > Development, select the Unknown Sources option. To install an Android package from a URL: 1. Place the APK package on a web server that is accessible to your device. 2. On the device, open the web browser. 3. Enter the URL for the package in the web browser. The device downloads the apk file and displays it on the browsers Download history page. Tap the APK entry to install it.
For example, consider an application in which the application descriptor file includes the following id element: You can launch this application (after it had been installed) using the following command:
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
25
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
26
The debug session displays any trace() output from the app, and you can use other debugging features.
In Flash Professional CS5, you can publish a debug version of the APK file:
Include one of the following -connect options (CONNECT_OPTIONS) to specify the IP address of the development computer running the debugger:
adt -package -target apk-debug -connect ... -connect IP_ADDRESSThe -connectThe
For a description of the SIGNING_OPTIONS, <output-package>, FILE_OPTIONS, and <input-package>, see Setting Application Properties.
Using the adt tool, you can package the app as a debug version using the -target apk-debug option:
application will attempt to connect to a debug session on the development computer used to compile the application. For example: application will attempt to connect to a debug session on the computer with the specified IP address. For example:
The -connect option is optional. If not included, the resulting debug application will not attempt to connect to a hosted debugger. To run a debug session: 1. Install the debug version of the app on the device or the Android emulator. 2. On the device, turn Wi-Fi on and connect to the same network as that of the development computer. 3. Start a debug session using Flash Professional CS5 or the fdb application included in the Flex SDK.
-connect HOST_NAMEThe application will attempt to connect to a debug session on the computer with the specified host name. For example:
In Flash Professional CS5, choose Debug > Begin Remote Debug Session > ActionScript 3.0. From the command line, run the fdb application included in the bin directory of the Flex SDK. 4. Run the app on the device. (See Running an Android application on a device on page 25.) When debugging an application installed on Android, Flash Professional CS5 and fdb support all debugging features, including trace() output, breakpoint control, stepping through code, and variable monitoring.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
27
You can create a self-signed certificate with the Adobe ADT tool. Use the new -validityPeriod option to extend the certificate expiration date. For example, the following command creates a certificate that is valid for 25 years:
By default, certificates created with ADT are valid for five years. Be sure to use the -validityPeriod option when creating a certificate for use with an AIR for Android application.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
28
In AIR for Android, you can use the Loader class to load a SWF file and execute its code. However, ActionScript 2.0 is not currently supported. AIR applications for the iPhone cannot execute code in loaded SWF content; AIR for Android does not include this restriction.
ActionScript API Notes File System The following APIs behave differently on Android devices than is currently documented in the ActionScript 3.0 Reference for the Adobe Flash Platform. The differences are:
File.applicationDirectory points to /data/data/app.appId/app/assets File.applicationStorageDirectory points to /data/data/app.appID/appID/Local Store File.desktopDirectory points to /sdcard File.documentsDirectory points to /sdcard File.createTempDirectory() created in /data/data/app.appId/cache File.createTempFile() created in /data/data/app.appId/cache app:/ points to /data/data/app.appId/app/assets app-storage:/ points to /data/data/app.appId/appId/Local Store FileReference.browse() can only select images, video and audio files. FileReference.browse() the title cannot be changed. FileReference opens up /sdcard for its operations. File.moveToTrash() and File.deleteFile() both delete files immediately, since there is no recycle bin. Similarly, File.moveToTrashAsync() and File.deleteFileAsync() behave in the same way.
Screen Orientation
29
Hardware Keyboard
Keyboard events are dispatched for the Back and Menu soft keys. The Back soft key is assigned keycode 94 and Menu soft key is assigned keycode 95. (The Search soft key is not currently supported.)
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
30
Don't overdraw. Use the background color as a background. Don't layer large shapes on top of each other. There is a cost for every pixel that must be drawn. Avoid shapes with long thin spikes, self -intersecting edges, or lots of fine detail along the edges. These shapes take longer to render than display objects with smooth edges. Make bitmaps in sizes that are close to, but less than, 2n by 2m bits. The dimensions do not have to be power of 2, but they should be close to a power of 2, without being larger. For example, a 31-by15pixel image renders faster than a 33-by-17pixel image. (31 and 15 are just less than powers of 2: 32 and 16.) Limit the size of display objects and try to narrow down to an optimal size which is visible enough.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
31
Information density
The physical size of the screen of mobile devices is smaller than on the desktop, although their pixel density is higher. Sharper text is nice to look at, but the glyphs have to have a minimal physical size to be legible. Mobile devices are often used on the move and under poor lighting conditions. Consider how much information you can realistically display onscreen legibly. It might be less than you would on a screen of the same pixel dimensions on a desktop. Use typographic hierarchy to highlight important information. Use font size, weight, placement, and spacing to express the relative importance of the elements of the user interface. You can use one or more cues at each level of the hierarchy. Apply these cues consistently across your application. A cue can be spatial (indent, line spacing, placement) or graphic (size, style, color of typeface). Applying redundant cues can be an effective way to make sure that the hierarchy is expressed clearly. However, try using no more than three cues for each level of grouping. Try to simplify the labels and explanatory text required. For example, use sample input in text field to suggest the content and avoid a separate label.
Use fonts that are 14 pixels or larger. Use device fonts for editable text fields. Device fonts in text fields also render more quickly than embedded fonts.
32
May 19, 2010 A single-line text field includes a clear button (to the right of the text) when the user edits the text. However, this clear button is not displayed if the text field is too narrow. After editing text in a single-line text field, the user dismisses the virtual keyboard by tapping the key on the keyboard. After editing text in a multi-line text field, the user dismisses the virtual keyboard by tapping outside of the text field. This removes focus from the text field. Make sure that your design includes area outside of the text field when the virtual keyboard is displayed. If the text field is too large, no other area may be visible. Using some Flash Professional CS5 components can prevent you from removing focus from a text field. These components are designed for use on desktop machines, where this focus behavior is desirable. One such component is the TextArea component. When it is in focus (and being edited), you cannot remove focus by clicking another display object. Placing some other Flash Professional CS5 components onstage can also prevent the focus from changing from the text field being edited. Do not rely on keyboard events. For example, some SWF content designed for the web uses the keyboard to let the user control the application. However, on Android, the virtual keyboard is only present when the user edits a text field.
Hit targets
Consider the size of hit targets when designing buttons and other user interface elements that the user taps. Make these elements large enough that they can be comfortably activated with a finger on a touch screen. Also, make sure that you have enough space between targets. Hit targets should be about 44 pixels to 57 pixels. For more information, see Hit targets on touch screens in the Optimizing Mobile Applications guide at http://help.adobe.com/en_US/as3/mobile/index.html.
Memory allocation
Allocating fresh blocks of memory is costly. It can slow down your application or cause performance to lag during animation or interaction as the garbage collection gets triggered. Try to recycle objects whenever you can, rather than getting rid of one and creating a new one. Keep in mind that vector objects can consume less memory than arrays. See Vector class versus Array class. For more information on memory usage, see Conserving memory in the Optimizing Mobile Applications at http://help.adobe.com/en_US/as3/mobile/index.html.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
33
Drawing API
Try to avoid using the ActionScript drawing API (the Graphics class) to create graphics. Using the drawing API creates objects dynamically on the stage, then renders them to the rasterizer. If possible, create those objects statically in authoring time on the stage instead. Objects created using drawing APIs, when repeatedly called, are destroyed and recreated every time actionscript is executed. However, static objects reside in memory through different timelines.
Event bubbling
For a deeply-nested display object container, bubbling of events can be expensive. Reduce this expense by handling the event completely in the target object, then calling the stopPropagation() method of the event object. Calling this method prevents the event from bubbling up. Calling this method also means that parent objects do not receive the event. Related gains can be realized by flattening the display object nesting, to avoid long event chains. Register for MouseEvent events instead of TouchEvent events when possible. MouseEvent events use less processor overhead than TouchEvent events. Set the mouseEnabled and mouseChildren properties to false, when possible.
To optimize mobile video playback, ensure that there is little else going on in your application while videois playing. This allows the video decoding and rendering processes to use as much CPU as possible. Have little or no ActionScript code running while the video plays. Try to avoid running code that runs on a frequent interval timer or on the timeline. Minimize the redrawing of non-video display objects. Especially avoid redrawing display objects that intersect with the video area. This is true even if they are hidden underneath the video. They will still be redrawn and use up processing resources. For example, use simple shapes for the position indicator and update the position indicator just a couple of times a second rather than on every frame. Dont have the video controls overlapping the video area; put them directly below. If you have a video buffering animation, dont hide it behind the video when it is not in use; set it to invisible. The deactivate/activate event here can be put to use judiciously over here. Whenever you receive a deactivate event you can pause the audio/video playback. Similarly, if you app uses some heavy graphics(I refere to a high frame rate here), its always better to reduce it as much as possible. You may resume or restore back the application state once you receive an activate event. The above not only reduce your memory resource consumption but also ensure lesser battery use for the end user.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
34
May 19, 2010 Check background bitmaps to see that they are the right size (not larger than needed). Check to see if any extra fonts are being embedded. Look at PNG assets for alpha channels and remove them if they are not needed. Use a utility like PNG crunch to reduce the size of PNG assets. Convert PNG assets to JPG assets, if possible. Consider compressing sound files (by using a lower bit rate) Remove any assets that are not used.
Note: This document doesnt cover hardware acceleration related optimizations. It shall be updated as soon as we share a build which is GPU-acceleration capable.
You can use the ADB logcat command to view the device system event log. This log can reveal system errors that affect your application.
On Android, the convention is that there is no exit button for an application. When a user switches out of your application, it goes to the background, but continues running. If the operating system runs low on resources, it will then shut down apps. You can detect when your app goes to the background and returns, by listening to deactivate and activate events dispatched by the NativeApplication object. You can shut down your app by calling the NativeApplication.exit() method. The elements of the application descriptor file that specify window properties are ignored. These elements include: systemChrome, visible, transparent, resizable, maximizable, minimizable, minSize, and maxSize.
Every Android application has a package name. The ADT tool creates this name by appending app. to the AIR application ID defined in the application descriptor file. Do not add app. to the beginning of the applicationID element in the application descriptor file.
adb shell pm list packages
You can use the following ADB command to list packages installed on a device:
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.
35