How to publish your AIR application to Mac App Store (guide)

April 6th, 2012 | Posted by Nina in Guides

Update 2012/07: With new app store rules Apple now requires applications to be properly sandboxed and this guide does not describe this step. However, you can read about air app sandboxing in this post on adobe forums

Adobe Flash and AIR SDK are both very suitable instruments when it comes to development of a cross-platform game applications. With version 3.2 of AIR SDK and new Captive Runtime feature it became possible to create truly stand-alone apps for both Mac and Windows, which is especially useful for game distribution. The most attractive benefit of packaging AIR Runtime and application itself in one bundle is obviously a possibility to distribute it through Apple App Store.

Unfortunately, almost all guides found on the Internet are focused on publishing only on iOS — only one part of the App Store (the other two parts are App Store for Mac and plugins for Safari). This guide, on the contrary, is focused on Mac desktop application publishing.

Not all of our attempts to package Coloropus went so smooth and since we finally managed to pass Apple’s review process and publish our game to the Mac App Store, we decided to share a knowledge about major troubles we encountered during this process.

This writing is based on version 3.2 of AIR SDK. A new 3.3 version (codename “Cyril”) is coming up in the second quarter of 2012 and it will hopefully have more comprehensive Mac applications packaging support and App Store integration which in theory should solve all those issues described here (as of April 8th, 2012 AIR 3.3 Beta is available).
February 22, 2012 Adobe has released a new Flash Player/AIR roadmap that explains where Adobe is heading in terms of the new features.

Packaging an application

First of all, of course, you will need an SWF compiled as AIR application. The next step after compiling the SWF is packaging it as a native bundle with Captive Runtime. This and consequent steps have to be done on Mac OS X with appropriate version of AIR SDK. Note, that you do not need the whole Flex SDK but only AIR SDK (adt) for this. Application on this step should be signed with Adobe AIR certificate.

I will not go into details about AIR app packaging, you can find this information on Adobe’s website. Here is the command we used to package our game (our main SWF is contained in bin directory):

/path/to/adt -package -storetype pkcs12 -keystore /path/to/certificate -storepass CERTIFICATE_PASSWORD -target bundle /path/to/bundle application.xml -C bin .

You will have your application packaged into /path/to/bundle.app upon the command’s completion. You can also use this command to test your SWF under Mac OS X before packaging:

/path/to/adl application.xml -C bin .

Getting Apple Developer certificates

To sell applications on Mac App Store you have to register in Apple’s developer program for Mac. For packaging your application you have to get two Apple developer certificates – first one is for signing application itself and the other one is for signing installation package (explained below). The first one is called Apple’s Developer Certificate and the second one is Apple’s Developer Installer Certificate.

To create and download your developer certificates, you will have to:

  1. Register in Apple’s developer program.
  2. Login to Mac Dev Center.
  3. Go to Developer Certificate Utility (https://developer.apple.com/certificates/).
  4. Use links “Create Certificates” and “Download Certificates” in “Certificates” section and follow onscreen instructions.
  5. Import your new certificates into the Keychain on your Mac.

Honestly, Apple has very good and detailed instructions. Just be sure to check article “Tools Workflow Guide for Mac” in the Mac OS X Developer Library.

Codesign process

Next step after receiving developer certificates is codesign process. Note, that here you should sign your bundle with Apple’s certificates, not with the AIR ones! For signing use codesign command line utility that comes with Apple’s Xcode developer tools.

If you want to change icon of your application or add some metadata (version, localization and so on), that will be shown in iTunes once you submit it, this is the place where you should do it – before the code sign.
On Mac, *.app is really just a directory with application files and metadata for description of a bundled contents. Main descriptor file (similar to AIR application descriptor) is called Info.plist and located in your *.app under Content directory. This file is just an XML dictionary containing keys and values:

<?xml version=”1.0″ encoding=”UTF-8″?>
<!DOCTYPE plist PUBLIC “-//Apple//DTD PLIST 1.0//EN” “http://www.apple.com/DTDs/PropertyList-1.0.dtd”>
<plist version=”1.0″>
<dict>
<key>CFBundleAllowMixedLocalizations</key>
<true/>
<key>CFBundleExecutable</key>
<string>Coloropus</string>

</dict>
</plist>

The most important properties that you might want to add here are:
1. CFBundleIdentifier — bundle identifier in (reverse domain notation)
2. CFBundleIconFile — name of the icon file for your application. Icon file should be in *.icns format and reside in Content/Resources directory inside of the bundle.
3. LSApplicationCategoryType  – your application category according to Apple’s specification. Full list of possible category types is available at this page (check section “Categorize Your Application”). Note: for games Apple provides special list of subcategories that you may use to specify exact category for your game.

You can change Info.plist with Max OS X built-in XML editor or with Xcode integrated editor. Former proved to be a lot simpler. To set the settings just add these string to Info.plist using Property List Editor or Xcode:

<?xml version=”1.0″ encoding=”UTF-8″?>
<!DOCTYPE plist PUBLIC “-//Apple//DTD PLIST 1.0//EN” “http://www.apple.com/DTDs/PropertyList-1.0.dtd”>
<plist version=”1.0″>
<dict>

<key>CFBundleIconFile</key>
<string>Coloropus.icns</string>
<key>CFBundleIdentifier</key>
<string>com.pigsels.coloropus</string>
<key>LSApplicationCategoryType</key>

<string>public.app-category.adventure-games</string>

</dict>
</plist>

and save it.

After updating your application’s metadata and before the actual signing you should take some additional actions – failing to do so might lead to a failed review upon sending your app to the app store.

1. Now, it’s time to make the magic: remove webkit.plugin from your bundle. This, of course, means, that you will not be able to use HTML rendering in your AIR application. The reason behind this is that Apple will refuse your app with WebKit plugin in it, because this plugin itself contains calls to undocumented Mac APIs, which is not tolerated by Apple.

Fortunately an AIR application will work just fine without WebKit if it has no use of HTML rendering.

Use this command to remove WebKit plugin file from your app:
rm path/to/app/file/Contents/Frameworks/Adobe AIR.framework/Versions/Current/Resources/WebKit.dylib

You also can do that using GUI. Press CMD+Click (right mouse button) on the app-file and choose “Show Package Contents” in context menu item. Then navigate to the plugin file and remove it.

2. Set permissions to files inside of your application. By default when ATD builds your app-file it sets your current user as owner of all files inside of app it creates. This may prevent Application Loader from reading all data when uploading your app to the Mac App Store.

Just use chmod command to set necessary permissions (we used 777 that gives all permissions to read, write and execute) to all files inside of your app:

chmod -R 777 bundle.app/

3. Codesign inner Adobe bundles with your developer certificate. If you won’t do this, Apple will decline your application, because it contains unsigned nested bundles in it. Here are the commands to sign Adobe’s bundles:

codesign -f -v -s DEVELOPER_CERTIFICATE_NAME /path/to/bundle.app/Contents/Frameworks/Adobe\ AIR.framework/Versions/1.0/Resources/AdobeCP15.plugin

codesign -f -v -s DEVELOPER_CERTIFICATE_NAME /path/to/bundle.app/Contents/Frameworks/Adobe\ AIR.framework/Versions/1.0/Resources/Flash\ Player.plugin

codesign -f -v -s DEVELOPER_CERTIFICATE_NAME /path/to/bundle.app/Contents/Frameworks/Adobe\ AIR.framework/Versions/1.0/Resources/adobecp.plugin

codesign -f -v -s DEVELOPER_CERTIFICATE_NAME /path/to/bundle.app/Contents/Frameworks/Adobe\ AIR.framework/Versions/1.0

And now it’s finally time to sign our bundle itself:

codesign -f -v -s DEVELOPER_CERTIFICATE_NAME /path/to/bundle.app

The DEVELOPER_CERTIFICATE_NAME is the name of your Apple’s Developer Certificate (exactly as it seen in Key Chain utility).

It’s very handy to create .sh file and put these commands into it to avoid typing or copying them every time you need to sign your application.

Creating an installation package

Congrats if you made it this far! This is the final step in packing your app for Mac App Store – creating an installation package (PKG file). Installation package is created with productbuild utility, that also comes with Xcode 4.

An important note here is that you may find another utility for PKG creation called PackageMaker, but Apple’s application loader refuses to upload PKG-s created with PackageMaker on iTunes, thus you have to use productbuild for packaging.

During creation of a PKG installer you should sign it with your developer installer certificate using –sign parameter. Here is the command for this:

productbuild –component /path/to/bundle.app INSTALLATION_PATH /path/to/installer.pkg –sign INSTALLER_CERTIFICATE_NAME

INSTALLATION_PATH should usually be /Applications if you want your application to appear in Apps folder on dashboard after installation.

You can take a step further before uploading and verify your installer, but it will not work if you just double click and unpack it. To ensure your app is installed correctly, you can run this command on PKG file:

sudo installer -store -pkg /path/to/installer.pkg -target /

Output PKG file is actually the file you can upload to iTunes using Application loader (which also comes with Xcode).

And the last – but not least – thing worth of notion: to avoid a lot of troubles with application loader use a real Mac at least for PKG creating and uploading it to iTunes, not a hackintosh or a virtual machine (like we recklessly did for the first time).

That is pretty much the end of story. We hope, this guide will help you to get your awesome games to the Mac App Store!

You can follow any responses to this entry through the RSS 2.0 Both comments and pings are currently closed.

21 Responses

  • Mixmix says:

    Thanks for this great guide, would greatly appreciate a guide on the New Air 3.3 Beta http://labs.adobe.com/technologies/flashplatformruntimes/air3-3/ does it make the process any simpler?
    The Adobe site does not give any hint on what “Improved Mac App Store Support ” means.
    Do i need a Adobe Air certificate or is it enough with a “Self Signed” certificate?

    • Paul Vasiliev says:

      We haven’t had an opportunity to try air 3.3 yet so i can only assume that it probably fixes some issues with signing inner frameworks when publishing.
      As for certificate, for packaging air application itself it is enough to have self signed air certificate. What you have to gain is apple developers certificates wich are required to sign application (after air packaging) and its installer to send it to app store.

  • I’m not as skilled in AIR SDK and learned quite a bit of the process through this post. Also, how long of a process is it to get the apple developers certificate for your application?

    Glad to see the game on the MAC as well. I’ve been playing it a lot and have enjoyed it immensely.How much of a shift was it to design the game of iOS compared to the PC version?

    • Time to get certificate varies depending on you registering as individual or a company. In latter case Apple can ask you to provide some documents and even call you to clarify some details. We completed it in couple of weeks, but i think an individual can do this much faster.

      There is no iOS version of Coloropus actually. We only have some plans to do this in future. And yes, this will require a vast amount of efforts to make it a good game for mobile platforms. Some major changes in controls and gameplay mechanics are inevitable I think.

  • Pingback: Coloropus in Flash goes Mac App Store — FlashRealtime.com

  • Thanks for the smooth guide. Btw new Adobe did great job with air sdk. 3.2 brings Stage3d to mobiles and 3.3 brings usb debug for i-devices. It was painful to debug i-apps via network (build app, upload to device, and only then debug). I this good trend for flash developers.

  • Really good walk trough the whole procedure :) Great work guys. I found everything by myself a bit earlier before the post appear. I confirm that all the steps here are really true and if everyone follows this guide he should be able to publish an app in the store.

  • Jack Zhang says:

    I found the app file of package is large there are have 58M.

  • Pingback: Titan

  • Mixmix says:

    I downloaded a Flash Professional CS6 yesterday, and used the “Mac Installer” in the Air publish settings. A .Dmg was created, with a .app inside. How do we go from there? Any new easy methods that can be used in codesigning, and packaging process?

    • 3eka says:

      We haven’t used Flash CS6 yet so have no idea whether it supports direct app signing or not.
      I think you should check if it has option to configure/load Apple’s signing certificates. And if it doesn’t you will have to unpack .APP from .DMG (simply mount .DMG and drag .APP anywhere you like) and use signing process described in this walkthrough.
      Good luck!

  • Thanks very nice blog!

  • Jack Zhang says:

    That guide no longer works since Apple now require the applications to run in a special sandbox mode.

  • harsh says:

    Guys..still searching for an updated guide which will allows the app to run in sandbox mode as required by Apple. Does anyone have any pointers?

  • Kéven Boily says:

    I finally found out how to achieved this and I posted instructions oh how to enable sandboxing for Air apps bundled with Air 3.3 and later on Adobe Forums : http://forums.adobe.com/message/4564789#4564789

  • Flex says:

    I get this error: object file format unrecognized, invalid, or unsuitable

    When try to run the codesign (for example this one: codesign -f -v -s DEVELOPER_CERTIFICATE_NAME /path/to/bundle.app/Contents/Frameworks/Adobe\ AIR.framework/Versions/1.0/Resources/AdobeCP15.plugin)

    I’m using Flash Builder 4.6 (for Flex) to build my app file with capitva runtime and not adt.

  • hovitya says:

    Nice walkthrough. Everything works fine, but when I m trying upload my app file using the application loader i’ve get this error message: “Contents/Frameworks/Adobe Air.framework/Versions/1.0 Payload not declared in PackageInfo.” I’ve tried everything, but it still don’t work. It seems like Application Loader is seeing symlinks in the framework directory (like Current) as a bundle and tries to load the Info.plist multiple times. If I delete symlinks Application Loader accepts the app file, but the app won’t run. Has anyone experienced this before? I am using snow leopard and Application Loader 2.5.