Requirements

Prerequisite knowledge

Prior experience developing projects with Flash Builder is required. Previous knowledge of building mobile apps is recommended.

 

Additional required other products

User level

All

One of the biggest challenges Flash developers face when developing AIR mobile applications is determining how to organize and create builds for each platform. This can be a daunting task if you are targeting web, desktop, phones, tablets, and TV. Luckily, Adobe has spent a considerable amount of time and energy devising the best solution to make multi-platform deployments as easy as possible. Flash Builder 4.5 enables you to take advantage of the new mobile features to streamline the output for multiple platforms.

When you start setting up a new mobile or Flex Hero project in Flash Builder 4.5, you'll see a set of new mobile templates.. In this article, I'll describe how to work with these new project configuration windows and provide an overview of how to configure your next project for iOS, Android, and PlayBook (see Figure 1).

I recently created a simple game called MatchHack, which you can use to to test the new features in Flash Builder 4.5. It's outside the scope of this article to provide instructions on building the MatchHack game. However, you can use it to explore the process of deploying a final project to multiple mobile devices. I'll provide the instructions and source code so that you can check it out. To get started, you'll take a look at the MatchHack game.

MatchHack is a simple matching game with some elements borrowed from RPGs. The goal was to make a kid friendly RPG without all the complexity. This game took me approximately 15 hours to build. I borrowed some assets and code libraries from an existing game I have been developing. I think this game is a good example of a multi-platform Flash game and certainly more interesting than a boring "Hello, World" app. All of the source code is uploaded to GitHub. If you'd like to review the source, click the download button on the GitHub project page to get a copy of the source directly from the repository.

Setting up a new project

In this section, you'll see how to set up a new project in Flash Builder 4.5. If you would like to use MatchHack for your project, simply download the source code and copy it in the Flash Builder 4.5 workspace folder. When you begin setting up a new project in Flash Builder 4.5 you'll notice that several new project templates are available to make mobile development and deployment incredibly easy. The two main templates are called Flex Mobile Project and ActionScript Mobile Project (see Figure 2).

When you create a new project with Flex Mobile it uses Hero, which is the mobile-friendly version of Flex. When you select an ActionScript Mobile Project, it does not include any components and you must build everything from scratch. The MatchHack game is an ActionScript Mobile Project.

Configuring a project

The new project wizard has been updated in Flash Builder 4.5. I followed the steps listed in this section to set up MatchHack. First, I entered the Project name and selected its location (see Figure 3):

After creating a new ActionScript Mobile Project, I clicked the Browse button and navigated to my checkout of MatchHack, which was located in the Flash Builder workspace folder on my computer.

I clicked Next to access the Mobile Settings. The Mobile Settings menu allows you to configure some global settings for your mobile app, as well as access more granular settings (depending on the platform). This is very helpful when starting a new project because some of these options become buried in the project menu. Additionally, the options you set in the Mobile Settings menu impact how the Air app.xml is generated (see Figure 4).

Note: By default, Apple iOS and Google Android support are built into Flash Builder 4.5. If you want to develop for the PlayBook, you will need to install their SDK and tools, which are available on the BlackBerry Developer site. After you install the SDK, BlackBerry Tablet OS will be listed in the menu along with the other supported platforms.

The last step to set up MatchHack is to add the project's Libs folder to your Libraries path. You'll find the library in the Build folder. Click Add Folder and then browse to select it (see Figure 6).

I always store my SWC files and additional libraries for my projects in the build folder. MatchHack is built on top of another one of my open source projects called FActivity. This library provides a simple screen management system, game loop, and green threading solution mobile applications. To learn more about it, visit the FActivity wiki. To make things easy, I distribute the SWC file along with the source code for MatchHack.

Run configurations

When it comes to compiling mobile applications, you'll need to set up individual runs for each platform. A Mobile Application run is similar to a normal Flash or Flex run except it includes specific settings and menu options for the intended platform. This strategy also helps keep things separated and more organized—so you can customize each build for its intended platform.

Once the project is set up, you can right-click on the main class, MatchHack.as, in the SRC folder and select Run As > Mobile Application (see Figure 7).

You can select a platform by picking an option from the Target Platform field. You'll notice that each platform has a different setup and Launch Method setting (see Figure 8).

Configuring mobile platforms

In this section, I'll cover each platform's configuration settings and describe how to get them up and running.

Note: For each platform, you have the option of running on the desktop or on an actual device. The desktop testing is a great option for validating quick changes, but for performance tuning and final testing, you should always deploy to an actual device.

Google Android

I'll describe the Android platform first because it's the easiest to set up and start running. Additionally, it's also one of the most robust mobile AIR platforms currently available. Access the Android configuration in your run by selecting Google Android from the Target Platform drop-down menu (see Figure 9).

When it comes to testing on an actual device, you have to set up your phone to activate USB debugging. See Connect Google Android Devices in the Adobe Flex 4.5 Help Documentation to get step-by-step instructions. Here's a quick summary of the process:

  1. If you are on a Windows machine, you must install the USB drivers. If you are on a Mac, this will simply work.
  2. Enable USB debugging on your device.
  3. Connect the device to the computer via USB.
  4. Select the option to Compile in Flash Builder; it will automatically install the application on the device connected to your computer.

Apple iOS

Flash Builder 4.5 includes the latest build of AIR, which is currently at 2.6. In the 2.6 release, the iOS Packager moved into the AIR tooling, as well as some significant performance boosts. Flash Builder facilitates the process of building and deploying an iOS application. The trickiest part of the process is understanding Apple's provisioning. Here is a quick overview of the steps:

  1. Log into the Apple iOS Developer center and create your Certificate. Then, download it to your computer.
  2. Import the Certificate into the keychain (this is easiest on a Mac) and generate a P12 Certificate, which Flash Builder needs in order to sign your app.
  3. Register your device's UID.
  4. Create an Apple ID, which will look similar to your application's package name. For this example, I used com.gamecook.matchhack .
  5. Next, create a provisioning profile, which combines the Certificate, your UID, and the Apple ID into a single file.

Once you have the final P12 Certificate and the Provisioning file, you can set up Flash Builder to compile your Flash app. Click the Configure Package settings in your run once you select Apple iOS from the Target Platform.

As you can see, I just point the Certificate path to my P12 file and the Provisioning file to the one I downloaded from Apple's developer portal (see Figure 10).

After setting these things up, click Run. Flash Builder will compile an .ipa file, which you can drag into iTunes and manually install.

Note: Building an iOS app takes a considerable amount of time. This is probably the one device you will want to do all of your testing locally and then do some verification deployments in between major development. On my iMac 3.1.4 core i7 with 12 gigs of RAM, it took approximately three minutes to build MatchHack.

BlackBerry Tablet OS

Developing for the PlayBook is relatively new and all of the development tools were created by RIM/QNX. As I mentioned earlier, you must first install the PlayBook SDK in order to build apps for it with Flash Builder 4.5. The process around building, deploying, and signing a PlayBook app is also the most complex of the three AIR platforms. I'll cover the basics, but keep in mind that RIM is continuing updating their tools with each new release, so hopefully over time PlayBook apps will become as easy to develop as the other platforms. Let's take a look:

  1. Download the BlackBerry Tablet OS SDK from the BlackBerry Developer site.
  2. When you install the SDK, specify the location of Flash Builder and the Flash Builder 4.5 SDK installed on your machine.
  3. Install a copy of VMWare to run the emulator. There is a free version on Windows, but you'll have to purchase a copy on Mac.
  4. You can set up the VM image of the PlayBook, which is helpful for local testing if you don't have a device. Select the bundled VM image in your Flash Builder Install folder, which is in the SDKs directory, inside the BlackBerry SDK, in the subfolder named BlackBerryPlayBookSimulator. Look for the file ending in .vmx.
  5. Enable debugging in the PlayBook's Settings menu.

To obtain the Certificate to build your app, submit the BlackBerry Code Signing Keys Order Form. You need this Certificate file to sign your app as well as get a debug Certificate, which is required in order to deploy your app to a physical device for testing purposes. This process can take a day or more. Check your Inbox to look for the attached Certificate file. Once you receive it, you can use it for all of your applications. To learn more, see the article on the BlackBerry Tablet Development Guide site titled, Signing your application.

Except for the Certificate file process, the steps to set up a run for the BlackBerry PlayBook are similar to those used for Android and iOS. You can select the desired options in the ActionScript Compiler (see Figure 11).

At this point, you know how to set up the three main mobile platforms and deploy your Flash games for most devices. In the next section, you'll learn how to optimizing your game applications to improve performance for various types of hardware.

Tips and tricks for optimization

In this section, I'll describe some helpful strategies to optimize your multi-platform projects.

Upscale whenever possible

When building AIR apps for any platform, pay special attention to the intended application's resolution. On the web, the baseline is usually around 1024 x 768 pixels. Most sites actually scale up to even higher resolutions. On mobile, however, you have to be especially careful since most of the Android phones run at 800 x 480 pixels and tablets are 1024 x 768 pixels. Consider that you'll be designing for devices with significantly less power than a desktop computer, using the same resolution used for desktops. One strategy to improve performance of a mobile app is to upscale it.

Upscaling is a practice that involves designing for half the native resolution and changing the display's scale by a factor of two. Obviously, the smaller the dimensions, the better the performance will be. All of the Flash mobile games I have been building use this technique; the difference in performance is staggering. In the world of mobile, even a few extra FPS could mean the difference between a usable and unresponsive application. Upscaling is also a great technique to use if you want to achieve retro 8 and 16-bit looking graphics. Avoid using vectors because upscaling vector graphics doesn't reduce file size and will actually add a performance penalty. The code below illustrates how to calculate the scale based on the height of the screen for portrait applications.

// 400 is the ideal height of your app before the scale var scale:int = stage.stageHeight / 400; // Set the scaleX and Y for the main app’s DisplayObject this.scaleX = this.scaleY = scale;

Simplify the elements in the application's UI

It is incredibly challenging building games or apps that are required to run on multiple resolutions. When I designed MatchHack, I created an inventory of each resolution and calculated the dimensions of a design that would render correctly when scaled across each screen. After calculating, I created the following list of supported resolutions for the target devices:

Resolution

Devices

480 x 320

iPhone 3GS, Android

800 x 480

Android

854 x 480

Android

960 x 640

iPhone 4

1024 x 600

Android Tablet

1024 x 786

iPad, Web

1280 x 720

TV, Web

1280 x 800

Android Tablet

As you can see, the game supports many different resolutions and aspect ratios. The Xoom tablet (at 1280 x 800) was the highest in the list. It is a huge resolution to have to support, especially when compared to the much lower screen resolutions for the 3GS iPhone and lower end Android devices running at 480 x 320. Fortunately, the Xoom tablet is capable of running Flash at higher resolutions, but it still required me to design a UI to fit all of these different devices.

Most mobile apps are currently following the trend to simplify the UI as much as possible, especially on smaller screen applications. This technique also works well on desktop applications. The simplified UI used for MatchHack is shown in Figure 12.

In addition to simplifying the UI, I also tried to streamline the game's menus (see Figure 13).

Once a fight is completed, the user moves on to the next level (see Figure 14).

Test on devices

Always test early and often when developing applications for tablets and other mobile hardware. I have devised a really good workflow to test my apps with my Xoom and other Android devices. I use an Ant Build to automate all my builds. Currently, it outputs a Web build, AIR build, Chrome Market build, Android APK, iOS IPA, and the PlayBook BAR (see Figure 15).

After configuring my Ant Build, I set my deploy folder to a Dropbox folder. When you are testing an app on five or six different devices, it's hard to have them all connected to your computer at the same time. One of the great things about Android is that if you install Dropbox and enable third-party app installs, you can actually load your game onto the device directly from Dropbox. This is a huge time saver. Additionally, I can share my Dropbox folder with all my testers so they always get the latest build and I never need to walk them through installing an APK via the command line.

When it comes to iOS and the PlayBook VM, you'll need to take a more manual approach. Luckily for the PlayBook, you can simply have Ant package a pre-built SWF file. I tend to be more hands on with my iOS builds since they take more time to compile and you have to manually install them via iTunes. I run nightly builds for my game and I make sure to always build out the iOS IPA and the PlayBook BAR file for others who want to test it.

Target specific OS features

At the moment, iOS is becoming the ideal platform for building AIR tablet apps for Flash developers. Adobe has spent a great deal of time optimizing the runtime for that platform, and it shows. I am seeing very impressive performance with my iPad 2, and there is great performance for all of the upcoming dual-core Android tablets too. Unfortunately, there is still work to be done to match the performance between Android and iOS. This is where the strategy of enabling or disabling some of your application's features by OS may come in handy. This technique is not limited to iOS. For example, you may choose to display higher resolution graphics on desktop and scale everything down on mobile apps. This is a common technique that is used in almost every 3D game on the market.

To get started, use the following code to access the current device's OS:

var os:String = Capabilities.version.substr(0,3); // returns AND or IOS on mobile devices.

By using the Capabilities Class, you can set up some conditional statements that define what each platform should do. For example, you can detect mobile OS's and generate lower resolution graphics or change the upscale resolution of your app to get better performance.

Now that you've learned some tips about optimization, you'll explore the final part of building a multi-platform app and learn how to submit your completed projects.

Submitting your app

Perhaps one of the most undocumented processes about deploying applications to multiple platforms is the submission process involved for each App market. The submission process can be complex, and it requires a great deal of asset preparation in order to complete the upload forms. In this section, I'll highlight the elements required for each of the major mobile markets: iOS, Android, Chrome, and the PlayBook.

iOS App Store submission

For the most part, submitting an application to Apple's App Store is a straight-forward process. The submission form is broken into separate screens (see Figure 16).

After entering the application's name, SKU number, and Bundle ID you are presented with a form you can use to submit all of the meta data and screenshots. You will need to supply the following sets of data shown in Figure 17:

Description

A description of the app you are adding, which details the app's features and functionality. Descriptions cannot be longer than 4000 bytes.

Keywords

One or more keywords that describe the app you are adding. When users search the App Store, the terms they enter are matched with keywords to return more accurate results. Separate multiple keywords with commas. Keywords cannot be edited once your binary is in review and the list of keywords cannot exceed 100 bytes.

Rating

Out of all of the app markets, Apple has the most detailed rating selection system. Simply select the options that make sense to the game you are submitting. After making your selections you will automatically receive a pending rating (see Figure 18).

Review notes

Additional information about your app and your In-App Purchases that may assist the app's review, such as the details of any test accounts to test them (including user names, passwords, access codes, etc.) Review Notes cannot be longer than 4000 bytes.

Assets

The following screenshots illustrate the types of asset files you'll provide when submitting your application. First, submit the large icon file (see Figure 19).

You'll also submit the smaller icon files for the application (see Figure 20).

Screenshots

To submit apps for the iPhone and iPod Touch, submit screenshots using the following dimensions (see Figure 21):

960x640, 960x600, 640x960, 640x920, 480x320, 480x300, 320x480 or 320x460 pixels

And to submit apps for the iPad, submit screenshots at these dimensions:

1024x768, 1024x748, 768x1024 or 768x1004 pixels

Notes

After adding the descriptions and uploading the screenshot images, you can save your game submission form and upload your final binary file. A unique feature of the iOS submission process is that you can choose the release date you would like to deploy your application, assuming you make it through the submission process.

Android Market Submission

Submitting to the Android market is an incredibly easy process. As soon as you submit your app, it's live in approximately 5 minutes. This uploading process offers incredible flexibility and enables you to quickly iterate updates of your app, in order to add new features and (most importantly), push out bug fixes (see Figure 22).

Use the list below to identify the items you'll need to submit an app to the Android market.

Assets

The Android market requires several different types of assets, along with your APK file.

The high resolution application icon is 512 x 512 pixels.

You'll also need to upload a promo graphic (180 x 120 pixels). If desired, you can also upload an optional feature graphic (1024 x 500 pixels).

Icons

Android supports a wide range of icons due to the many different device resolutions and dpi supported by Android devices. I use the following dimensions when I bundle up my APK file:

128 x 128 pixels

72 x 72 pixels

48 x 48 pixels

36 x 36 pixels

16 x 16 pixels

Screenshots

Screenshots come in several sizes to cover the range of resolutions on the Android platform.

Screenshots:

320 x 480, 480 x 800, 480 x 854, 1280 x 800 in either 24 bit PNG or JPEG (no alpha)

You can upload screenshots in either landscape or portrait orientation. For the MatchHack submission, I used the 480 x 800 pixel dimensions (see Figure 23).

Description

You'll need to create four types of descriptions for the Android submission form:

Title (9 characters)

Description (4000 characters)

Recent Changes (500 characters)

Promo Text (80 characters)

Device availability

An interesting feature of the Android submission process is the ability to limit the devices your application supports. For example, you can choose to block phones or devices that may not be powerful enough to run your application or game (see Figure 24).

Notes

After adding all of the required images and text, click Submit and your app will be on the market in a few minutes. Be sure to use the recent change textfield to describe updates to the app; developers update apps more frequently on Android then iOS since the submissions are not subject to approval. The recent change information helps set your users expectations, especially if you are adding new features in each push. Another unique feature of the Android Market submission process is that you can now add multiple APKs to target specific devices. This is very helpful when you are targetting low-powered devices, because you can remove animations or effects via a compiler argument to use your one click deployment workflow to generate the builds.

Chrome Market submission

The process for submitting apps to the Chrome market is very straight-forward. At this point you are already familiar with the submission process described for the other two platforms, so in this section I'll just highlight the main areas of interest. After submitting your application, the app is listed in the Chrome Market (see Figure 25).

Manifest file

A Chrome application is simply a ZIP file that contains your application. If desired, the app can also be a URL hosted on an external domain but I find that people would rather install the app locally. Add an HTML page at the root of the folder that will be compressed and set up all the supporting files in the manner you want to organize them. The main thing you need to include is a manifest file. This is similar to the XML App Descriptor file in Adobe AIR, except the version for the Chrome market is formatted in JSON. An example of manifest file is provided below:

{ "name": "MatchHack", "description": "Welcome to MatchHack, an open source, pick up and play, RPG matching game.", "version": "4.3", "icons": { "16": "images/icons/icon-16x16.png", "48": "images/icons/icon-48x48.png", "128": "images/icons/icon-128x128.png" }, "app": {"launch": { "local_path": "index.html" }}, "homepage_url": "http://matchhack.com" }

Promotional images

Upload the images used in the Chrome market to describe your app. You'll need to create and upload two different sizes:

Large banner: 585 x 220 pixels

Small banner: 210 x 140 pixels

Screenshots

When you prepare screenshots to upload to the Chrome Market, the image files will not match the exact size of your app. Usually, they'll be much smaller. In the case of MatchHack, I created a custom screenshot and positioned the title of the game on the left and right of the image to fill in the empty space (see Figure 26).

App icons

The submission process for the Chrome Market requires app icons similar to the other mobile platforms. The Chrome Market supports three icon sizes:

128 x 128 pixels
48 x 48 pixels
16 x 16 pixels

Description

Submit a description of the application that does not exceed 1600 characters.

Notes

After following the steps described above, the rest of the Chrome Market submission form is comprised of textboxes or simple checkboxes to specify the language, URLs for the product, and other related information. Additionally, there is one final image you can supply for the app's background when it is displayed in the market. This background image is 570 x 275 pixels. If you choose not to supply it, your app's landing page will look similar to the screenshot shown in Figure 27 with a blue gradient:

PlayBook Market submission

When you submit a PlayBook app to the BlackBerry App World, you'll fill out several screens worth of information that is similar to all of the other mobile platforms. After you submit your PlayBook application, it is listed in the market (see Figure 28).

Product icon

The BlackBerry App World uses a promotion icon to display in the app browser. You'll need to prepare and upload a 480 x 480 pixel product icon.

Screenshots

BlackBerry App World requires screenshots no larger then 640 x 640 pixels. This market is similar to the Chrome Market because the screenshot dimensions don't match the native resolution of the app.

Product featured image

This is an optional image file (1920 x 1186 pixels) used by the market to feature your app.

Description

Write and submit two descriptions. The short description is 50 characters and long description is 4,000 characters.

Now that you've learned about the promotional art and text needed to submit your application to each of the markets, you can begin preparing the image files and drafting the descriptions to start the distribution process. Strive to complete the prep work first because it makes it easier to fill out the submission forms if the assets are already created. Be advised that some of the submission forms are complex and don't allow you save your progress in the middle. Additionally, most of the submission forms will not allow you to advance to the next screen unless you upload all of the content required for each section.

Where to go from here

If you are new to this developing multi-platform Flash Builder projects, you may wish to experiment to devise the best mobile development workflow. Below I've highlighted a few of the items I learned while using Flash Builder 4.5 to create and distribute my game:

  1. Create a list of the platforms you intend to target. Research each platform to learn the limitations associated with each, including performance issues on iOS vs supported versions of Flash Player on the BlackBerry PlayBook. Once you understand the limitations, you can make informed decisions and create better-architected code.
  2. The most frustrating part of deploying to some of these devices revolves around understanding the certificate and code signing process. During the submission process for the PlayBook, I resorted to trial and error and made several attempts until things worked. The process for submitting iOS apps was much easier but I did have to make a few attempts before I learned about all of the requirements. I recommend reading the documentation describing each platform's certificate process to help alleviate deployment errors that may occur later.
  3. Start with a small project and work your way up to larger projects. Remember that even though Flash can run on all of these new devices, most handsets and tablets are incredibly less powerful then your desktop computer. If you start small and expand your application slowly, feature by feature, you'll discover performance issues before it is too late. Don't expect that you can convert an existing Flash app and make it run perfectly on a mobile device.
  4. Finally, keep your project organized. Especially when developing applications that run on multiple platforms. Your mobile applications will have icons, loading screens, embedded/loaded assets and more. Try to manage these supporting files in folders so that you can quickly find and modify the files on a platform-by-platform basis. This organization really pays off in the long run when it comes to maintaining your project, especially if you plan on updating the app for a specific platform at a time.

Hopefully this article has helped familiarize you with the considerations and best practices to follow when developing your own multi-platform Flash applications. If you are curious, download and analyze MatchHack's source code to learn some of the techniques I used to get it to work on each platform. I heavily commented the code to make it easier to decipher. Explore a real-world app to investigate strategies you can use to build your own mobile Flash apps with Flash Builder.

If you're attending MAX this year, be sure to attend my session. You can learn more about it in my article, Adobe MAX sneak peek: Blitting for Flash gaming across screens.

Check out these online resources to research further: