How to create an Android app from a Flash .swf file with Adobe AIR SDK

From Color Infection Wiki
Jump to: navigation, search

Notice: This is one of the many workflows to develop Android apps.

Overview

Adobe AIR is a cross-platform runtime environment developed by Adobe Systems for building Rich Internet Applications (RIA) using Adobe Flash, Adobe Flex, HTML, and Ajax, that can be run as desktop applications or on mobile devices. The runtime supports installable applications on Windows, Linux, Mac OS and some mobile operating systems such as iOS and Android. (see the wikipedia item).

To run an AIR program on a target operating system, AIR runtime program must be installed on the operating system.

  • for PCs (I think Mac is also a PC), you download and install the AIR runtime here.
  • for Android mobile phones, there is a free app called Adobe AIR at the Google or Amazon Android Market. If you install an app which need Adobe AIR to run, the Android system will prompt you to install the free Adobe AIR app firstly.
  • for iOS (iPhone and iPad), sadly, Apple forbids Adobe providing a AIR runtime at Apple App Store. So Adobe AIR SDK will bundle your app with the AIR runtime together as a solo app. (In fact, the newest AIR SDK version supports bundling your app with the AIR runtime for any operating system.)

The AIR SDK is simple to use. It is more a packager tool than a development tool. It just packages your Flash apps developed by other Flash development tools. It can also package apps developed with HTML5+CSS+JavaScript.

Phyard.com supports "download your design as an *.swf file". And Phyard.com also supports "download design as an Android *.apk app". So you can get the Android app file from Phyard.com without any other tools. But if you want to use Adobe AIR SDK to package your design swf files by yourself, this tutorial is for you.

Package swf files by yourself

Install JRE

Adobe AIR SDK needs Java Runtime Environment (JRE) to run. And creating a certificate (see the below section) is also need JRE. If you have installed JDK, then you have already installed JRE, for JRE is included in JDK. Otherwise, if you don't need JDK to develop Java programs, you can download and install JRE individually. For Mac users, follow this instruction: http://kb2.adobe.com/cps/909/cpsid_90908.html.

Install AIR SDK

Download it here. Adobe has interrupted the development for AIR SDK Linux version from v2.7. You can download v2.6 for Linux here.

To install AIR SDK, just unzip the download zip package.

Set System Path Environment Variables

Sorry, I'm not good at English. It is hard for me to describe clearly how to set the PATH environment variable on all kinds of operating system. You can google "set PATH environment variable" + Windows (or Linux or Mac) to find the answer. Ok, when you get it, add the JRE_InstallDir/bin and and AIR_InstallDir/bin to your PATH environment variable, where JRE_InstallDir and AIR_InstallDir are the path of install directories of JRE and AIR SDK.

Maybe when you install JRE, the path JRE_InstallDir/bin has been already added to the PATH environment variable automatically. So you need only to add 'AIR_InstallDir/bin to the PATH environment variable.

In short, before adding the AIR_InstallDir/bin into the PATH environment variable, you will input the following command in a terminal or DOS console window to call the adt program in AIR SDK:

AIR_InstallDir/bin/adt -version

On Windows, it may be (in the following command examples, I will not show the Windows case any more. Just remember, on Windows, the separators in path is \ instead of /):

C:\AdobeAir\bin\adt -version

But after adding the AIR_InstallDir/bin into the PATH environment variable, you can call the adt command directly

adt -version

The command will output the version of the AIR SDK, for example, 2.6.0.19120, which means the AIR SDK version is 2.6.

Create The App Project

  1. Create a new directory anywhere to contain your project files.
  2. Then create a src folder in the project directory.
  3. Download the design swf file from Phyard.com and put it in the src folder. Assume you save it as MyGame.swf.
  4. Create a file MyGame-app.xml in the src folder, and put the following content in it:
<?xml version="1.0" encoding="UTF-8"?> 
<application xmlns="http://ns.adobe.com/air/application/2.6"> 
    <id>com.phyard.android.viewer.PhyardGame.DesignByTapir.AtSlot_3_7</id> 
    <versionNumber>1.2.3</versionNumber> 
    <filename>Color Infection 3</filename> 
    <versionLabel>1.2.3</versionLabel>
    <supportedProfiles>mobileDevice</supportedProfiles>
    <customUpdateUI>false</customUpdateUI>
    <allowBrowserInvocation>false</allowBrowserInvocation>
    <initialWindow> 
        <content>./MyGame.swf</content> 
        <fullScreen>true</fullScreen>
        <aspectRatio>landscape</aspectRatio><!-- portrait -->
        <autoOrients>false</autoOrients>
        <visible>true</visible>
        <renderMode>gpu</renderMode> <!-- cpu -->
    </initialWindow> 
    <android>
       <manifestAdditions>
        <![CDATA[
        <manifest>
           <uses-permission android:name="android.permission.INTERNET"/>
           <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
           <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>
</application>

You should modify it as needed:

  • change the 2.6 in xmlns="http://ns.adobe.com/air/application/2.6 to the real AIR SDK version. (if the version is larger than 2.6, you can also keep it unchanged.)
  • you should (try to) make sure the id com.phyard.android.viewer.PhyardGame.DesignByTapir.AtSlot_3_7 unique. I means it should not be the same as the other apps developed by the developers all over the world.
    • Please make sure no continuous number letters in the id, and the first letter of each segment in the id should not be a number letter. (This is an experience I got in developing Android apps) [edit: sorry, this is a wrong experience]
  • replace the file name Color Infection 3 with your game title. For English letters, the max length is 20. If the title contains any non-English letters, the max length is 10. (This is anohter experience I got in developing Android apps) [edit: sorry, this is another wrong experience]
  • set the correct version numbers. There are 2 positions to change. The 2 positions need not to be the same. For versionLabel, it can contain non-number letters.

Make Icons (Optional but Recommended)

You can/should make 3 icons for your Android apps. These icons are used as the app launch icon for phones with low/general/high screen resolutions.

  1. create a assets folder in the src folder, and make 3 icons with name icon36.png, icon48.png and icon72.png. Their sizes are 36x36, 48x48 and 72x72.
  2. add the following text in the MyGame-app.xml file (the same indent as the initialWindow and android elements)
   <icon> 
      <image36x36>./assets/icon36.png</image36x36> 
      <image48x48>./assets/icon48.png</image48x48> 
      <image72x72>./assets/icon72.png</image72x72> 
   </icon> 

Test the application

Assume your project directory is /home/Tapir/develop/projects/MyGame. Open a terminal or DOS console window, firstly enter your project directory:

cd /home/Tapir/develop/projects/MyGame

Then run:

adl src/MyGame-app.xml

to test your app. The adl is another command program in AIR SDK for your to test your apps.

Create A Certificate

Before packaging your app, you need a certificate to sign your app.

Create a folder cer in your project, then run the following commands in your project directory (replace MyCert.p12 and CertPassword as what you want):

adt -certificate -validityPeriod 25 -cn SelfSigned 2048-RSA cer/MyCert.p12 CertPassword

25 means 25 years. It is a recommended value. After a while, your certificate will be created in the cer folder. Please remember your password and avoid others stealing your certificate.

Package & Sign The App

Create a bin folder in your project directory to store the final output binary package file.

Ok, now your project directory looks this:

 /MyGame
  |- /bin
  |- /cer
      |- MyCert.p12
  |- /src
      |- MyGame.swf
      |- MyGame-app.xml

or this if you use custom icons (strongly recommended)

 /MyGame
  |- /bin
  |- /cer
      |- MyCert.p12
  |- /src
      |- assets
         |- icon36.png
         |- icon48.png
         |- icon72.png
      |- MyGame.swf
      |- MyGame-app.xml

Enter the src folder (assume you are in the project directory now):

cd src

Run the following command to package your game (where ../ means parent directory, for we are in the src directory now, so the parent directory is the project root directory):

adt -package -target apk -storetype pkcs12 -keystore ../cer/MyCert.p12 ../bin/MyGame.apk MyGame-app.xml MyGame.swf

You will be prompted to enter the certificate password. The output package file, MyGame.apk, will be put in the bin folder. You can submit it to Android app markets now.

I didn't run the last package command in the project root directory, the reason is there is a bug in AIR SDK 2.6. If you installed the latest version of AIR SDK this bug may have been fixed. If it is really fixed, you can run the following comamnds instead:

cd /home/Tapir/develop/projects/MyGame
adt -package -target apk -storetype pkcs12 -keystore cer/MyCert.p12 bin/MyGame.apk src/MyGame-app.xml src/MyGame.swf

Install The App Package On Your Android Phone

It is very easy and straight to install an app on your android phone.

References

  1. Developing AIR applications for mobile devices, http://help.adobe.com/en_US/air/build/WSfffb011ac560372f-5d0f4f25128cc9cd0cb-8000.html
  2. Creating your first AIR application for Android with the Flex SDK, http://help.adobe.com/en_US/air/build/WS901d38e593cd1bac25d3d8c712b2d86751e-8000.html
  3. Android APK packages, http://help.adobe.com/en_US/air/build/WS901d38e593cd1bac-4f1413de12cd45ccc23-8000.html
  4. Signing Your Applications, http://developer.android.com/guide/publishing/app-signing.html