Developing Android Applications with Adobe AIR

The APK File

A variant of the JAR format used for compression and archival, APK is the file format used to distribute and install an Android mobile application. You can open an APK file using an archive tool such as WinZip or StuffIt Expander to see what is inside it. An APK file typically includes .swf and application.xml files containing assets, as well as a res folder which contains icons.

Creating the Application Icon

The default system icon is an Android-green icon. Icons need to be 36×36-, 48×48-, or 72×72-pixel PNG images. They are used for low-, medium-, and high-density screens, respectively.

You should make your icon stand out, while clearly identifying your application. Google provides guidelines on how to make icons, and provides a Photoshop template, at http://developer.android.com/guide/practices/ui_guidelines/icon_design.html.

In Flash Professional, go to File→AIR Android Settings→Icon and browse to the icons on your computer.

Note

If you use an icon of the wrong size in Flash Professional, the IDE will prompt you with a message that reads, “One of the specified icons do not have the correct dimensions.”

In Flash Builder, create a directory called icons in the src folder, and place your icons in it. Right-click on your project and select Properties. Then select ActionScript Build Packaging→Google Android→Package Contents and select the icons folder if it is not already selected.

In other tools, add a node to your application descriptor file as follows:

<icon>
<image36x36>icons/36.png</image36x36>
<image48x48>icons/48.png</image48x48>
<image72x72>icons/72.png</image72x72>
</icon>

Alternatively, if you are using the command line, place all your icons in a folder called icons and add it to the end of your statement:

AIR-sdk-path/bin/adt -package -target apk -storetype pkcs12
-keystore yourCertificate.p12 hello.apk Main-app.xml Main.swf icons

Publish your application one last time. Change your application to release mode if it is in debug mode. In Flash Professional, select File→AIR Android settings. Under the Deployment tab, for “Android deployment type,” choose Release.

If you are publishing from the command line, verify that the target is apk:

AIR-sdk-path/bin/adt -package -target apk -storetype pkcs12
-keystore yourCertificate.p12 hello.apk Main-app.xml Main.swf

Choosing the Application Settings

The application descriptor contains application settings, and should look similar to the following code. Note the required or optional annotation, and default, for each setting.

Here are the required tags:

<application xmlns=http://ns.adobe.com/air/application/2.6>
// Last segment specifies the version of AIR required

    <id>com.veronique.MyApplication</id>
    // Universally unique identifier.
    // Android converts ID to a package name by adding  
    // "air." to the beginning.
    // Hyphens are converted to underscore 
    // and digits are preceded by a capital A.

    <filename>MyApplication</filename>
    // name used for the APK package file

    <versionNumber>1.0.0</versionNumber>
    // contains three integers, up to three digits each

    <initialWindow>
    // properties of initial appearance of the application

        <content>Main.swf</content>
        // root swf

        <fullScreen>false</fullScreen>
        // application takes over the whole screen if true

        <aspectRatio>portrait</aspectRatio>
        // portrait (default) or landscape

        <autoOrients>false</autoOrients>
        // true (default) or false

        <visible>true</visible>

        <renderMode>cpu</renderMode>
        // cpu (default) or gpu

    </initialWindow>

</application>

The following tags are optional. They are child nodes of the application tag:

<name>Hello World</name>
// or localized
<name>
    <text xml:lang="en">English name</text>
    <text xml:lang="fr">nom français</text>
</name>
// name as it appears on device. Keep it short

<versionLabel>1.0.0</ versionLabel >
// Displayed in installation dialog

<description>
    <text xml:lang="en">English description</text>
    <text xml:lang="fr">Description française</text>
</description>

<copyright></copyright>

<icon>
    <image36x36>icons/36.png</image36x36>
    <image48x48>icons/48.png</image48x48>
    <image72x72>icons/72.png</image72x72>
</icon>

<customUpdateUI>false</customUpdateUI>
   // Update handled by user on double-click or automatic

<allowBrowserInvocation>false</allowBrowserInvocation>
   // can be launched from link in a browser

<android>
       <manifestAdditions>
        <![CDATA[
        <manifest>
        <uses-permission android:name="android.permission.CAMERA"/>
        <uses-permission android:name="android.permission.INTERNET"/>
        // Add all permissions as children of manifest tag

        <supports-screens android:normalScreens="true"/>
            <uses-feature android:required="true"
            android:name="android.hardware.touchscreen.multitouch"/>
            <application android:enabled="true">
                <activity android:excludeFromRecents="false">
                    <intent-filter>
                        <action
                        android:name="android.intent.action.MAIN"/>
                            <category
                            android:name=
                                "android.intent.category.LAUNCHER"/>
                    </intent-filter>
                </activity>
            </application>
        </manifest>
        ]]>
        </manifestAdditions>
</android>

Setting Permissions

The Android security and privacy model requires permissions to access certain features such as GPS. When clicking the Install button, the user sees the list of permissions and can then make an educated decision to opt out if desired.

Use the permission tag in the application descriptor to list all the permissions needed, as shown in the code below. Permissions cannot be modified at runtime.

Just before installing an application, the Android Market displays the permissions required. Figure 4-1 shows that Queue Manager, an application for managing your Netflix queue, only requires the Internet permission.

Warning

Before submitting your application, verify that you only include the permissions needed. Otherwise, you may filter out a group of users who will not see your application in their version of the Android Market.

<uses-permission android:name="android.permission.INTERNET" />
To make network requests. Can be used for remote debugging

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
To write data to external storage, such as the SDCard

<uses-permission android:name="android.permission.READ_PHONE_STATE" />
Read-only access of phone state. Used to mute AIR in case of incoming call

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
Access the location information. Fine for GPS location, Coarse for Cell/Wi-Fi

<uses-permission android:name="android.permission.CAMERA" />
Access the device camera

<uses-permission android:name="android.permission.RECORD_AUDIO" />
Access the device microphone

<uses-permission android:name="android.permission.DISABLE_KEYGUARD" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
Prevents device from dimming, going in sleep mode and activating keyguard

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
Access information on device network interfaces

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
Access information on device Wi-Fi networks

Android offers a lot of other settings, only some of which can be set in AIR but not documented. They should all be added to the Android→Manifest Additions→Manifest node.

Figure 4-1. The Queue Manager application before installation

The Android Launcher activity keeps track of the applications that have been launched. If a long press is applied on the home button, a list of recently run applications appears. If you do not want your application to be on this list, add excludeFromRecents to your manifest file as follows:

<android>
<manifestAdditions>
    <![CDATA[
    <manifest>
        <application android:enabled="true">
            <activity android:excludeFromRecents="false">
                <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
                </intent-filter>
            </activity>
        </application>
    </manifest>
    ]]>
    </manifestAdditions>
</android>

Applications are installed on the device memory by default. If you select Settings→Applications→Manage Applications, you will notice that some applications have the option “Move to SD card” (which then becomes “Move to phone”).

However, some Android applications and AIR applications do not have that option. If you type the following at the command line, all applications will now be moved:

adb shell pm setInstallLocation 2

To restore the settings, type the following:

adb shell pm setInstallLocation 0

If you set the installLocation tag to preferExternal, saving internally is not an option. All of your content, including your application, is stored on the SD card. This could be helpful for large applications. Keep in mind that the content is accessible to other applications, and therefore is vulnerable. If the SD card is full, the system falls back to an installation on the device:

<android>
    <manifestAdditions>
    <manifest>
        <attribute name="android:installLocation" value="preferExternal"/>
    </manifest>
    </manifestAdditions>
</android>

Read the Android recommendation regarding what should not be installed externally, online at http://developer.android.com/guide/appendix/install-location.html.

Users can erase the application data. If you want to prevent them from doing this, you can add the allowClearUserData attribute to the android node:

<manifest>
<application android:allowClearUserData="false" />
</manifest>

Warning

At the time of this writing, a bug in Android prevented this setting from working. It should be fixed in a future release.

You can also fine-tune permissions to add specific requirements. For instance, you may have an application which only works for devices with a camera auto-focus. You can add a different type of permission, uses-feature, to inform users of what is needed for your application:

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />

Android throws an error if a required permission is not set, such as for Internet or GPS, but not others, such as reading the phone state or disabling the keyguard. The criterion is what it considered potentially dangerous for the user. In AIR, the application always fails silently.

Native developers have a larger choice of features, and therefore permissions. You can go to http://developer.android.com/reference/android/Manifest.permission.html to learn about some of the new possibilities. If you see one that you would like to use, send Adobe a feature request, preferably with a use case so that it can be added to the AIR runtime, by going to https://www.adobe.com/cfusion/mmform/index.cfm?name=wishform.

For example, having an API to access contacts would open a lot of possibilities:

<uses-permission android:name="android.permission.READ_CONTACTS" />

Packaging External Resources

If your application has a lot of art, you may want to keep the art external to the application and load it at runtime. In the AIR for Android settings, if you are using Flash Professional, add the resources to the “Included files” list at the bottom of the General tab.

In Flash Builder, create a directory called assets in the scr folder, and place your art in it. Right-click on your project and select Properties. Then select ActionScript Build Packaging→Google Android→Package Contents and select the assets folder if it is not already selected.

If you are using the command line, list the files or the containing folders at the end of the command line:

AIR-sdk-path/bin/adt -package -target apk -storetype pkcs12
-keystore yourCertificate.p12 hello.apk Main-app.xml Main.swf
image.jpg movie.flv data.xml

Another way to handle external files is to store them on the SD card and access them via File Access. You cannot remove files included at the time of installation because it would make the application invalid. You can, however, copy them to the SD card. This is the approach you would use if you want to modify them during the life of the application. We will cover this method in Chapter 6.

Signing Your Application with a Certificate

All applications must be signed before being updated to the Android Market. This enables consumers to identify and establish trust with a developer. The developer signs the certificate using a private key. The private key is different from the one you used during development. Typically, a key generally using ADT is only good for five years.

To create a suitable key in Flash Professional, go to File→AIR Android settings→Deployment→Certificate and fill out every field. The publisher name will appear in the Android Market as you enter it. As before, make a note of the password, since you will need it when you compile your application. Choose Type 2048-RSA, Google’s recommended type.

The certificate must be valid for 25 years. The system only checks the certificate’s expiration date upon installation. If the certificate expires afterward, the application will continue working.

To create a suitable key using AIR ADT and the command line, use the following code, making sure to put your name and country in quotes:

AIR-sdk-path/bin/adt -certificate -cn "FirstName LastName" -c "US"
-validityPeriod 25 2048-RSA myCertificate.p12 myPassword

More information on this is available on the Android developer website, at http://developer.android.com/guide/publishing/app-signing.html.

When/if you later upgrade your application, you must use the same certificate, so keep it in a safe place.

Versioning

Versioning gives you the opportunity to submit fixes and updates to your application. A version number consists of three digits separated by dots, as in 1.0.0, referred to as major.minor.build. Set the version number in Flash Professional in the Settings window. In Flash Builder, open the application descriptor and change the version number in the XML.

For debugging purposes, you can check the version number at runtime from the applicationDescriptor of the NativeApplication.nativeApplication that is an XML object:

import flash.desktop.NativeApplication;

var applicationDescription:XML =
NativeApplication.nativeApplication.applicationDescriptor;

var ns:Namespace = applicationDescription.namespace();
// http://ns.adobe.com/air/application/2.6
var currentVersion:String = applicationDescription.ns::versionNumber;
// 1.0.0

The update to an application appears on the Android Market quickly.

As mentioned earlier in this chapter, the update can be accomplished in two ways. You can specify your preference in the application descriptor, or the user can specify it manually. The following tag implies that the update is handled by the user upon double-clicking:

<customUpdateUI>false</customUpdateUI>

If the user installs an update of your application, previously saved data is preserved.