May 19, 2010

Developing Adobe AIR Applications for Android

Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.

May 19, 2010

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.

May 19, 2010

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.

May 19, 2010

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.

May 19, 2010

1.

CHAPTER ONE Getting Started

This chapter includes information on setting up your development environment. It also includes a Hello World example.

Workflow for developing and testing an AIR for Android app

1. Write the ActionScript code. 2. Create a standard AIR application descriptor file (using the 2.5 namespace). 3. Compile the application. 4. Package the application as an Android package (.apk) with ADT. 5. Install the AIR runtime on the device (if not already installed) with the Android ADB tool. 6. Install the application on device (or Android emulator) with the Android ADB tool. 7. Launch the application on the device.

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.

Flash Platform tool support

You can use your favorite Flash development tool to create an AIR for Android application. However, only Flash Professional CS5 and the AIR 2.5 SDK command-line tools provide direct support for packaging and on-device debugging. There is no Android support in Flash Builder yet. The AIR for Android prerelease site includes the AIR for Android prerelease extension for Flash Professional CS5. Use this extension to update Flash Professional CS5 for use in building AIR for Android applications. To install the AIR for Android prerelease extension for Flash Professional CS5: 1. Download the AIR for Android prerelease extension from the AIR for Android web site. This file is named AIRforAndroid_FlashCS5_mmddyy.zxp. 2. If Flash Professional CS5 is running, close it. 3. On Windows 7 or Windows Vista, run the Adobe Extension Manager as the Administrator. On the Windows Start menu, right-click Programs > Adobe Extension Manager CS5, and select Run as Administrator. 4. Double-click the .zxp file you downloaded from the prerelease site.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.

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/.

Installing the Android SDK

The Android SDK provides many useful tools for developing Android applications. Obtain the Android SDK from: http://developer.android.com/sdk/index.html Follow the instructions for Adding SDK Components at http://developer.android.com/sdk/addingcomponents.html to add the Android tools and USB drivers (if needed). You can use the Android SDK tools to install the AIR runtime and AIR applications on an Android device. In addition, the Android SDK includes the Android Emulator, which allows simulation of many types of Android devices on your development computer. The Android SDK also includes the Windows USB driver that is required to connect an Android device to a Windows computer. The Android SDK requires the Java version 1.6 or later. You can obtain the latest version of Java from http://www.java.com/en/download. Mac OS includes a pre-installed version of Java.

Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.

May 19, 2010

Creating a Hello World application

This section shows you how to build a basic Hello World application. There are separate instructions for using Flash Professional CS5, Flash Builder, and the AIR SDK. Before you build the application, be sure that you have configured your development environment for AIR for Android development. See the previous sections for details. Hello WorldUsing Flash Professional CS5 Before starting this tutorial, be sure to install the AIR for Android prerelease extension for Flash Professional CS5, available at the prerelease site. For more information, see Flash Platform Tool Support on page 4.

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

Write the code

Since this tutorial isnt really about writing code, just use the Text tool to write, Hello, World! on the stage:

Set the application properties

On the properties pane of the text object, select Classic Text.

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.

May 19, 2010

Package and Install the application on the Android device

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

May 19, 2010

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

May 19, 2010 Edit the application descriptor file

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

The Android package, HelloWorld.apk, is created in the bin-debug directory.

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 project Write the code

Create a folder in a convenient location. Create two files within this folder: HelloWorld.as HelloWorld-app.xml

Open HelloWorld.as in an text editor and add the following code:

package { import flash.display.Sprite; import flash.text.TextField;

Edit the application descriptor file

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

May 19, 2010

<content>HelloWorld.swf</content> <visible>true</visible> </initialWindow> </application>

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

Install on the device

The Android package, HelloWorld.apk, is created in the bin-debug directory.

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

May 19, 2010

adb install pathToRuntime/Runtime.apk adb install pathToApp/HelloWorld.apk

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

May 19, 2010

Setting the path environment variable

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

May 19, 2010

cat .bash_profile echo $PATH

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

May 19, 2010

CHAPTER 2 Building AIR applications for Android

This chapter contains details on using the tools to build AIR applications for Android. For instructions on installing development tools and for Hello World tutorial samples, see Chapter 1.

Android icon art

The application launch icon should be supplied as 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. 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.)

Setting application properties

<?xml version="1.0" encoding="utf-8" standalone="no"?> <application xmlns="http://ns.adobe.com/air/application/2.5"> <id>com.example.HelloWorld</id> <filename>HelloWorld</filename> <name>Hello World</name> <version>1.0.0</version> <supportedProfiles>mobileDevice</supportedProfiles> <initialWindow> <content>HelloWorld.swf</content> <visible>true</visible> <fullScreen>true</fullScreen> <initialOrientation>portrait</initialOrientation> <autoOrients>false</autoOrients> </initialWindow> <icon> <image36x36>assets/icon36.png</image36x36> <image48x48>assets/icon48.png</image48x48> <image72x72>assets/icon72.png</image72x72> </icon> </application>

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.

<icon> <image36x36>assets/icon36.png</image36x36> <image48x48>assets/icon48.png</image48x48> <image72x72>assets/icon72.png</image72x72> </icon>

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).

Packaging an Android application

In Flash Professional CS5, you can package the application by selecting 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.) Use the AIR ADT tool to package an AIR for Android application. The AIR SDK version 2.5 supports packaging for Android. The primary difference between packaging an AIR application for Android versus packaging for the desktop is that you add the -target apk flag to the command line parameters. The command line syntax for packaging is:
adt -package -target ( apk | apk-debug ) ( CONNECT_OPTIONS ) SIGNING_OPTIONS <output-package> ( FILE_OPTIONS | <inputpackage> )

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/.

Installing Adobe AIR and AIR for Android apps

To install Adobe AIR or an AIR application to an Android device or the Android emulator, use the Android Debug Bridge (ADB) tool. The ADB tool is included in the Android SDK. You can also install Android packages from a URL by placing the APK package on an HTTP server and navigating to the URL with the device web browser. 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.

Installing with the Android Debug Bridge (ADB)

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

6. To install an application run:

adb -e install myApp.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.

Running an Android application on a device

You can launch an Android application from the standard launch screen on the device. You can also use the ADB tool to launch an application on a connected device. Use the following command:
adb -d shell am start -a android.intent.action.MAIN -n app.<app-id>/app.<app-id>.AppEntry <id>com.example.test.ball</id>

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

May 19, 2010

adb -d shell am start -a android.intent.action.MAIN -n app.com.example.test.ball/app.com.example.test.ball.AppEntry

Running AIR applications in the Android emulator

To run your AIR application on the Android emulator, you must install the Android SDK, create at least one virtual device, install the emulator version of the AIR runtime, and then install your AIR application. Note that applications on an emulator typically run much slower than they do on an actual device. You must have the Android SDK installed. See Installing the Android SDK on page Error! Bookmark not defined.. Create the Android Virtual Device: 1. Launch the Android SDK and AVD Manager application: On Windows, run the SDK Setup.exe file, at the root of the Android SDK directory. On Mac OS, run the android application, in the tools subdirectory of the Android SDK directory 2. Select the Settings option and select the "Force https:// option. 3. Select the Available Packages option. You should see a list of available Android SDKs. 4. Select the Android 2.1 option and click the Install Selected button. 5. Select the Virtual Devices option and click the New button. 6. Make the following settings: A name for your virtual device A target (the list should include only one target if you just downloaded one before) A size for the SD Card (such as 1024) A skin (such as Default HVGA) 7. Click the Create AVD button. Note that Virtual Device creation may take some time depending on your system configuration. Now you can launch the new Virtual Device. 1. Select Virtual Device. The virtual device you created above should be listed. 2. Select the Virtual Device, and click the Start button. 3. Click the Launch button on the next screen. You should see an emulator window. This too may take a few seconds. It may also take some time for the Android operating system to initialize. You can check that the firmware on the Virtual Device is version 2.1. Open the device Settings app and go to About Phone > Firmware Version. You can use the ADB tool to install Adobe AIR and AIR for Android apps. Be sure to install Adobe AIR before installing any AIR for Android apps. See Installing Adobe AIR and Android apps on page 24. You can now run AIR applications on the Android Virtual Device. See Running AIR applications in the Android emulator on page 26. For more information, see the Android documentation at: http://developer.android.com/guide/developing/tools/othertools.html#android http://developer.android.com/guide/developing/tools/emulator.html

Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.

26

May 19, 2010

Debugging an application on the device

You can create a version of an app that you can install on the device and debug. You can debug using the remote debugging session feature in Flash Professional CS5. You can also use the fdb tool, included in the Flex SDK. Compile the application with debug support. 1. Select File > AIR Android settings. 2. In the Deployment tab, specify Release as the Android Deployment Type. 3. Click the Publish button.
adt -package -target apk-debug CONNECT_OPTIONS SIGNING_OPTIONS <output-package> ( FILE_OPTIONS | <input-package> )

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:

adt -package -target apk-debug -connect 192.0.32.10

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.

adt -package target apk-debug -connect bobroberts-mac.example.com

-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

May 19, 2010

Distributing an AIR for Android application

Because the AIR application is packaged as a standard Android package, you can distribute it like any other Android application, either through the Android marketplace or another website. However, the general public cannot install AIR for Android applications until the AIR runtime is publicly available. The Android marketplace currently requires that submitted apps be signed with a certificate valid until at least 2033. (Such a long-lived certificate is not required for developing an APK; this is only a requirement for packages submitted to the Android marketplace.)

adt -certificate -cn ADigitalID 1024-RSA SigningCert.p12 39#wnetx3tl

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

May 19, 2010

CHAPTER 3 Supported Flash and AIR APIs

AIR for Android conforms to the AIR mobile device profile. Not all APIs that are supported on the desktop are supported on mobile devices. For a list of APIs that are not supported see ActionScript 3.0 API support for mobile devices. Note that this guide discusses iPhone development. However, the referenced section also applies to Android development. The ActionScript 3.0 API support for mobile devices topic discusses the level of ActionScript support planned for the public release of AIR for Android. For current API and development issues, refer to the release notes on the Adobe prerelease website. Note: The DisplayObject.cacheAsBitmapMatrix property is not currently supported in AIR for Android.

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

Stage.Orientation returns only stageOrientation.DEFAULT or stageOrientation.ROTATED_RIGHT for Android

Stage.setOrientation can be set to stageOrientation.DEFAULT or stageOrientation.ROTATED_RIGHT only.

Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.

29

May 19, 2010

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

May 19, 2010

CHAPTER 4 Designing AIR applications for Android

The processing speed and screen size of mobile devices lend to special design and coding considerations. However, many of the design considerations are common to development for all applications or for mobile applications. For more information on optimizing applications, see Optimizing Content for the Flash Platform, at http://help.adobe.com/en_US/as3/mobile/index.html. This document includes many suggestions for optimizing performance of mobile content, Flash Player content, AIR content, and ActionScriptbased content in general. Most of these suggestions also apply to AIR applications for mobile devices. Important: Many of these design considerations and optimization techniques are essential in developing applications that run well on mobile devices.

Improve display object performance

Hardware acceleration is not supported on current pre-release of android but you can speed up graphics performance in some classes of display objects. Here are a few tips on how to maximize graphics performance.
Try to limit the numbers of items visible on stage. Each item takes some time to render and composite with the other items around it. When you no longer need to display a display object, set its visible property to false or remove it from the stage (removeChild()). Do not simply set its alpha property to 0. Restrict upon the use of global objects and create objects restricted within a block of code. Avoid blend modes in general, and the layer blend mode in particular. Use the normal blend mode whenever possible. Display object filters are expensive computationally. Use them sparingly. For example, using a few filters on an introduction screen may be acceptable. However, avoid using filters on many objects or on objects that are being animated or when you must use a high frame rate. Avoid morph shapes. Avoid using clipping. If possible, set the repeat parameter to false when calling the Graphic.beginBitmapFill() method.

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

May 19, 2010

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.

Fonts and text input

The following fonts are device fonts on Android (check the built-in fonts in /system/fonts folder on your target phone): Clockopia.ttf DroidSerif-Bold.ttf DroidSans-Bold.ttf DroidSerif-BoldItalic.ttf DroidSans.ttf DroidSerif-Italic.ttf DroidSansFallback.ttf DroidSerif-Regular.ttf DroidSansMono.ttf

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.

Application design considerations

Consider implementing alternatives to using input text fields. For example, to have the user enter a numerical value, you do not need a text field. You can provide two buttons to increase or decrease the value (something like a custom numeric stepper). Be aware of the space used by the virtual keyboard. When the virtual keyboard is activated (for example when a user taps within a text field), the application adjusts the position of the stage. The automatic repositioning ensures that the selected input text field is visible. A text field at the top of the stage moves to the top of the visible stage area. (The visible stage area is smaller to accommodate the virtual keyboard.) A text field at the bottom of the stage stays at the bottom of the new stage area. A text field in another part of the stage is moved to the vertical center of the stage. You can add an event listener for the focus event of a text field, to reposition the text field.
Adobe Confidential: This information is only provided to the AIR for Android prerelease. Do not redistribute.

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.

Saving application state

Your application may quit at any time (for example when the phone rings or you app goes to background). The application dispatches a deactivate event whenever you application goes to background and an activate event when it comes back to the top again. Consider saving the state of your application anytime you receive a deactivate event. For example, you can save settings to a file or a database in the application storage directory. Or you can save data to a local shared object. You can then restore the state of your application when you receive an activate event (obviously theres no guarantee here that your app wont be killed by the OS when not in focus). If a phone call interrupts an application, it will restart when the call ends. Do not rely on the NativeApplication object dispatching an exiting event when the application quits; it may not as the support for this event hasnt been decided yet and may be missing in the final release too.

Screen orientation changes

Android application content can be viewed in portrait or landscape orientation. Consider how your application will deal with screen orientation changes. For more information, see Setting an Detecting Screen Orientation.

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

May 19, 2010

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.

Optimizing video performance

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.

Reducing application file size

Here are some tips on reducing the file size of your apk file:

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.

Differences between Android and iPhone development

If you are already familiar with the process of creating AIR applications for the iPhone, be aware of the following differences when creating an application for Android: The runtime is compiled into AIR for iPhone applications. However, on Android, all the AIR applications share the same runtime. This fact makes Android applications much, much smaller. However, it also means that you must wait for the runtime to be publically available before you can distribute your application. You do not need a special developer certificate or provisioning profile on Android. You can sign an Android application with a normal AIR development certificate. (However, Android requires that the certificate remain valid through 2033. For more information, see Distributing an AIR for Android application on page 28.) Icons are optional on Android. (However, it is certainly recommended that you use a custom launch icon. The ADT tool provides a default icon if you do not provide one.) A graphic for the initial screen (Default.png) is not used by Android apps. Android devices come in a wider variety of screen sizes and with a wider range of capabilities. For tips on developing for multiple screen sizes, see Authoring mobile Flash content for multiple screen sizes at http://www.adobe.com/devnet/flash/articles/authoring_for_multiple_screen_sizes.html.

Miscellaneous development notes

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