Last year I built an internal application for our local office that manages employee’s days off. I chose to use AIR/Flex for the client and PHP/MySQL on the server. Soon after the first release I ran into a big problem: as bugs were fixed and new features were implemented I would send email notifications to all users to update the application (many of these changes broke compatibility and thus without the update the user wasn’t able to use the application anymore). So you can imagine that after several notifications both my client (the HR manager) and some of the users were quite loud in their complaints. The client even suggested that it might be a better idea to redeploy the application as a web-based one.
This was indeed a problem. How can you push your updates for an AIR application as simply and non intrusively as you do with web-based applications?
Yesterday, as part of the Adobe AIR 1.1 release, the Update Framework was launched. It is still in beta but I think it is OK to use it in production (I have been using it for some time and I didn’t have problems).
How to use the Adobe AIR Update Framework
It is not hard at all to use the Update Framework. The simplest approach has three main steps:
- Add the update library SWC file to your application
- Create and add the updater descriptor file – this is small XML file that keeps information needed by the updater (for example, what version is available, from where to take it and what info to display)
- Write about 10-15 lines of code in your AIR application … and you are done!
How does it work? Once you have integrated the Update Framework library into your application, whenever the application is started it checks if a new version is available. If a new version is available it can start to download the update (either automatically or after you show the user a window that displays some info about what improvements were made etc and ask the user to approve the update). After the update is downloaded, it is installed and the application is restarted.
Let’s create a simple Flex/AIR application to see how you can use it. (You can download the exported project here; in the archive you will find a readme.txt that explains how to import and set up the project).
For my example, I used Flex Builder 3. We need an AIR Flex project (I’ve called it air_updater). Then we need to add to the “libs” folder of the project the Update Framework library file: applicationupdater_ui.swc (you should find this file inside of the downloaded framework).
The next step is to create the updater descriptor file. This file lets you define the URL from where to download the new version of the application, and to set the version number, to set the description text you want to display to the user. Mine looks like this:
You need to place this file on your web server. On my machine this file is reachable using this URL: http://localhost/updater/update.xml. In the same folder you place the release build of the application (or you can change the URL to the AIR app in the XML file if you want to have the file in another place ).
Now it is time to move to the aplication file and write some ActionScript code. So open the application file air_updater.mxml and add a handler called checkUpdate for the event creationComplete of the WindowedApplication:
checkUpdate will be called every time the application is loaded. Next we need to write a little bit of ActionScript code to wire things together.
First thing, add a mx:script tag and create a variable appUpdater which will keep a reference to the updater object (this object will be our interface to the framework update). Next create the function checkUpdate(). This function will be in charge of initializing and setting some values needed by the updater object; the updateURL property tells the updater how to find the updater descriptor file (the file we have created earlier); then we register two functions for the error event and initialized event; the isCheckForUpdateVisible property lets you decide if you want to give the user the option to choose if he wants to allow the updater to check for a new version. In our case, set it to false, skipping this dialog in order to check for a new version every time. The last line appUpdater.initialize() does exactly what the name implies. When the updater is initialized it calls the listeners you have registered for the initialize event and inside of these listeners you start the process of checking for a new version.
The next two functions are the implementations for the event listeners for error and initialize events. Inside of the onUpdate() function we call the method checkNow() on the updater, starting the update process.
The last function setApplicationVersion() just read the current version of the app and displays it using a label.
And last let’s add a label component to display the current version of the application:
We have now all the code in place but we haven’t finished, yet. It is very important not to forget this: in order for the update to work you need to carefully set the same version number in these files: updater descriptor file and application descriptor (in our case air_updater-app.xml). In both these files you will find a tag version and what you put here needs to be exactly the same.
Important: be very careful what convention you use for the version string. The framework compares the version string of the installed application with the one from the server. If the installed version is “greater” than the one from the server the application will not be updated. Here are some examples that you could use:
- v1.0, v1.1, v1.2
- 1.0, 1.1,2
However if you use something like 1.0 and later you decide to switch to something like v3.5 it might not work.
Now it is time to test what we have done. Choose Export > Flex Project > Release Build. Install the AIR application and then go back to Flex Builder and change the version number from each file (as I explained above) and also you can add a button to see that it is working. Then export the app again using the Release Build and place it on your server in the same folder as the updater.xml file. The next time you open the installed AIR app you should see a screen like this:
If you click on the “Download now” option you will see the following screen:
My friend Remus posted an article about Update Framework, but use it with an HTML AIR application:
Later Update 2:
I post here the Error codes from the documentation:
16800 Occurs during validating the downloaded update file. The subErrorID may contain additional information.
16801 Invalid Adobe AIR file (missing application.xml).
16802 Invalid Adobe AIR file (missing mimetype).
16807 Invalid Adobe AIR file (format).
16804 Invalid Adobe AIR file(invalid flags).
16805 Invalid Adobe AIR file(unknown compression).
16806 Invalid Adobe AIR file (invalid filename).
16807 Invalid Adobe AIR file (corrupt).
16808 Configuration file does not exist.
16809 updateURL not set.
16811 Invalid configuration file(unknown configuration version).
16812 Invalid configuration file (URL missing).
16813 Invalid configuration file (delay format).
16814 Invalid configuration file (invalid defaultUI values).
16815 Invalid update descriptor (unknown descriptor version).
16816 Invalid update descriptor (missing update version).
16817 Invalid update descriptor (invalid description).
16818 IO error while saving data to disk. subErrorID may provide more information.
16819 Security error while downloading. subErrorID may provide more information.
16820 Invalid HTTP status code. subErrorID may contain the invalid status code.
16822 IO error while downloading. subErrorID may provide more information.
16823 EOF error while saving data to disk. subErrorID may provide more information.
16824 Invalid update descriptor. subErrorID may provide more information.
16825 The update file contains an application with a different application ID.
16826 The update file does not contain a newer version of the application.
16827 The version contained in the update file does not match the version from the update descriptor.
16828 Cannot update application, usually because the application is running in the AIR Debug Launcher (ADL).
16829 Missing update file at install time.