Tutorial 5: Deploying to mobile devices

So far, we’ve built some Mobile applications using MadComponents and Pure ActionScript.   Now we’re going to learn how to deploy them to mobile devices (Android, iPhone, iPad, etc..).  If you’re using a new version of Flash CS5.5, or Flash Builder 4.5, then you’ll already know how to do this from the application.  But If you haven’t yet rushed out and bought the latest upgrade, then read on… because you can use Adobe’s FREE Flex SDK tools.

One Core, Many Flavours

MadComponents is IDE agnostic, so you might have built your application using Flash, or Flash Builder (Flex), or a third-pary free IDE such as AXDT or Flash Develop.  Because MadComponents is based on standard ActionScript, with no AIR-only features, you might even test the core of your mobile application in the browser.

This is what I do.  I divide my AIR Mobile projects into two parts, separating the AIR and non-AIR code.  First I develop a core ActionScript project.  No exotic AIR classes.  It runs in the browser, or anywhere, and you don’t need Adobe’s latest development tools to develop it.

Now I can extend this core, or derive several variants from it if I wish.  One for iPhone, One for Android, One for desktop AIR, One for the browser, etc.

So now if want to add AIR mobile classes, to handle accelerometer events, or utilise the sqlite database, or whatever – I put this AIR code in a separate class.  It extends the top class of my core project, and makes it specific to mobile deployment.  You can use free command-line tools to build this project if your IDE doesn’t support AIR.

Anyway, this is the way I structure my AIR projects.  It may, or may not suit you.

Adobe’s free Flex SDK

You can get the latest release version of Adobe’s free Flex SDK from http://www.adobe.com/cfusion/entitlement/index.cfm?e=flexsdk

(There are downloads for MacOS and Windows.  I’m not sure what the situation is for Linux now.  Anyone? – can you leave a comment if you know).

Once you download this folder, you may or may not want to move it somewhere convenient in your filesystem.  On my Mac, I’d move it to the Developer directory.

Optionally, set a path to the “bin” folder.

amxmlc

amxmlc is the compiler for air applications.  Let’s assume your top application class is called MadProject.as, inside a MadProject folder.

1. Start up your terminal / command-line window.

2. Set the directory to your MadProject project folder.  For example,

cd /Users/danielfreeman/Desktop/MadProject

3. Compile the project.  This creates a familiar .swf file.  Let’s assume that you also want to include the MadComponentsLib, you would write:-

/Developer/flex_sdk_4/bin/amxmlc  -library-path+=MadComponentsLib0_5_5.swc  MadProject.as

i. I’m assuming that the path to amxmlc is /Developer/flex_sdk_4/bin/.  But if you’ve put the Flex SDK somewhere else, change the path appropriately.  If you’ve set up a path, you can omit the path.

ii. I’m assuming that you’re using MadComponentsLib0_5_5.swc.  But if you’re using a later version, change this filename.

iii. I’ve assumed that there’s a copy of the .swc library inside the MadProject folder.  Alternatively, set a path to where it is.

When you type this command into the terminal window, it should create your MadProject.swf file.

Android application.xml

We’re going to use adt to create a .apk file for android.  But first, we’re going to make an application.xml file:-

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<application xmlns="http://ns.adobe.com/air/application/2.7">
 <id>MadTest</id>
 <filename>MadTest</filename>
 <name>MadTest</name>
 <versionNumber>0.1</versionNumber>
 <description>MadTest example</description>
 <supportedProfiles>mobileDevice</supportedProfiles>
 <initialWindow>
  <content>MadTest.swf</content>
  <visible>true</visible>
  <fullScreen>true</fullScreen>
  <aspectRatio>portrait</aspectRatio>
  <autoOrients>true</autoOrients>
 </initialWindow>
</application>

This is a very simple template that you can apply to your own projects.   For more information about further options, refer to the documentation at http://help.adobe.com/en_US/air/build/WS5b3ccc516d4fbf351e63e3d118666ade46-7ff1.html  Or you can take a look at samples/descriptor-sample.xml in the Flex SDK you downloaded.

The options for <aspectRatio> are portrait or landscape.  This determines the initial orientation of your application when it is run.  If you set the <autoOrients> parameter to false, then it will stay in this orientation, and it won’t adjust to device orientation.

Android Permissions

For Android applications, you need to specify permissions for various resources that you use in your application.  So if your app uses the internet, or geolocation, or some other privileged resource – you need to give yourself permission.  You need to specify these permissions inside the application.xml file.  You would put the following XML before the </application> tag above.

<android>
    <manifestAdditions>
        <![CDATA[
            <manifest>
                <uses-permission android:name="android.permission.INTERNET" />
            </manifest>
        ]]>
    </manifestAdditions>
</android>

(More information about permissions here.)

Signing your application

All Android applications must be signed.  We can use Adobe’s adt tool to create a signing certificate:-

/Developer/flex_sdk_4/bin/adt -certificate -cn -validityPeriod 25 myidentifier 1024-RSA myCertificate.pfx mypassword

Where mycertificate and mypassword are strings of your own choosing.  This will create a .pfx certificate file called myCertificate.pfx.  If you want to put your application on an Android market, you must create a certificate that’s valid for at least 25 years, Hence -validityPeriod 25.

Creating the Android app

Now we’ve prepared the three ingredients to make our android .apk app.  The compiled .swf file, the application.xml and the self-signed certificate.  We can use adt to package for Android:-

/Developer/flex_sdk_4/bin/adt -package -target apk -storetype pkcs12 -keystore myCertificate.pfx -storepass mypassword MadProject.apk application.xml MadProject.swf

This command will create the Android .apk file.

Installing on an Android phone

We can use Google’s adb tool to install the .apk file on an Android phone.  (Get it here.)  On a Windows PC, you may need a driver to allow your PC to talk to your phone.  There’s an install folder in the SDK, that may be relevant to your system.  On a Mac, it just works.  So if you have a driver, plug your phone into your computer.

First of all, you’ll need to install the AIR runtime for Android.  You’ll find it in the Flex SDK.  (runtimes/air/andoid/device/Runtime.apk)

adb -r install Runtime.apk

You only need to install the runtime once.  Not every time.  Now install your application.

adb -r install MadProject.apk

Building an iPhone application

Now, we’re going to package the same application for iPhone.  Last, time we didn’t make any app icons, so let’s go through that step this time.  And we’ll need an application.xml file for iPhone.

Making Icons

Use an image editor to make an icon, and export four .png files of different sizes.  29×29 pixels, 57×57 pixels, 72×72 pixels and 512×512 pixels.  For test purposes, you can just create blank .pngs.  Put these four images into an icons folder inside your MadProject folder.

iPhone application.xml

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<application xmlns="http://ns.adobe.com/air/application/2.7">
	<id>MadProject</id>
	<filename>MadProject</filename>
	<name>MadProject</name>
	<versionNumber>0.1.0</versionNumber>
	<supportedProfiles>mobileDevice</supportedProfiles>
	<initialWindow>
		<renderMode>gpu</renderMode>
		<content>hello.swf</content>
		<visible>true</visible>
		<fullScreen>true</fullScreen>
		<aspectRatio>portrait</aspectRatio>
		<autoOrients>true</autoOrients>
	</initialWindow>
	<supportedProfiles>mobileDevice</supportedProfiles>
	<icon>
		<image29x29>icons/icon29.png</image29x29>
		<image57x57>icons/icon57.png</image57x57>
		<image72x72>icons/icon72.png</image72x72>
		<image512x512>icons/icon512.png</image512x512>
	</icon>
	<iPhone>
		<InfoAdditions>
		<![CDATA[
			<key>UIStatusBarStyle</key>
			<string>UIStatusBarStyleBlackOpaque</string>
			<key>UIRequiresPersistentWiFi</key>
			<string>NO</string>
		]]>
		</InfoAdditions>
	</iPhone>
</application>

<renderMode> gpu means that we’re going to use hardware accelerated graphics.  Notice how we’ve referenced our four icon files.

Provisioning Profile and Developer Certificate

To export to iPhone, iPad, or Ipod, you need to be a paid-up Apple Developer.  Within the members area of http://developer.apple.com, you can create and download a provisioning profile, and a developer certificate.

Packaging for iPhone

So we have the following ingredients that we will use to make a .ipa file for iPhone.

1. A compiled .swf file.  MadProject.swf

2. An iPhone application.xml file.  applicationiPhone.xml

3. Application Icons.  icon29-icon512.png

4. An Apple developer certificate.  developerKey.p12

5. An Apple provisioning profile.  docProfile.mobileprovision

Use adt to build the .ipa as follows.  (Prior to Flex 4.5 SDK, we used to use a tool called “pfi” (packager for iPhone), but this is now deprecated).

/Developer/flex_sdk_4/bin/adt -package -target ipa-debug -provisioning-profile docProfile.mobileprovision -storetype pkcs12 -keystore developerKey.p12 -storepass mypassword MadProject.ipa applicationiPhone.xml MadProject.swf icons/icon29.png icons/icon57.png icons/icon72.png icons/icon512.png

Ok, that’s a long command to type in.  I usually paste all of these commands into a .txt file that I keep in my project folder.  So every time I want to use it, I copy and paste to pop it into my terminal window.

You can install this .ipa application on your iPhone, iPod, or iPad using iTunes.  For more information about adt, take a look here.

What’s next ?

In the next tutorial we’re going to delve deeper into MadComponent’s capabilities.  Advanced Navigation, Scrolling containers, Tab-based applications, View Flippers, Groups, Pop-Ups, and Sliding Drawers.

Further reading

To find out more about MadComponents, you can read the other related threads on this blog, or download the documentation at http://code.google.com/p/mad-components/downloads/list

There are also lots of code examples to view or check-out from the subversion repository at http://code.google.com/p/mad-components/source/checkout

Please subscribe to this blog if you want to catch subsequent tutorials.