Adding auto update features to your AIR application in 3 easy steps

UPDATED 10/14/2009:

Most modern desktop applications, browser plugins, OS’s, etc. automatically check for updates periodically, and some of them even handle the update process with a single click so it’s easy to stay current. When building AIR applications, it’s also important to provide a good auto-update feature.

During the past several weeks, I’ve been managing a project to build an internal AIR application. I wrote the original requirements document but forgot to include a simple bullet about auto-updating. A few days ago, I was handed the source code and other assets and quickly realized my oversight.

Thankfully, adding this capability is dramatically simplified by the Adobe AIR Update Framework that appeared on Adobe labs a few months ago. There have been several blog articles about the new framework but I thought I would provide a very simple example of the most common update model.

You can download the Flex project from here.

The code below checks to see if a new update is available every time the program is run. If an update is available, it simply prompts the user to install the new update with the following default UI:

I implemented this using the following 3 steps:

I downloaded the AIR update framework from http://labs.adobe.com/wiki/index.php/Adobe_AIR_Update_Framework and copied the included applicationupdater_ui.swc to my project’s lib folder – UPDATE: This step is no longer required – the auto-update framework is included in AIR 1.5. I guess it’s now only 2 easy steps!
I created a file called update.xml (see tab 3 below) and uploaded it to the server where my .air file lives. This file identifies the currently available version, the location of the .air file and provides the description shown above as “release notes”.
I added code to my existing init() method to initialize the updater. Once initialized, I triggered an immediate update check via a one-liner event handler.

Every time my application runs, it performs a quick check to see if the version number in the update.xml on my server is different than the version number in my app config file (AIRAutoUpdateSample-app.xml). If it’s the same, the user sees nothing. If it is different, the dialog above displays. The update framework takes care of the dialog, downloading the new air installer and the installation of the new version. If there is no connection to the server, it silently continues running the existing version of the application.

There are many other options included in the framework, including the ability to have the update check occur every n days. For more details, see the included documentation and the included samples.

Try out the results

To demonstrate this capability for this blog post, I created a tiny AIR program. Download AIRAutoUpdateSample-v1.air and install it. It simply displays a small window with the current version number displayed. When you run it, it will immediately tell you that v2 is available and prompt you to install it so you can see the end-user experience.

UPDATE 11/26/2008 – http://gregsramblings.com/2008/11/26/adobe-air-update-framework-for-html-ajax-and-flash-applications/

Source Code

Below is the source code to AIRAutoUpdateSample.air and the update.xml that resides on the server:

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" width="200" height="70" creationComplete="checkForUpdate()">
    <mx:Script>
    <![CDATA[
        import flash.events.ErrorEvent;
        import air.update.ApplicationUpdaterUI;
        import air.update.events.UpdateEvent;
        import mx.controls.Alert;

        private var appUpdater:ApplicationUpdaterUI = new ApplicationUpdaterUI();

        private function checkForUpdate():void {
            setApplicationVersion(); // Find the current version so we can show it below
            appUpdater.updateURL = "http://tourdeflex.adobe.com/blogfiles/AIRAutoUpdateSample/server/update.xml"; // Server-side XML file describing update
            appUpdater.isCheckForUpdateVisible = false; // We won't ask permission to check for an update
            appUpdater.addEventListener(UpdateEvent.INITIALIZED, onUpdate); // Once initialized, run onUpdate
            appUpdater.addEventListener(ErrorEvent.ERROR, onError); // If something goes wrong, run onError
            appUpdater.initialize(); // Initialize the update framework
        }

        private function onError(event:ErrorEvent):void {
            Alert.show(event.toString());
        }

        private function onUpdate(event:UpdateEvent):void {
            appUpdater.checkNow(); // Go check for an update now
        }

        // Find the current version for our Label below
        private function setApplicationVersion():void {
            var appXML:XML = NativeApplication.nativeApplication.applicationDescriptor;
            var ns:Namespace = appXML.namespace();
            ver.text = "Current version is " + appXML.ns::version;
        }
    ]]>
    </mx:Script>

    <mx:VBox backgroundColor="blue" x="0" y="0" width="100%" height="100%">
        <mx:Label color="white" id="ver" />
    </mx:VBox>

</mx:WindowedApplication>

The following update.xml file is on the server.

<?xml version="1.0" encoding="utf-8"?>
<update xmlns="http://ns.adobe.com/air/framework/update/description/1.0">
<version>v2</version>
<url>http://tourdeflex.adobe.com/blogfiles/AIRAutoUpdateSample/server/AIRAutoUpdateSample-v2.air</url>
<description><![CDATA[
v2
 * These notes are displayed to the user in the update dialog
 * Typically, this is used to summarize what's new in the release
]]></description>
</update>

Here are some common mistakes that developers make with the auto-update code:

You run v1 and nothing happens – confirm that updateURL is pointing to the right place. Confirm that your update.xml is pointing to the correct AIR file. Confirm that the <version> attribute is set to something different than your last version.
You get a download error or install error – confirm that the version of the air app exactly matches the version specified in the <version> section of the update.xml. Also confirm that the app has the same cert. You cannot change certs via auto-update.

You can find this same sample and many other AIR-related samples in Tour de Flex.

NEW Related blog post: 10/16/2009 – Adobe AIR Auto-Update – How to force some updates and make others optional

~ by gregorywilson on August 16, 2008.

Posted in Adobe AIR
Tags: Adobe, Adobe AIR, Adobe AIR Update Framework, AIR, AIR Auto Update, AIR Update Framework

38 Responses to “Adding auto update features to your AIR application in 3 easy steps”

.swc files are nothing more then a nuisance of our industry.
Why is the dam frame work only for flex and not in raw AS3 source?
I decompiled the swf embedded in the swc file and seen no dependencies for flex, so why the strong arming to use flex.

This is bull shit. I have a AIR app that I made with flash and now if I want to get any time of auto update I have to go make my own framework to do so. Thanks a lot adobe.

some of sick of flex said this on August 17, 2008 at 12:14 pm | Reply
The docs do neglect to discuss using the framework from flash. However, it does provide examples of building an updater in HTML/JS so that’s another option for you. There are multiple examples of this included on the page.

The version on labs is a pre-release so it is not complete. Our intent is to provide a flash-friendly way of doing this…it’s mostly a packaging issue.

It is NOT our intent to ignore flash developers. AIR is a great way for Flash developers to build desktop apps (see http://www.adobe.com/products/air/develop/flash and http://www.adobe.com/devnet/air/flash/ and http://help.adobe.com/en_US/AIR/1.1/devappsflash/). The framework is intended for ALL developers deploying on AIR.

Thanks,

Greg

gregorywilson said this on August 18, 2008 at 9:21 am | Reply
Great job! Thanks for this post.

Aaron Hardy said this on October 9, 2008 at 1:08 pm | Reply
The compiler ses an error here:

private function setApplicationVersion():void {
var appXML:XML = NativeApplication.nativeApplication.applicationDescriptor;
var ns:Namespace = appXML.namespace();
ver.text = “Current version is ” + appXML.ns::version;
}

**** Access of undefined property ver ****

Paul said this on October 23, 2008 at 11:01 am | Reply
Paul,

“ver” is the name of the label at the bottom of the source. Add that label and it’ll work.

gregorywilson said this on October 26, 2008 at 9:49 pm | Reply
I tried running the code but I cannot get it to work. I do not get any error messages, it just doesn’t work. Is there anything else that needs to be done?

thanks

Mike Bernstein said this on October 28, 2008 at 12:41 pm | Reply
Disregard my last post. I found out what I was doing wrong.

Mike Bernstein said this on October 28, 2008 at 2:19 pm | Reply
[...] also on how to implement steps @ http://gregsramblings.com/2008/08/16/adding-auto-update-features-to-your-air-application-in-3-easy-s... [...]

Update framework for AIR applications | Adobe AIR Tutorials said this on October 30, 2008 at 5:46 am | Reply
Does Adobe provide a way to ‘patch’ an Air application or do you need to do a full uninstall and reinstall on each update?

Mark Fulton said this on November 10, 2008 at 4:53 pm | Reply
I keep getting the following error when I try to implement the updater code in Gumbo. Any ideas?

VerifyError: Error #1053: Illegal override of seek in mx.effects.effectClasses.TweenEffectInstance.

timT said this on December 1, 2008 at 10:26 pm | Reply
Where is the source code to UpdateSample.air and the update.xml

surendra said this on December 8, 2008 at 6:57 am | Reply
I was searching for source code to UpdateSample.air and the update.xml but i didn’t get in this page , plz tell me where is the source code to UpdateSample.air and the update.xml???????????

surendra said this on December 8, 2008 at 7:00 am | Reply
the Compiler shows error here:
The compiler ses an error here:
private function setApplicationVersion():void {
var appXML:XML = NativeApplication.nativeApplication.applicationDescriptor;
var ns:Namespace = appXML.namespace();
ver.text = “Current version is ” + appXML.ns::version;
}

The Error Message is:

TypeError: Error #1009: Cannot access a property or method of a null object reference.
at Test/setApplicationVersion()[C:\Users\Administrator.RSPLLAPTOP27\Documents\Flex Builder 3\Test\src\Test.mxml:48]
at Test/init()[C:\Users\Administrator.RSPLLAPTOP27\Documents\Flex Builder 3\Test\src\Test.mxml:24]
at Test/___Test_WindowedApplication1_creationComplete()[C:\Users\Administrator.RSPLLAPTOP27\Documents\Flex Builder 3\Test\src\Test.mxml:3]
at flash.events::EventDispatcher/dispatchEventFunction()
at flash.events::EventDispatcher/dispatchEvent()
at mx.core::UIComponent/dispatchEvent()[E:\dev\3.0.x\frameworks\projects\framework\src\mx\core\UIComponent.as:9051]
at mx.core::UIComponent/set initialized()[E:\dev\3.0.x\frameworks\projects\framework\src\mx\core\UIComponent.as:1167]
at mx.managers::LayoutManager/doPhasedInstantiation()[E:\dev\3.0.x\frameworks\projects\framework\src\mx\managers\LayoutManager.as:698]
at Function/http://adobe.com/AS3/2006/builtin::apply()
at mx.core::UIComponent/callLaterDispatcher2()[E:\dev\3.0.x\frameworks\projects\framework\src\mx\core\UIComponent.as:8460]
at mx.core::UIComponent/callLaterDispatcher()[E:\dev\3.0.x\frameworks\projects\framework\src\mx\core\UIComponent.as:8403]

Jigar Kapadia said this on January 8, 2009 at 1:47 am | Reply
Hi Greg. Finally after so many time trying to find an updater for Flash i came here. I was so damn happy to see the feature i was looking for and now i know i cant do this in Flash… All this Adobe thing looking to have everything to Flex and letting Flash so damn behind is getting me completly sick of Adobe. I can’t just ue the update, i need to do some thing in Flex + html + javscript just to have an updater that, in flex, i can do it in minutes.. err just my rant…

Mauro said this on January 26, 2009 at 3:45 pm | Reply
All- I also am getting the following error when I try to implement the updater code in Gumbo.
VerifyError: Error #1053: Illegal override of seek in mx.effects.effectClasses.TweenEffectInstance.

– Jiira seems to indcate this is fixed in a later build, has anyone tried that? my build 4.0.0.4021

Dan said this on February 5, 2009 at 9:11 am | Reply
-

Dan said this on February 5, 2009 at 9:11 am | Reply
hi….the solution is great!!!
but where is the code??

win said this on February 11, 2009 at 8:27 am | Reply
During the update process, I have a 5100 error.
I search for quite a long timem but didn’t find any answer…
Does anyone have one?

franz said this on March 26, 2009 at 9:48 pm | Reply
Is it possible to auto-update the application in the background without prompting the user? Thanks for the article, quite helpful.

Scott Selikoff said this on March 27, 2009 at 9:15 am | Reply
Hi thanks for sharing this nice work. but i have a question can i make a partial update. for example the client downloaded a complete air application (20MB), then i issued an update but i want only to update 1 image (25KB). using the normal update the client need to download the whole 20MB again. can i make a partial update true?

thanks,

Mohamed Barakat said this on April 15, 2009 at 7:19 am | Reply

Hey Mohamed. The update framework can’t do partial updates. However, it is possible to accomplish what you are asking by writing a little code. AIR applications cannot write to the actual application directory but it can write to the application storage directory (File.applicationStorageDirectory). So, when your application starts, copy any files that you want to update in the future to the File.applicationStorageDirectory. Then you can later update the file from your application.

The Tour De Flex application (http://www.adobe.com/devnet/flex/tourdeflex) does this with an XML file that contains the samples. Every time we update the sample database, the application downloads it and replaces the copy in the File.applicationStorageDirectory.

Does this help?

Thanks!

Greg

gregorywilson said this on April 18, 2009 at 9:04 am | Reply

Hey Greg. Care to share the source of the tour de flex updater code? I can’t tell you how many alternatives I’ve attempted using the ‘prescribed’ ways to build an air with external components loadable/updateable from a remote non-app domain source.

greg said this on April 26, 2009 at 7:37 pm | Reply
hi i have used the above code as it is. i am getting an error

Type was not found or was not a compile-time constant: UpdateEvent

please help me.

devesh said this on May 3, 2009 at 7:41 am | Reply

Make sure you copy applicationupdater_ui.swc to your project’s lib folder. Note applicationupdater_ui.swc is now included in the Flex SDK.

Brian Scardina said this on May 15, 2009 at 1:13 pm | Reply

How do you capture if the user cancels the download? I tried to listen to every event that is available but didn’t have any luck.

Jim said this on May 3, 2009 at 1:47 pm | Reply
When i try to auto update my Air application as user or power user, the update program get an error code “Error 0″.
The directory permissions are “full control” for everyone
Can you help me please?
tanks in advances

Meldown said this on May 7, 2009 at 10:11 am | Reply
Where is the code? No one can find it. This post is useless without it. Pls respond to the others who are also asking for the code being referenced. It does not display. TY.

sean2078 said this on May 20, 2009 at 12:09 pm | Reply

Code is now back in the post. Sorry about that!

Greg

gregorywilson said this on May 21, 2009 at 4:41 pm | Reply

I’ve followed this exactly, but it doesn’t work. The appUpdater.checkNow() (in onUpdate) is firing, but nothing seems to happen. Note that this -DOES- work for one of our other projects on the server. What am I doing wrong? Why isn’t checkNow() actually doing anything?

istrasci said this on June 23, 2009 at 11:47 am | Reply

I figured it out. In my *-app.xml, I　had a tag of 1.0, but on the server update.xml, I　had v1.1 (notice the ‘v’). So I changed my tag to v1.0 and it worked. I guess the versions have to be of the same “format”??? I figured if they were different at all, it would update, but it only worked when they were of the same “format”. Who knew?

istrasci said this on June 23, 2009 at 12:17 pm | Reply

With the release of AIR 1.5, the update framework was added to the SDK. We created the following quick start articles:

For Flex developers: http://www.adobe.com/devnet/air/flex/quickstart/update_framework.html

For Flash developers: http://www.adobe.com/devnet/air/flash/quickstart/update_framework.html

For HTML/Ajax developers: http://www.adobe.com/devnet/air/ajax/quickstart/update_framework.html

Hope you find them helpful.

anton@adobe said this on August 17, 2009 at 6:23 pm | Reply
works just fine tkx

Pedro Lopes said this on August 27, 2009 at 6:05 pm | Reply
One question: aside from the framework, is it possible to conditionally update a single client? Imagine, I installed 10 identical air apps on 10 different computers. Now: I create a new version number, say 0.3 and store that value in a db relating it to a client ID. The client with ID=id2 MUST download this upgrade, while the client with ID=id5 must not. Is this possible?

Pino said this on September 20, 2009 at 5:46 am | Reply
I just updated this post to be AIR 1.5 compatible. I also included links to the Flex project, etc…. Greg

gregorywilson said this on October 14, 2009 at 6:29 pm | Reply
Hi Greg, thanks for the heads up and for updating to reflect the most recent changes to AIR, its really useful.

Cheers,
Peter

Peter Andreas Molgaard said this on October 15, 2009 at 6:10 am | Reply
[...] Adobe AIR Auto-Update – How to force some updates and make others optional If you are looking for information on how to add auto-update capabilities to your Adobe AIR app, start with my earlier blog post, “Adding auto update features to your AIR application in 3 easy steps“. [...]

Adobe AIR Auto-Update – How to force some updates and make others optional « Greg Wilson’s Ramblings said this on October 16, 2009 at 7:59 am | Reply
[...] http://gregsramblings.com/2008/08/16/adding-auto-update-features-to-your-air-application-in-3-easy-s... カテゴリー: Air create/update application タグ: コメント (0) トラックバック (0) コメントをどうぞトラックバックURL [...]

やせ蛙まけるな一茶是にあり » Air create/update application said this on October 19, 2009 at 4:45 am | Reply
Thanks! I have been looking for a simple example for the past week – why can’t Adobe just include simple working flex examples within their API docs! I’ve read a shed load of convoluted samples… but I just need something simple.

Tony Norcross said this on October 19, 2009 at 5:51 am | Reply

Greg Wilson’s Ramblings