Users can install or update an AIR application by double-clicking an AIR file on their computer or from the browser (using the seamless install feature), and the Adobe® AIR™ installer application manages the installation, alerting the user if they are updating an already existing application. (See Distributing, Installing, and Running AIR applications.)

However, you can also have an installed application update itself to a new version, using the Updater class. (An installed application may detect that a new version is available to be downloaded and installed.) The Updater class includes an update() method that lets you point to an AIR file on the user's computer and update to that version.

Contents

• About updating applications
• Presenting a custom application update user interface
• Downloading an AIR file to the user's computer
• Checking to see if an application is running for the first time

About updating applications

The Updater class (in the flash.desktop package) includes one method, update(), which you can use to update the currently running application with a different version. For example, if the user has a version of the AIR file ("Sample_App_v2.air") located on the desktop, the following code updates the application:

var updater:Updater = new Updater();
var airFile:File = File.desktopDirectory.resolvePath("Sample_App_v2.air");
var version:String = "2.01";
updater.update(airFile, version);

Prior to using the Updater class, the user or the application must download the updated version of the AIR file to the computer. For more information, see Downloading an AIR file to the user's computer.

Results of the method call

When an application in the runtime calls the update() method, the runtime closes the application, and it then attempts to install the new version from the AIR file. The runtime checks that the application ID and publisher ID specified in the AIR file matches the application ID and publisher ID for the application calling the update() method. (For information on the application ID and publisher ID, see Setting AIR application properties.) It also checks that the version string matches the version string passed to the update() method. If installation completes successfully, the runtime opens the new version of the application. Otherwise (if the installation cannot complete), it reopens the existing (pre-install) version of the application.

On Mac OS, to install an updated version of an application, the user must have adequate system privileges to install to the application directory. On Windows, a user must have administrative privileges.

If the updated version of the application requires an updated version of the runtime, the new runtime version is installed. To update the runtime, a user must have administrative privileges for the computer.

When testing an application using ADL, calling the update() method results in a runtime exception.

About the version string

The string that is specified as the version parameter of the update() method must match the string in the version attribute of the main application element of the application descriptor file for the AIR file to be installed. Specifying the version parameter is required for security reasons. By requiring the application to verify the version number in the AIR file, the application will not inadvertently install an older version, which might contain a security vulnerability that has been fixed in the currently installed application. The application should also check the version string in the AIR file with version string in the installed application to prevent downgrade attacks.

The version string can be of any format. For instance, it can be "2.01" or "version 2". The format of this string is left for you, the application developer, to decide. The runtime does not validate the version string; the application code should do this before updating the application.

If an Adobe AIR application downloads an AIR file via the web, it is a good practice to have a mechanism by which the web service can notify the Adobe AIR application of the version being downloaded. The application can then use this string as the version parameter of the update() method. If the AIR file is obtained by some other means, in which the version of the AIR file is unknown, the AIR application can examine the AIR file to determine the version information. (An AIR file is a ZIP-compressed archive, and the application descriptor file is the second record in the archive.)

For details on the application descriptor file, see Setting AIR application properties.

Presenting a custom application update user interface

AIR includes a default update interface:

This interface is always used the first time a user installs a version of an application on a machine. However, you can define your own interface to use for subsequent instances. To do this, specify a customUpdateUI element in the application descriptor file for the currently installed application:

<customUpdateUI>true</customUpdateUI>

When the application is installed and the user opens an AIR file with an application ID and a publisher ID that match the installed application, the runtime opens the application, rather than the default AIR application installer. For more information, see Providing a custom user interface for application updates.

The application can decide, when it is invoked (when the NativeApplication.nativeApplication object dispatches an invoke event), whether to update the application (using the Updater class). If it decides to update, it can present its own installation interface (which differs from its standard running interface) to the user.

Downloading an AIR file to the user's computer

To use the Updater class, the user or the application must first save an AIR file locally to the user's computer. For example, the following code reads an AIR file from a URL (http://example.com/air/updates/Sample_App_v2.air) and saves the AIR file to the application storage directory:

var urlString:String = "http://example.com/air/updates/Sample_App_v2.air";
var urlReq:URLRequest = new URLRequest(urlString);
var urlStream:URLStream = new URLStream();
var fileData:ByteArray = new ByteArray();
urlStream.addEventListener(Event.COMPLETE, loaded);
urlStream.load(urlReq);

function loaded(event:Event):void {
    urlStream.readBytes(fileData, 0, urlStream.bytesAvailable);
    writeAirFile();
}

function writeAirFile():void {
    var file:File = File.applicationStorageDirectory.resolvePath("My App v2.air");
    var fileStream:FileStream = new FileStream();
    fileStream.open(file, FileMode.WRITE);
    fileStream.writeBytes(fileData, 0, fileData.length);
    fileStream.close();
    trace("The AIR file is written.");
}

For more information, see Workflow for reading and writing files.

Checking to see if an application is running for the first time

Once you have updated an application you may want to provide the user with a "getting started" or "welcome" message. Upon launching, the application checks to see if it is running for the first time, so that it can determine whether to display the message.

One way to do this is to save a file to the application store directory upon initializing the application. Every time the application starts up, it should check for the existence of that file. If the file does not exist, then the application is running for the first time for the current user. If the file exists, the application has already run at least once. If the file exists and contains a version number older than the current version number, then you know the user is running the new version for the first time.

Here is a Flex example:

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" 
    layout="vertical" 
    title="Sample Version Checker Application"
    applicationComplete="init()">
    <mx:Script>
        <![CDATA[
            import flash.filesystem.*;
            public var file:File;
            public var currentVersion:String = "1.2";
            public function init():void {
                file = File.applicationStorageDirectory;
                file = file.resolvePath("Preferences/version.txt");
                trace(file.nativePath);
                if(file.exists) {
                    checkVersion();
                } else {
                    firstRun();
                }
            }
            private function checkVersion():void {
                var stream:FileStream = new FileStream();
                stream.open(file, FileMode.READ);
                var prevVersion:String = stream.readUTFBytes(stream.bytesAvailable);
                stream.close();
                if (prevVersion != currentVersion) {
                    log.text = "You have updated to version " + currentVersion + ".\n";
                } else {
                    saveFile();
                }
                log.text += "Welcome to the application.";
            }
            private function firstRun():void {
                log.text = "Thank you for installing the application. \n"
                    + "This is the first time you have run it.";
                saveFile();
            }
            private function saveFile():void {
                var stream:FileStream = new FileStream();
                stream.open(file, FileMode.WRITE);
                stream.writeUTFBytes(currentVersion);
                stream.close();
            }
        ]]>
    </mx:Script>
    <mx:TextArea id="log" width="100%" height="100%" />
</mx:WindowedApplication>

If your application saves data locally (such as, in the application storage directory), you may want to check for any previously saved data (from previous versions) upon first run.