Debugging a mobile AIR application

You can debug your mobile AIR app in several ways. The simplest way to uncover application logic issues is to debug on your development computer using ADL. You can also install your application on a device and debug remotely with the Flash debugger running on a desktop computer.

Device simulation using ADL

The fastest, easiest way to test and debug most mobile application features is to run your application on your development computer using the Adobe Debug Launcher (ADL) utility. ADL uses the supportedProfiles element in the application descriptor which profile to use. If more than one profile is listed, ADL uses the first one in the list. You can also use the -profile parameter of ADL to select one of the other profiles in the supportedProfiles list. (If you do not include a supportedProfiles element in the application descriptor, then any profile can be specified for the -profile argument.) For example, use the following command to launch an application to simulate the mobile device profile:

adl -profile mobileDevice myApp-app.xml

When simulating the mobile profile on the desktop like this, the application runs in an environment that more closely matches a target mobile device. ActionScript APIs that are not part of the mobile profile are not available. ADL also allows the input of device soft keys and rotation through menu commands.

ADL support simulations of device orientation changes and soft key input through menu commands. When you run ADL in the mobile device profile, the ADL displays a menu (in either the application window or the desktop menu bar) that allows you to enter device rotation or soft key input.

Soft key input

ADL simulates the soft key buttons for Back, Menu, and Search buttons on a mobile device. You can send these keys to the simulated device using the menu displayed when ADL is launched using the mobile profile.

Device rotation

ADL lets you simulate device rotation through the menu displayed when ADL is launched using the mobile profile. You can rotate the simulated device to the right or the left.

The rotation simulation only affects an application that enables auto-orientation. You can enable this feature by setting the autoOrients element to true in the application descriptor.

Screen size

You can test your application on different size screens by setting the ADL -screensize parameter. You can pass in the code for one of the predefined screen types. You can specify the following screen types:

Screen type

Normal width x height

Fullscreen width x height

QVGA

240 x 320

240 x 320

WQVGA

240 x 400

240 x 400

FWQVGA

240 x 432

240 x 432

iPhone

320 x 460

320 x 480

iPod

320 x 460

320 x 480

HVGA

320 x 480

320 x 480

NexusOne

480 x 762

480 x 800

WVGA

480 x 800

480 x 800

Droid

480 x 816

480 x 854

FWVGA

480 x 854

480 x 854

iPad

768 x 1024

768 x 1024

You can also specify a string containing the four values representing the widths and heights of the normal and maximized screens. For example, the following command would open ADL to simulate the screen used on the Droid:

adl -screensize 480x816:480x854 myApp-app.xml

Limitations

Some APIs that are not supported on the desktop profile cannot be simulated by ADL. The APIs that are not simulated include:

  • Accelerometer

  • cacheAsBitmapMatrix

  • CameraRoll

  • CameraUI

  • Geolocation

  • Multitouch and gestures on desktop operating systems that do not support these features

  • SystemIdleMode

If your application uses these classes, you should test the features on an actual device or emulator.

Trace statements

When you run your mobile application on the desktop, trace output is printed to either the debugger or the terminal window used to launch ADL. When you run your application on a device or emulator, you can set up a remote debugging session to view trace output. Where supported, you can also view trace output using the software development tools provided by the device or operating system maker.

In all cases, the SWF files in the application must be compiled with debugging enabled in order for the runtime to output any trace statements.

Remote trace statements on Android

When running on an Android device or emulator, you can view trace statement output in the Android system log using the Android Debug Bridge (ADB) utility included in the Android SDK. To view the output of your application, run the following command from a command prompt or terminal window on your development computer:

tools/adb logcat air.MyApp:I *:S

where MyApp is the AIR application ID of your application. The argument *:S suppresses output from all other processes. To view system information about your application in addition to the trace output, you can include the ActivityManager in the logcat filter specification:

tools/adb logcat air.MyApp:I ActivityManager:I *:S

These command examples assume that you are running ADB from the Android SDK folder or that you have added the SDK folder to your path environment variable.

Connecting to the Flash debugger

To debug an application running on a mobile device, you can run the Flash debugger on your development computer and connect to it over the network. To enable remote debugging on Android, you must do the following:

  • Specify the android:permission.INTERNET permission in the application descriptor

  • Compile the application SWFs with debugging enabled

  • Package the APK file with the -target apk-debug and -connect flag

Remote debugging takes place over a network connection (not USB), so the device must be able to access TCP port 7935 of the computer running the Flash debugger by IP address or fully qualified domain name.

Remote debugging with Flash Professional

Note: Debugging directly from Flash Professional requires the AIR for Android extension for Flash Professional available on Adobe Labs.

Once your application is ready to debug and the permissions are set in the application descriptor, do the following:

  1. Open the AIR Android Settings dialog.

  2. Under the Deployment tab:

    • Select “Device debugging” for deployment type

    • Select “Install application on the connected Android device” for After publishing

    • Deselect “Launch application on the connected Android device” for After publishing

    • Set the path to the Android SDK, if necessary.

  3. Click Publish.

    You application is installed and launched on the device.

  4. Close the AIR Android Settings dialog.

  5. Select Debug > Begin Remote Debug Session > ActionScript 3 from the Flash Professional menu.

    Flash Professional displays, “Waiting for Player to connect” in the Output panel.

  6. Launch the application on the device.

  7. Enter the IP address or host name of the computer running the Flash debugger in the Adobe AIR connection dialog, then click OK.

Remote debugging with FDB

To debug an app running on a device with the command-line Flash Debugger (FDB), first run the debugger on your development computer and then start the application on the device. The following procedure uses the AMXMLC, FDB and ADT tools to compile, package, and debug an application on the device. The examples assume that you are using a combined Flex and AIR SDK and that the bin directory is included in your path environment variable. (This assumption is made merely to simplify the command examples.)

  1. Open a terminal or command prompt window and navigate to the directory containing the source code for the application.

  2. Compile the application with amxmlc, enabling debugging:

    amxmlc -debug DebugExample.as
  3. Package the APK using the apk-debug target:

    adt -package -target apk-debug -connect -storetype pkcs12 -keystore ../../AndroidCert.p12 DebugExample.apk DebugExample-app.xml DebugExample.swf

    If you always use the same host name or IP address for debugging, you can put that value after the -connect flag. The app will attempt to connect to that IP address or host name automatically. Otherwise, you must enter the information on the device each time you start debugging.

  4. Install the application:

    adt -installApp -platform android -platformsdk /Users/juser/SDKs/android -package DebugExample.apk
  5. Open a second terminal or command window and run FDB:

    fdb
  6. In the FDB window, type the run command:

    Adobe fdb (Flash Player Debugger) [build 14159] 
    Copyright (c) 2004-2007 Adobe, Inc. All rights reserved. 
    (fdb) run 
    Waiting for Player to connect
  7. Launch the application from the original terminal or command window:

    adt -launchApp -platform android -platformsdk /Users/juser/SDKs/android -appid DebugExample
  8. Once the app launches on the device or emulator, the Adobe AIR connection dialog opens. (If you specified a host name or IP address for debugging when you packaged the app it will attempt to connect automatically using that address.) Enter the appropriate address and tap OK.

    In order to connect, the device must be able to resolve the address or host name and connect to TCP port 7935. A network connection is required. Connecting the device via the USB cable is not sufficient.

  9. When the remote runtime connects to the debugger, you can set breakpoints with the FDB break command and then start execution with the continue command:

    (fdb) run 
    Waiting for Player to connect 
    Player connected; session starting. 
    Set breakpoints and then type 'continue' to resume the session. 
    [SWF] Users:juser:Documents:FlashProjects:DebugExample:DebugExample.swf - 32,235 bytes after decompression 
    (fdb) break clickHandler 
    Breakpoint 1 at 0x5993: file DebugExample.as, line 14 
    (fdb) continue