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 or the iOS Simulator. 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 to determine 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. However, ADL does not distinguish between the capabilities of different mobile devices. For example, you can send simulated soft-key presses to your app, even though your actual target device does not utilize soft keys.

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 or a string containing the four values representing the pixel dimensions of the normal and maximized screens.

Always specify the pixel dimensions for portrait layout, meaning specify the width as a value smaller than the value for height. For example, the following command would open ADL to simulate the screen used on the Motorola Droid:

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

For a list of the predefined screen types, see ADL usage.

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.

Similarly, there are APIs that work when running under ADL on the desktop, but which do not work on all types of mobile devices. These include:

  • Speex and AAC audio codec

  • Accessibility and screen reader support

  • RTMPE

  • Loading SWF files containing ActionScript bytecode

  • PixelBender shaders

Be sure to test applications that use these features on the target devices since ADL does not entirely replicate the execution environment.

Device simulation using the iOS Simulator

The iOS Simulator (Mac-only) offers a fast way to run and debug iOS applications. When testing with the iOS simulator, you do not need a developer certificate or a provisioning profile. You must still create a p12 certificate, although it can be self-signed.

By default ADT always launches the iPhone simulator. To change the simulator device, set the environment variable, AIR_IOS_SIMULATOR_DEVICE, as follows:

launchctl setenv AIR_IOS_SIMULATOR_DEVICE "iPad Retina"

Restart the process after setting the environment variable and run the application on the simulator device of your choice.

Note:

When using ADT with the iOS Simulator, you must always include the ‑platformsdk option, specifying the path to the iOS Simulator SDK.

To run an application in the iOS Simulator:

  1. Use the adt -package command with either -target ipa-test-interpreter-simulator or -target ipa-debug-interpreter-simulator, as the following example shows:

    adt     -package 
        -target ipa-test-interpreter-simulator 
        -storetype pkcs12 -keystore Certificates.p12 
        -storepass password 
        myApp.ipa 
        myApp-app.xml 
        myApp.swf 
        -platformsdk /Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator5.0.sdk
    Note:

    Signing options are no longer required in case of simulators now, so any value can be provided in -keystore flag as it will not be honored by ADT.

  2. Use the adt ‑installApp command to install the application in the iOS Simulator, as the following example shows:

    adt     -installApp 
        -platform ios 
        -platformsdk /Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator5.0.sdk 
        -device ios-simulator 
        -package sample_ipa_name.ipa
  3. Use the adt ‑launchApp command to run the application in the iOS Simulator, as the following example shows:

    adt     -launchApp 
        -platform ios 
        -platformsdk /Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator5.0.sdk 
        -device ios-simulator 
        -appid sample_ipa_name

To test a native extension in the iOS Simulator, use the iPhone-x86 platform name in the extension.xml file and specify library.a (static library) in the nativeLibrary element, as the following extension.xml example shows:

<extension xmlns="http://ns.adobe.com/air/extension/3.1"> 
  <id>com.cnative.extensions</id> 
  <versionNumber>1</versionNumber> 
  <platforms> 
    <platform name="iPhone-x86"> 
      <applicationDeployment> 
        <nativeLibrary>library.a</nativeLibrary> 
        <initializer>TestNativeExtensionsInitializer </initializer> 
        <finalizer>TestNativeExtensionsFinalizer </finalizer> 
      </applicationDeployment> 
    </platform> 
  </platforms> 
</extension>
Note:

When testing a native extension in the iOS Simulator, do not use the static library (.a file) that is compiled for the device. Instead, be sure to use the static library that is compiled for the simulator.

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.

Note:

In AIR 2.6+, the ADB utility is included in the AIR SDK and can be found in the lib/android/bin folder.

Remote trace statements on iOS

To view the output of trace statements from an application running on an iOS device, you must establish a remote debugging session using the Flash Debugger (FDB).

Connecting to the Flash debugger

AIR 2.6 (Android) AIR 3.3 (iOS)

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, you must do the following:

  • On Android, specify the android:permission.INTERNET permission in the application descriptor.

  • Compile the application SWFs with debugging enabled.

  • Package the application with the -target apk-debug, for Android, or -target ipa-debug, for iOS, and either the -connect (wifi debugging) or -listen (USB debugging) flag.

For remote debugging over wifi, 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. For remote debugging over USB, the device must be able to access TCP port 7936 or the port specified in the -listen flag.

For iOS, you can also specify -target ipa-debug-interpreter or -target ipa-debug-interpreter-simulator.

Remote debugging with Flash Professional

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.

    Your 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 over a network connection

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 application using either the apk-debug or ipa-debug targets:

    Android 
    adt -package -target apk-debug -connect -storetype pkcs12 -keystore ../../AndroidCert.p12 DebugExample.apk DebugExample-app.xml DebugExample.swf 
     
    iOS 
    adt -package -target ipa-debug -connect -storetype pkcs12 -keystore ../../AppleDeveloperCert.p12 -provisioning-profile test.mobileprovision 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.

    On Android, you can use the ADT -installApp command:

    adt -installApp -platform android -package DebugExample.apk

    On iOS, you can install the application using the ADT -installApp command or using iTunes.

  5. In 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 on the device.

  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 with the -connect option 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 to the debugger in this mode, the device must be able to resolve the address or host name and connect to TCP port 7935. A network connection is required.

  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

Remote debugging with FDB over USB

AIR 2.6 (Android) AIR 3.3 (iOS)

[adoberuntime]AIR 2.6 (Android) AIR 3.3 (iOS)[/adoberuntime]

To debug an app over a USB connection, you package the application using the ‑listen option instead of the -connect option. When you specify the ‑listen option, the runtime listens for a connection from the Flash debugger (FDB) on TCP port 7936 when you launch the application. You then run FDB with the -p option, and FDB initiates the connection.

USB debugging procedure for Android

In order for the Flash debugger running on the desktop computer to connect to the AIR runtime running on the device or emulator, you must use the Android Debug Bridge (ADB - utility from the Android SDK) or the iOS Debug Bridge (IDB - utility from the AIR SDK) to forward the device port to the desktop port.

  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 application using the appropriate debug target (such as apk-debug) and specify the ‑listen option:

    adt -package -target apk-debug -listen -storetype pkcs12 -keystore ../../AndroidCert.p12 DebugExample.apk DebugExample-app.xml DebugExample.swf
  4. Connect the device to the debug computer with a USB cable. (You can also use this procedure to debug an application running in an emulator, in which case, a USB connection is not necessary — or possible.)

  5. Install the application.

    You can use the ADT -installApp command:

    adt -installApp -platform android -package DebugExample.apk
  6. Forward TCP port 7936 from the device or emulator to the desktop computer using the Android ADB utility:

    adb forward tcp:7936 tcp:7936
  7. Launch the application on the device.

  8. In a terminal or command window run FDB using the -p option:

    fdb -p 7936
  9. 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
  10. The FDB utility attempts to connect to the application.

  11. When the remote connection is established, you can set breakpoints with the FDB break command and then start execution with the continue command:

    (fdb) run 
    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
Note:

Port number 7936 is used as the default for USB debugging by both the AIR runtime and FDB. You can specify different ports to use with the ADT -listen port parameter and the FDB -p port parameter. In this case you must use the Android Debug Bridge utility to forward the port number specified in ADT to the port specified in FDB: adb forward tcp:adt_listen_port# tcp:fdb_port#

USB debugging procedure for iOS

In order for the Flash debugger running on the desktop computer to connect to the AIR runtime running on the device or emulator, you must use the iOS Debug Bridge (IDB - utility from the AIR SDK) to forward the device port to the desktop port.

  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 application using the appropriate debug target (such as ipa-debug or ipa-debug-interpreter, and specify the ‑listen option:

    adt -package -target ipa-debug-interpreter -listen 16000 
    xyz.mobileprovision -storetype pkcs12 -keystore Certificates.p12  
    -storepass pass123 OutputFile.ipa InputFile-app.xml InputFile.swf
  4. Connect the device to the debug computer with a USB cable. (You can also use this procedure to debug an application running in an emulator, in which case, a USB connection is not necessary — or possible.)

  5. Install and launch the application on the iOS device. In AIR 3.4 and higher, you can use adt ‑installApp to install the application over USB.

  6. Determine the device handle by using the idb -devices command (IDB is located in air_sdk_root/lib/aot/bin/iOSBin/idb):

    ./idb -devices 
     
    List of attached devices 
    Handle    UUID 
        1     91770d8381d12644df91fbcee1c5bbdacb735500
    Note:

    (AIR 3.4 and higher) You can use adt ‑devices instead of idb ‑devices to determine the device handle.

  7. Forward a port on your desktop to the port specified in the adt ‑listen parameter (in this case, 16000; the default is 7936) using the IDB utility and the Device ID found in the previous step:

    idb -forward 7936 16000 1

    In this example, 7936 is the desktop port, 16000 is the port that the connected device listens on, and 1 is the Device ID of the connected device.

  8. In a terminal or command window run FDB using the -p option:

    fdb -p 7936
  9. In the FDB window, type the run command:

    Adobe fdb (Flash Player Debugger) [build 23201] 
    Copyright (c) 2004-2007 Adobe, Inc. All rights reserved. 
    (fdb) run
  10. The FDB utility attempts to connect to the application.

  11. When the remote connection is established, you can set breakpoints with the FDB break command and then start execution with the continue command:

Note:

Port number 7936 is used as the default for USB debugging by both the AIR runtime and FDB. You can specify different ports to use with the IDB -listen port parameter and the FDB -p port parameter.

Adobe logo

Sign in to your account