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

August 16, 2008 | By

UPDATED 08/27/2010:
We just released Adobe AIR Launchpad, a new desktop tool that helps Adobe Flex developers get started building desktop applications deployed on Adobe AIR. Auto-update is an included feature, so you can use Launchpad to generate your auto-update code.

Native Installers now can have auto-update!: If you need to add auto-update to your AIR 2 application that uses a native installer, Piotr Walczyszyn created a solution! Piotr blogged about it at http://www.riaspace.com/2010/08/nativeapplicationupdater-updater-for-air-apps-packaged-with-native-installers/

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 folderUPDATE: 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 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 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

Filed in: Adobe AIR, Adobe Flex | Tags: , , , , , , ,

About the Author (Author Profile)

Greg is a developer advocate for the Google Cloud Platform based in San Francisco, California

Comments (87)

  1. .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.

  2. 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

  3. Great job! Thanks for this post.

  4. 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 ****

  5. Paul,

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

    :)

  6. Mike Bernstein

    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

  7. Mike Bernstein

    Disregard my last post. I found out what I was doing wrong.

  8. Mark Fulton

    Does Adobe provide a way to ‘patch’ an Air application or do you need to do a full uninstall and reinstall on each update?

  9. 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.

  10. surendra

    Where is the source code to UpdateSample.air and the update.xml

  11. surendra

    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???????????

  12. Jigar Kapadia

    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]

  13. 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…

  14. Dan

    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

  15. win

    hi….the solution is great!!!
    but where is the code??

  16. franz

    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?

  17. Is it possible to auto-update the application in the background without prompting the user? Thanks for the article, quite helpful.

  18. Mohamed Barakat

    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,

    • 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

  19. greg

    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.

  20. devesh

    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.

    • Brian Scardina

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

  21. Jim

    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.

  22. Meldown

    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

  23. sean2078

    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.

  24. istrasci

    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

      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?

  25. anton@adobe

    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.

  26. Pino

    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?

  27. I just updated this post to be AIR 1.5 compatible. I also included links to the Flex project, etc…. Greg

  28. Peter Andreas Molgaard

    Hi Greg, thanks for the heads up and for updating to reflect the most recent changes to AIR, its really useful.

    Cheers,
    Peter

  29. 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.

  30. This application overwrite all new application to user machine.If application has less continents then it remove contents that are not in newer version. Is any way that we can update contents that may be less data in application and not remove data that is already exist in the current application.

  31. You should be using the File.applicationStorageDirectory for files that you don’t want to be overwritten on updates.

    You can read more at http://help.adobe.com/en_US/AIR/1.5/devappshtml/WS5b3ccc516d4fbf351e63e3d118666ade46-7fe4.html

    …and http://www.flexer.info/2008/05/08/air-applications-file-and-directory/

    You should never store user data in the install directory (File.applicationDirectory) because it can be overwritten when they install the next version. Handling user data in the applicationstorage directory keeps it separate.

    I hope this helps!

    Greg

  32. Rob

    Good day everyone,

    I’m pretty stuck on a problem I have been tackling with the auto update for days!!! Its probably a easy fix though it is evading me.

    I have written the update code as shown above, though when I run my application the update screen appears as a blank window. I am building my project in Flex Builder 3, with the Flex 3.5 SDK installed. When I debug the application, at the following line:

    appUpdater.initialize(); // Initialize the update framework

    I get a source not found error. Does anyone have any ideas?

    Any help most appricaited, regards

    Rob

  33. Dante

    Hi Rob, I have the same problem. Today I updated to the last build (3.5) and I got the blank window. If I compile with the 3.4 SDK then I get the right result.

    Maybe it could be a 3.5 SDK bug.

  34. Ryan Knight

    I confirmed it is really busted in Flex SDK 3.5! I filed a bug with adobe if everyone could vote on it for a quick resolve!

    http://bugs.adobe.com/jira/browse/SDK-24919

  35. This just in from engineering: (see http://bugs.adobe.com/jira/browse/SDK-24766)

    [01/07/10 09:57 AM ] Two separate concepts of visibility are involved here – the Native Window visibility, which is managed through the OS, and the Flash visibility, which is the visibility of DisplayObject. Pre 3.5 Flex SDKs used to treat the visible property on WindowedApplication directly as the NativeWindow visible property. Flex SDK 3.5 changed this functionality to affect both the NativeWindow visible property and the DisplayObject visible property.

    In ApplicationUpdaterUI, the visible property of the WindowedApplication was set to false at initialization. After that, all visibility manipulations were made directly on the NativeWindow. This showed the window, but left the DisplayObject within in a hidden state.

    This was changed, and now visibility is controlled directly through the visible property of the WindowedApplication.

    The bug will be fixed in the AIR 2 SDK, as well as in the AIR 1.5.3 SDK that will be delivered with Flex 4.

    It is not fixed in the current AIR 1.5.3.

  36. Ethan Chee

    I’m developing a AIR Application Online game where i have 1 Game Lobby AIR App (Flex-Based AIR) and games AIR App (Flash CS4 Built Swf, Create AIR file using Flex to load the Swf file).

    The game have only 1 Lobby(air file) and Numbers of games (air files).
    Purpose to having multiple AIR file to make use of AIR auto updates features for the lobby and all games.

    I want to remove/unchecked “Add shortcut icon to my desktop” from the Installation Preferences of AIR Application Install dialogue.

    May i know how to do remove/unchecked “Add shortcut icon to my desktop” feature?

  37. Flex

    Hi 4 all , I am developing the Xml editor based on Text layout Framework and I try to import this library and used it in my application but this I had have many errors i fixed all but now the application can not loaded and to see the application .. nevertheless I use AIR and flex 3 with SDK 3.2 and I have this waring
    Design mode: Cannot load applicationupdater_ui.swc ….
    anyone who has an idea to fix that and to make the application loaded ,,,,

  38. Christophe

    I am using flex3.5 and encountered the “non-visible Update window” as well (SDK-24766). The bug and its duplicates have been closed, I suppose they won’t fix it in this release ? What a sloppy support!

  39. Christophe

    Adobe has fixed the SDK-24766 bug in a follow-up release:
    Flex 3.5a
    http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+3

  40. Pappu

    Hi Guys,

    I have a flex air application which I build it in my desktop and port it to the clients with a CD/DVD.

    I have tried building a sample air application and with two versions with customUpdateUI=true in my application XML file.

    With this when I install version1 it gets installed normally.

    When the user wants to update his version to version2 he has to manually copy the air file to the desktop from the CD.Since I have been using below code:

    public function updateVersion(updatedVersionName:String,updatedVersionAir:String):void{
    var updater:Updater = new Updater();
    var airFile:File = File.desktopDirectory.resolvePath(updatedVersionAir);
    var version:String = updatedVersionName;
    updater.update(airFile, version);
    }

    When he runs the air file from the desktop it first opens the version1 UI and there he has to click the update link there which calls the above function to update his version.

    Is there no other better way to manage this scenario.All the examples I see in the internet are downloading from remote server but my case is that the client doesn’t have internet access.

    Thanks in advance.
    pappu.

  41. Brijesh

    Hi
    I have use this approach. My air file is inside WEB-INF folder of my application (Java-application) under Jboss server. I didnot give a path of air file because it is inside WEB-INF directory(server directory) such that i have created a servlet and I give the path of servlet inside update.xml file. The update.xml file is outside of WEB-INF folder such that i am able to give update.xml file path inside flex code. But my application is not getting auto update feature. How can i solve this.
    Thanks
    Brijesh

  42. It’s all working for me with my app, but when I try to update I get this error:
    There was an error downloading the update. Error# 16822
    Note that the app has already become visible and this is on top of that. My updater code is in the creationcomplete event of the air app’s mxml.

    Thanks

    • Same digital cert on both old and new versions?
      update.xml is perfect?
      Does the version in the update.xml match the string EXACTLY in the app config xml of the new app?

      It sounds like you are close since the update window is appearing.

      Greg

      • Peter

        I have the same problem, with my native air2 app using this framework:

        “There was an error downloading the update. Error# 16822″

        my update.xml:
        ………………………………………………

        0.0.3
        path to my airfile.air

        Can’t fix it. please help!

        Peter

    • Just Got The Solution for Error 16811 & 16816

      Note Following things to avoide update error
      No 1.>
      You xml schema for update descriptor.xml in server should look similar to this

      2.0
      http://localhost/SerialHunter/SerialHunter.air

      Note xmlns=”http://ns.adobe.com/air/framework/update/description/2.5″
      and versionNumber instead of version

      Also make similar changes in appxml version field (in Burrito its by default versionNumber )

      No 2>
      if u are using code to display veesion number make sure it should look like:

      var appXML:XML = NativeApplication.nativeApplication.applicationDescriptor;
      var ns:Namespace = appXML.namespace();

      pnlMain.title=appXML.ns::name+” v “+appXML.ns::versionNumber

      Thats it…!

      Rajendra Khope

      bkrajendra at gmail dot com

  43. ahsan

    i want to know that how i can manage to install the new version over old version.without uninstalling the old version.

  44. Nuwan

    Thanks my friend,
    this was really helpful,
    Keep up the good work!

  45. jase21

    I get the error source not found with Flex 4 also.

  46. Bobthetomato

    Awesome. Just what I was looking for. You rock!

  47. Peter

    Found an helpful Comment about updating native air2 apps:

    http://blogs.adobe.com/simplicity/2010/01/application_update_security_an.html

    Sounds that this will not work for native air2 Apps!

  48. Thanks alot for this post.
    Added it to my application and it works superbly.

  49. Thank you for your work on this. It has been very useful. I have a few questions regarding auto update:
    1. How to you listen for Download Later Button clicked?
    2. How to you listen for Cancel Button clicked during download?
    3. How to you listen for Close Button clicked after Download failed?
    4. How to you listen for Postpone Until Restart button clicked?

    Download Later or Cancel during Download, or Download failed close buton

  50. エロ電話できちゃうライブチャット http://www.erotelephone.com 完全無料で素人とエロ電話が楽しめる エロ電話

  51. Eric

    Can i use auto update over a network without an http address (ie: L:directory/directory)?
    The app I am building is just for fellow employees. I would like to put the it on a network drive and have it update from there. We do not have a website server on which to store it.
    I was trying to test it on my local C drive in a different directory, but it didn’t seem to work.

  52. Eric

    AutoUpdate.as
    appUpdater.updateURL = "file://C/Users/Eric/Documents/My Projects/ProjectName/air/update.xml";

    update.xml
    file://C/Users/Eric/Documents/My Projects/ProjectName/air/Project.air

    This is the error I recieved:
    “There was an error checking for updates. Error# 16822″

  53. In the code posted, the memory will never be released. Just keep in mind always to remove event listeners and dispose objects.

  54. Daniel

    Hi,

    First, thank you very much for your time. In my case, this code works fine for my flash application, except for one thing:

    When I click the mouse anywhere out of the stage, the animation almost freezes. It seems as if the framerate would descend to 0.01 FPS, something like that.

    Any idea?

    Thanks!

  55. THANKS DUDE! :) YOU ROCK!

  56. hector_indi

    hey man nice post!!
    i got an error of 16822!!
    LocalApp-0.1.1909.air is my apps name on dictionary and 0.1.1909 is the version no same on the descriptor and the app’s descriptor file.
    earlier it was like LocalApp.air nut i changed it after ur blog!, didn’t help anyways!!
    can u show me the way i really out of clue here.

  57. AS4More

    Hmmm… interesting I also noted this…
    var updater = new air.Updater();
    var airFile = air.File.applicationStore.resolvePath(“Example Application.air”);
    var version = “2.01”;
    updater.update(airFile, version);
    unfortunately everybody now needs a method for Mobile AIR apps and iPhone exported IPAs, etc.
    Link to the store? or 50 of them or your site or what exactly is best practice now.
    None of these solutions seem available anymore. AIR 2.5? or CS Flash Builder 4.5 burrito? aka Flex 4.5.1 SDK?

  58. Jason

    Thank you for the post!
    I have a great problem with the updater: my application opens the updater pop-up but it crashes immediatly. The application works correctly but the update wasn’t installed.
    I’m using Flex 3.0.2.214193 and Adobe Air 3.0.4080.

  59. Olsen

    Hey there, does it work for sdk 4.6?