How to build your Flex app for iOS with AIR 2.6

AIR 2.6 brought a lot of great stuff, but one specific feature I just couldn’t pass by — publishing for iOS. Yes, there was this thing called Packager For Iphone, but now it is a part of ADT and is claimed to be much faster.

So, we have Flash Builder Burrito, Flex Hero SDK focused on mobile development and now AIR 2.6. You can see clear vector where Adobe is moving. There are many tutorials for Android platform, but iOS is lacking. So, let’s try to compile a small Flex application for iPad.

First of all, there’s documentation on help.adobe.com which helped me a lot. But there are walls of text and much of it is about Android which we don’t need here.

Apple developer program.

This tutorial assumes that you are registered Apple developer because to actually upload your app to iOS device you’ll need:

1. Developer certificate
2. App ID
3. Provisioning profile

If you are not an Apple developer, you can still read the material because it is still helpful if you want to develop apps for other platforms, and who knows maybe one day you’ll join Apple developers community.

Well, first of all you need your developer certificate. Certificates are used to sign iOS applications. One for testing on devices (developer certificate) and another to publish to App Store (distribution certificate).

Basically, the process looks like this:

1. You generate a signing request
2. You send generated .csr file to Apple
3. (Your corporate account manager approves your certificate)
4. You download new certificate
5. You combine your private and public parts of certificate in a .p12 file
6. You use this .p12 file to sign your AIR application

Of course you need to do this only once.

Go to developer.apple.com, click on “Certificates” and follow the steps to upload certificate signing request (or read the “how to” guide on Apple developers site). Don’t worry if you are on Windows. AIR documentation has a whole section devoted to this process. There you will find step-by-step guide for generating certificates and converting them to .p12 format which AIR needs both for Mac and Windows. Just make sure that if you generated a certificate on Mac that you are converting it on Mac too (same for Windows).

In my app I put converted .p12 certificate to /certificates/ipadtest.p12 which is later used in ANT build file.

After that you need to add a new App ID for your test application. I chose just “ipadtest”. We will need this ID later.

And the last thing from Apple we will need is .mobileprovision file to be able to test our app on a real device. Don’t forget to add your iPad (or iPhone) to devices at Apple developer site.

How to find your device id.

Mobile Flex.

Adobe is doing great job with upcoming Flash Builder Burrito and Flex Hero SDK. If you are interested in Flash mobile future you should check out the videos and draft docs on Adobe Labs.

Also, there are several good articles on the web about mobile Flex development:

• Tips for Flex mobile apps
• View navigation in a mobile Flex application
• A couple of hacks for mobile Flex development
• Flex 4.5 mobile development post Burrito <– read this!

The last one is a good explanation of basic Mobile Flex concepts: MobileApplication, Views, Navigation bar, pushing and popping views. I definitely recommend it everyone who is curious about mobile Flex.

Also you will need ActionScript 3.0 Beta Reference.

Let’s get started.

Download and install Flash Builder Burrito with Flex Hero SDK and latest AIR SDK. You can develop in any IDE but it’s much more convenient to use the new Flash Builder, though you can’t export to iOS using it right now. We will use ANT script for publishing.

First of all add iPad to Device Configurations in Flash Builder preferences: Window -> Preferences -> Flash Builder -> Device Configurations -> Add with resolution 768×1024 and PPI 132.

We’ll be using Twitter Trends tutorial from Flex Hero SDK examples. Open the PDF in another window and download tutorial assets. Create Mobile Flex application as described in the tutorial. Don’t panic when you see the only option is to publish for Google Android. Select it and continue.

So now you have an empty Flex mobile app…

Application descriptor. General parameters.

First of all let’s modify app descriptor XML a bit. Open TwitterTrends-app.xml (or alike, if you called your project differently). More detailed information about setting up an application you can find at help.adobe.com. And right now I’ll guide you through important stuff.

First of all set namespace to 2.6:

<application xmlns="http://ns.adobe.com/air/application/2.6">

Set app id the same you added at Apple developers site but without random letters/numbers at the beginning. Warning! It’s a common mistake to copy the whole id from the site with these random numbers. Be careful!

<id>ru.interactivelab.ipadtest</id>

Add name and version info. Version must be 1-3 numbers separated by “.” and when you update your app it’s better to increase its version. Sometimes iTunes fails to update app with same version.

<filename>ipadtest</filename>
<name>iPad Test</name>
<versionNumber>1.0.1</versionNumber>

Set content manually to be able to use ANT. Make sure that it is your actual executable swf file.

<content>TwitterTrends.swf</content>

Seting visible = true might be necessary to test localy with ADL, but I think it does nothing when running with Device Emulator.

<visible>true</visible>

Set width and height.

<width>768</width>
<height>1024</height>

Set device specific parameters. Our app will be in portrait orientation. It won’t reorient. It will be fullscreen. It will be super fast using GPU. And it doesn’t need software keyboard.

<aspectRatio>portrait</aspectRatio>
<autoOrients>false</autoOrients>
<fullScreen>true</fullScreen>
<renderMode>gpu</renderMode>
<softKeyboardBehavior>none</softKeyboardBehavior>

Don’t forget to add mobileDevice to supported profiles.

<supportedProfiles>mobileDevice</supportedProfiles>

Application descriptor. iOS specific parameters.

Find the comment saying <!– iOS specific capabilities –> in application descriptor file. For detailed description refer to help.adobe.com but right now let’s replace <iPhone> block with

<iPhone>
	<InfoAdditions>
        <![CDATA[
            <key>UIDeviceFamily</key>
            <array>
                <string>2</string>
            </array>
            <key>UIRequiresPersistentWiFi</key>
            <string>NO</string>
	    <key>UIApplicationExitsOnSuspend</key>
	    <string>YES</string>
        ]]>
    </InfoAdditions>
</iPhone>

UIDeviceFamily key contains supported devices. 1 is iPhone/iPod, 2 is iPad. We are interested in iPad only. We don’t need persistent WIFI and want to close our app when Home button pressed (though it didn’t work for me).

Next we will need to add application icons and splash screens. Read this article to find out how to do it and what images you need. If you have none your app can still run but with empty white icon.

Following the tutorial.

Continue on the tutorial. Everything should be pretty easy. In design mode choose iPad as your device to see how views will be aligned on it. When asked to test run your application you will need to create a Debug Configuration for it.

I stopped when I had 2 views with data binding and item renderers. I decided to add back button so the app would look like this.

I added back button image. Get it here and put into src/assets folder. Here’s my final code for TwitterTrends.mxml.

<?xml version="1.0" encoding="utf-8"?>
<s:MobileApplication xmlns:fx="http://ns.adobe.com/mxml/2009"
					 xmlns:s="library://ns.adobe.com/flex/spark" firstView="views.twitterHome">

	<fx:Script>
		<![CDATA[
			protected function backBtn_clickHandler(event:MouseEvent):void
			{
				if ( navigator.length > 1 ) navigator.popView();
			}
		]]>
	</fx:Script>

	<s:actionContent>
		<s:Button id="refreshBtn" icon="@Embed(source='assets/refresh48x48.png')"
				  click="Object(navigator.activeView).refresh()" />
	</s:actionContent>
	<s:navigationContent>
		<s:Button id="backBtn" icon="@Embed(source='assets/back48x48.png')"
				  click="backBtn_clickHandler(event)" />
	</s:navigationContent>

</s:MobileApplication>

Building for iPad.

Here’s what you need to build your app for iOS:

1. Compiled SWF
2. Application descriptor
3. .p12 certificate
4. .mobileprovision
5. Icons (optional)
6. Splash screens (optional)

Let’s get compiled SWF first. We’ll be using ANT script to compile and publish our application so I assume that you have some knowledge of ANT scripts.

First of all I have 2 .properties files. You must change local.properties and specify paths to Flex, mxmlc and adt.

FLEX_HOME=e:/work/4.5.0hero
MXMLC=${FLEX_HOME}/bin/mxmlc.exe
ADT=${FLEX_HOME}/bin/adt.bat

build.properties just lists several relative paths.

app.rootdir=.
app.descriptor=${app.rootdir}/src/TwitterTrends-app.xml
app.rootfile=TwitterTrends.swf
app.sourcedir=${app.rootdir}/src
app.debugdir=${app.rootdir}/bin-debug
app.builddir=${app.rootdir}/bin-release
app.releasedir=${app.rootdir}/release
app.source=${app.sourcedir}/TwitterTrends.mxml

build.storetype=pkcs12
build.keystore=${app.rootdir}/certificates/ipadtest.p12
build.storepass=mysecretpassword
build.mobileprofile=${app.rootdir}/certificates/ipadtest.mobileprovision
build.name=ipadtest.ipa

Here’s an archive with local.properties, build.properties and build.xml — build.zip.

Build.xml has several build targets: clean, copy (copies assets from /src to /bin-release), compile and publish-debug. Take a look at compile target. Notice that I included a number of swc’s in weird locations.

-library-path+=’C:\Program Files (x86)\Adobe\Burrito\Adobe Flash Builder Burrito\eclipse\plugins\com.adobe.flexbuilder.dcrad_4.5.0.287807\fiberSwcs\4.0\libs\fiber.swc’

These are used by Flash Builder Burrito to generate classes for data binding. Also make sure you are using airmobile config (+configname=airmobile) or compiler won’t be able to find mobile Flex components.

Next important target is publish-debug. This command performs actual packaging (and does it very slow to be honest). You can find more information about packaging to iOS at help.adobe.com.

Here’re parameters I’m using in build.xml:

-package
-target ipa-debug
-storetype ${build.storetype}
-keystore ${build.keystore}
-storepass ${build.storepass}
-provisioning-profile ${build.mobileprofile}
${app.releasedir}/${build.name}
${app.descriptor}
-C ${app.builddir} ${app.rootfile} assets photos sampledata

You can build for several targets: ipa-test, ipa-debug, ipa-ad-hoc, ipa-app-store. With ipa-debug you can debug your app remotely on the device. Read more about remote debugging.

Testing on iPad.

After you’ve compiled your app into .ipa file and before you will be able to actually test it on your iPad, you need to drag .mobileprovision file to iTunes to indicate that it is authorized to install this specific app to the iPad with specific UID. You might need to drag .p12 file used too but I’m not sure if I did that or not.

Sync with iPad and check the app on device.

If you have problems syncing check that you have correct app id in app descriptor xml, that you provided correct iPad UID and didn’t mess anything up while converting certificates.

Conclusion.

While Adobe is doing great job trying to make AIR run everywhere, iPad performance is very poor so far. I’m getting huge interface lags even with this simple app. We even made a video which I posted earlier where you can see it yourself.

I hope that one day I’ll be able to create competitive iPad apps with AIR, but for now I’ll agree with Steve Jobs and will keep Flash away from my device.