Updating AIR applications



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

Both the application ID and the publisher ID of an update AIR file must match the application to be updated. In AIR 1.5.3 or later, the publisher ID is optional and can be specified in the application descriptor file. In earlier versions of AIR, the publisher ID was derived from the signing certificate, which meant that both the update and the application to be updated had to be signed with the same certificate. When updating an application published before AIR 1.5.3 with an update created with AIR 1.5.3 or later, add the original publisher ID to the application descriptor file of the update. New applications do not need and should not specify a publisher ID.

As of AIR 1.1 and later, you can migrate an application to use a new code-signing certificate. Migrating an application to use a new signature involves signing the update AIR file with both the new and the original certificates. Certificate migration is a one-way process. After the migration, only AIR files signed with the new certificate (or with both certificates) will be recognized as updates to an existing installation.

Managing updates of applications can be complicated. AIR 1.5 includes the new update framework for AdobeAIR applications. This framework provides APIs to assist developers in providing good update capabilities in AIR applications.

You can use certificate migration any time you need to change from using one certificate to another — including changing to a renewed version of an existing certificate. If you do not migrate the certificate, existing users must remove their current version of your application before installing the new version. For more information see Changing certificates.

Note: In earlier versions of AIR, you could sometimes sign an application with a renewed certificate without using a migration signature. As of AIR 1.5.3, a migration signature is always required to change certificates — even for renewals.

It is a good practice to include an update mechanism in your application. If you create a new version the application, the update mechanism can prompt the user to install the new version.

Note: New versions of the Adobe AIR runtime may include updated versions of WebKit. An updated version of WebKit may result in unexpected changes in HTML content in a deployed AIR application. These changes may require you to update your application. An update mechanism can inform the user of the new version of the application. For more information, see About the HTML environment.

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);

Before an application uses 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 Updater.update() 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 and Linux, 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 example, 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 validate this string 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. If your application defines a custom update interface, 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 run (when the NativeApplication.nativeApplication object dispatches an load 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.

Note: AIR 1.5 includes an update framework, which assists developers in providing good update capabilities in AIR applications. Using this framework may be much easier than using the update() method of the Update class directly. For details, see Using the update framework.

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.

Note: AIR 1.5 includes an update framework, which assists developers in providing good update capabilities in AIR applications. This framework provides easy methods to check if a version of an application is running for the first time. For details, see Using the update framework.

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.

The following example demonstrates the concept:

<?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="system extension()"> 
    <mx:Script> 
        <![CDATA[ 
            import flash.filesystem.*; 
            public var file:File; 
            public var currentVersion:String = "1.2"; 
            public function system extension():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 reversion:String = stream.readUTFBytes(stream.bytesAvailable); 
                stream.close(); 
                if (reversion != 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.

Using the update framework

Managing updates of applications can be complicated. The update framework for AdobeAIR applications provides APIs to assist developers in providing good update capabilities in AIR applications. The functionality in the AIR update framework assists developers in the following:

  • Periodically checking for updates based on an interval or at the request of the user

  • Downloading AIR files (updates) from a web source

  • Alerting the user on the first run of the newly installed version

  • Confirming that the user wants to check for updates

  • Displaying information on the new update version to the user

  • Displaying download progress and error information to the user

The AIR update framework supplies a sample user interface that your application can use. It provides the user with basic information and options related to application updates. Your application can also define its own custom user interface for use with the update framework.

The AIR update framework lets you store information about the update version of an AIR application in simple XML configuration files. For most applications, setting up these configuration files and including some basic code provides good update functionality to the end user.

Even without using the update framework, Adobe AIR includes an Updater class that AIR applications can use to upgrade to new versions. This class lets an application upgrade to a version contained in an AIR file on the user’s computer. However, upgrade management can involve more than simply having the application update based on a locally stored AIR file.

Files in the AIR update framework

The AIR update framework includes the following directories:

  • doc—The documentation (which you are reading now) for the AIR update framework.

  • frameworks—This directory includes SWC files, for Flex development, and SWF files, for HTML development. For more information, see these sections (which follow immediately):

  • samples—This directory includes Flex- and HTML-based samples showing how to use the application update framework. Compile and test these files, as you would any AIR application.

  • templates—This directory contains sample update descriptor files (simple and localized) and configuration files. (See Setting up your Setting up your Flex development environment and Basic example: Using the ApplicationUpdaterUI version for more information on these files.)

Setting up your Flex development environment

The frameworks/flex directory of the update framework includes these files:

  • ApplicationUpdater.swc—Defines the basic functionality of the update library, without any user interface

  • ApplicationUpdater_UI.swc—Defines the basic functionality of the update library, including a user interface that your application can use to display update options

SWC files define classes that you can use in Flex development.

To use the update framework when compiling with the Flex SDK, include either the ApplicationUpdater.swc or ApplicationUpdater_UI.swc file in the call to the amxmlc compiler. In the following, example, the compiler loads the ApplicationUpdater.swc file in the lib subdirectory of the Flex SDK directory:

amxmlc -library-path+=lib/ApplicationUpdater.swc  -- myApp.mxml

The following example, the compiler loads the ApplicationUpdater_UI.swc file in the lib subdirectory of the Flex SDK directory:

amxmlc -library-path+=lib/ApplicationUpdater_UI.swc  -- myApp.mxml

When developing using Flex builder, add the SWC file in the Library Path tab of the Flex Build Path settings in the Properties dialog box.

Be sure to copy the SWC files to the directory that you will reference in the amxmlc compiler (using Flex SDK) or Flex Builder.

Including framework files in an HTML-based AIR application

The frameworks/html directory of the update framework includes these SWF files:

  • ApplicationUpdater.swf—Defines the basic functionality of the update library, without any user interface

  • ApplicationUpdater_UI.swf—Defines the basic functionality of the update library, including a user interface that your application can use to display update options

JavaScript code in AIR applications can use classes defined in SWF files.

To use the update framework, include either the ApplicationUpdater.swf or ApplicationUpdater_UI.swf file in your application directory (or a subdirectory). Then, in the HTML file that will use the framework (in JavaScript code), include a script tag that loads the file:

<script src="applicationUpdater.swf" type="application/x-shockwave-flash"/>

Or use this script tag to load the ApplicationUpdater_UI.swf file:

<script src="ApplicationUpdater_UI.swf" type="application/x-shockwave-flash"/>

The API defined in these two files is described in the remainder of this document.

Basic example: Using the ApplicationUpdaterUI version

The ApplicationUpdaterUI version of the update framework provides a basic interface that you can easily use in your application. The following is a basic example.

First, create an AIR application that calls the update framework:

  1. If your application is an HTML-based AIR application, load the ApplicationUpdaterUI.js file:

    <script src="ApplicationUpdater_UI.swf" type="application/x-shockwave-flash"/>
  2. In your AIR application program logic, instantiate an ApplicationUpdaterUI object.

    In ActionScript, use the following code:

    var appUpdater:ApplicationUpdaterUI = new ApplicationUpdaterUI(); 

    In JavaScript, use the following code:

    var appUpdater = new runtime.air.update.ApplicationUpdaterUI(); 

    You may want to add this code in an initialization function that executes when the application has loaded.

  3. Create a text file named updateConfig.xml and add the following to it:

    <?xml version="1.0" encoding="utf-8"?> 
    <configuration xmlns="http://ns.adobe.com/air/framework/update/configuration/1.0"> 
         <url>http://example.com/updates/update.xml</url> 
        <delay>1</delay> 
    </configuration>

    Edit the URL element of the updateConfig.xml file to match the eventual location of the update descriptor file on your web server (see the next procedure).

    The delay is the number of days the application waits between checks for updates.

  4. Add the updateConfig.xml file to the project directory of your AIR application.

  5. Have the updater object reference the updateConfig.xml file, and call the object’s initialize() method.

    In ActionScript, use the following code:
    appUpdater.configurationFile = new File("app:/updateConfig.xml"); 
    appUpdater.initialize();
    In JavaScript, use the following code:
    appUpdater.configurationFile = new air.File("app:/updateConfig.xml"); 
    appUpdater.initialize();
  6. Create a second version of the AIR application that has a different version than the first application. (The version is specified in the application descriptor file, in the version element.)

Next, add the update version of the AIR application to your web server:

  1. Place the update version of the AIR file on your web server.

  2. Create a text file named updateDescriptor.xml, and add the following contents to it:

    <?xml version="1.0" encoding="utf-8"?> 
         <update xmlns="http://ns.adobe.com/air/framework/update/description/1.0"> 
           <version>1.1</version> 
           <url>http://example.com/updates/sample_1.1.air</url> 
           <description>This is the latest version of the Sample application.</description> 
        </update>

    Edit the version, URL, and description of the updateDescriptor.xml file to match your update AIR file.

  3. Add the updateDescriptor.xml file to the same web server directory that contains the update AIR file.

This is a basic example, but it provides update functionality that is sufficient for many applications. The remainder of this document describes how to use the update framework to best suit your needs.

For another example of using the update framework, see the following sample application at the Adobe AIR developer center: Update Framework in a Flex-based Application (http://www.adobe.com/go/learn_air_qs_update_framework_flex_en).

Defining the update descriptor file and adding the AIR file to your web server

When you use the AIR update framework, you define basic information about the available update in an update descriptor file, stored on your web server. The update descriptor file is a simple XML file. The update framework included in the application checks this file to see if a new version has been uploaded.

The update descriptor file contains the following data:

  • version—The new version of the air application. It must be the same string that is used in the new air application descriptor file as the version. If the version in the update descriptor file does not match the update AIR file’s version, the update framework will throw an exception.

  • url—The location of the update AIR file. This is the file that contains the update version of the AIR application.

  • description—Details regarding the new version. This information can be displayed to the user during the update process.

The version and url elements are mandatory. The description element is optional.

Here is a sample update descriptor file:

<?xml version="1.0" encoding="utf-8"?> 
     <update xmlns="http://ns.adobe.com/air/framework/update/description/1.0"> 
       <version>1.1a1</version> 
       <url>http://example.com/updates/sample_1.1a1.air</url> 
       <description>This is the latest version of the Sample application.</description> 
    </update>

If you want to define the description tag using multiple languages, use multiple text elements that define a lang attribute:

<?xml version="1.0" encoding="utf-8"?> 
     <update xmlns="http://ns.adobe.com/air/framework/update/description/1.0"> 
       <version>1.1a1</version> 
       <url>http://example.com/updates/sample_1.1a1.air</url> 
       <description> 
           <text xml:lang="en">English description</text> 
           <text xml:lang="fr">French description</text> 
           <text xml:lang="ro">Romanian description</text> 
       </description> 
    </update>

Place the update descriptor file, along with the update AIR file, on your web server.

The templates directory included with the update descriptor includes sample update descriptor files. These include both single-language and multi-language versions.

Instantiating an updater object

After loading the AIR update framework in your code (see Setting up your Flex development environment and Including framework files in an HTML-based AIR application), you need to instantiate an updater object, as in the following example:

var appUpdater:ApplicationUpdater = new ApplicationUpdater();

The previous code uses the ApplicationUpdater class (which provides no user interface). If you want to use the ApplicationUpdaterUI class (which provides a user interface), use the following:

var appUpdater:ApplicationUpdaterUI = new ApplicationUpdaterUI();

The remaining code samples in this document assume that you have instantiated an updater object named appUpdater.

Configuring the update settings

Both ApplicationUpdater and ApplicationUpdaterUI can be configured via a configuration file delivered with the application or via ActionScript or JavaScript in the application.

Defining update settings in an XML configuration file

The update configuration file is an XML file. It can contain the following elements:

  • updateURL— A String. Represents the location of the update descriptor on the remote server. Any valid URLRequest location is allowed. You must define the updateURL property, either via the configuration file or via script (see Defining the update descriptor file and adding the AIR file to your web server). You must define this property before using the updater (before calling the initialize() method of the updater object, described in Initializing the update framework).

  • delay—A Number. Represents an interval of time given in days (values like 0.25 are allowed) for checking for updates. A value of 0 (which is the default value) specifies that the updater does not perform an automatic periodical check.

The configuration file for the ApplicationUpdaterUI can contain the following element in addition to the updateURL and delay elements:

  • defaultUI: A list of dialog elements. Each dialog element has a name attribute that corresponds to dialog box in the user interface. Each dialog element has a visible attribute that defines whether the dialog box is visible. The default value is true. Possible values for the name attribute are the following:

    • "checkForUpdate"—Corresponding to the Check for Update, No Update, and Update Error dialog boxes

    • "downloadUpdate"—Corresponding to the Download Update dialog box

    • "downloadProgress"—Corresponding to Download Progress and Download Error dialog boxes

    • "installUpdate"—Corresponding to Install Update dialog box

    • "fileUpdate"—Corresponding to File Update, File No Update, and File Error dialog boxes

  • "unexpectedError"—Corresponding to Unexpected Error dialog box

    When set to false, the corresponding dialog box does not appear as part of the update procedure.

Here is an example of the configuration file for the ApplicationUpdater framework:

<?xml version="1.0" encoding="utf-8"?> 
<configuration xmlns="http://ns.adobe.com/air/framework/update/configuration/1.0"> 
      <url>http://example.com/updates/update.xml</url> 
      <delay>1</delay> 
</configuration>

Here is an example of the configuration file for the ApplicationUpdaterUI framework, which includes a definition for the defaultUI element:

<?xml version="1.0" encoding="utf-8"?> 
<configuration xmlns="http://ns.adobe.com/air/framework/update/configuration/1.0"> 
      <url>http://example.com/updates/update.xml</url> 
      <delay>1</delay> 
      <defaultUI> 
         <dialog name="checkForUpdate" visible="false" /> 
         <dialog name="downloadUpdate" visible="false" /> 
         <dialog name="downloadProgress" visible="false" /> 
      </defaultUI> 
</configuration>

Point the configurationFile property to the location of that file: as in the following

  • ActionScript:
    appUpdater.configurationFile = new File("app:/cfg/updateConfig.xml");
  • JavaScript:
    appUpdater.configurationFile = new air.File("app:/cfg/updateConfig.xml");

The templates directory of the update framework includes a sample configuration file, config-template.xml.

Defining update settings ActionScript or JavaScript code

These configuration parameters can also be set using code in the application, as in the following:

appUpdater.updateURL = " http://example.com/updates/update.xml"; 
appUpdater.delay = 1;

The properties of the updater object are updateURL and delay. These properties define the same settings as the updateURL and delay elements in the configuration file: the URL of the update descriptor file and the interval for checking for updates. If you specify a configuration file and settings in code, any properties set using code take precedence over corresponding settings in the configuration file.

You must define the updateURL property, either via the configuration file or via script (see Defining the update descriptor file and adding the AIR file to your web server) before using the updater (before calling the initialize() method of the updater object, described in Initializing the update framework).

The ApplicationUpdaterUI framework defines these additional properties of the updater object:

  • isCheckForUpdateVisible—Corresponding to the Check for Update, No Update, and Update Error dialog boxes

  • isDownloadUpdateVisible—Corresponding to the Download Update dialog box

  • isDownloadProgressVisible—Corresponding to Download Progress and Download Error dialog boxes

  • isInstallUpdateVisible—Corresponding to Install Update dialog box

  • isFileUpdateVisible—Corresponding to File Update, File No Update, and File Error dialog boxes

  • isUnexpectedErrorVisible—Corresponding to Unexpected Error dialog box

Each property corresponds to one or more dialog box in the ApplicationUpdaterUI user interface. Each property is a Boolean value, with a default value of true. When set to false the corresponding dialog boxes do not appear as part of the update procedure.

These dialog box properties override settings in the update configuration file.

The update process

The AIR update framework completes the update process in the following steps:

  1. The updater initialization checks to see if an update check has been performed within the defined delay interval (see Configuring the update settings). If an update check is due, the update process continues.

  2. The updater downloads and interprets the update descriptor file.

  3. The updater downloads the update AIR file.

  4. The updater installs the updated version of the application.

The updater object dispatches events at the completion of each of these steps. In the ApplicationUpdater version, you can cancel the events that indicate successful completion of a step in the process. If you cancel one of these events, the next step in the process is canceled. In the ApplicationUpdaterUI version, the updater presents a dialog box allowing the user to cancel or proceed at each step in the process.

If you cancel the event, you can call methods of the updater object to resume the process.

As the ApplicationUpdater version of the updater progresses through the update process, it records its current state, in a currentState property. This property is set to a string with the following possible values:

  • "UNINITIALIZED"—The updater has not been initialized.

  • "INITIALIZING"—The updater is initializing.

  • "READY"—The updater has been initialized

  • "BEFORE_CHECKING"—The updater has not yet checked for the update descriptor file.

  • "CHECKING"—The updater is checking for an update descriptor file.

  • "AVAILABLE"—The updater descriptor file is available.

  • "DOWNLOADING"—The updater is downloading the AIR file.

  • "DOWNLOADED"—The updater has downloaded the AIR file.

  • "INSTALLING"—The updater is installing the AIR file.

  • "PENDING_INSTALLING"—The updater has initialized and there are pending updates.

Some methods of the updater object only execute if the updater is in a certain state.

Initializing the update framework

After setting the configuration properties (see Basic example: Using the ApplicationUpdaterUI version), call the initialize() method to initialize the update:

appUpdater.initialize();

This method does the following:

  • It initializes the update framework, silently installing synchronously any pending updates. It is required to call this method during application startup because it may restart the application when it is called.

  • It checks if there is a postponed update and installs it;

  • If there is an error during the update process, it clears the update file and version information from the application storage area.

  • If the delay has expired, it starts the update process. Otherwise it restarts the timer.

Calling this method can result in the updater object dispatching the following events:

  • UpdateEvent.INITIALIZED—Dispatched when the initialization is complete.

  • ErrorEvent.ERROR—Dispatched when there is an error during initialization.

Upon dispatching the UpdateEvent.INITIALIZED event, the update process is completed.

When you call the initialize() method, the updater starts the update process, and completes all steps, based on the timer delay setting. However, you can also start the update process at any time by calling the checkNow() method of the updater object:

appUpdater.checkNow();

This method does nothing if the update process is already running. Otherwise, it starts the update process.

The updater object can dispatch the following event as a result of the calling the checkNow() method:

  • UpdateEvent.CHECK_FOR_UPDATE event just before it attempts to download the update descriptor file.

If you cancel the checkForUpdate event, you can call the checkForUpdate() method of the updater object. (See the next section.) If you do not cancel the event, the update process proceeds to check for the update descriptor file.

Managing the update process in the ApplicationUpdaterUI version

In the ApplicationUpdaterUI version, the user can cancel the process via Cancel buttons in the dialog boxes of the user interface. Also, you can programmatically cancel the update process by calling the cancelUpdate() method of the ApplicationUpdaterUI object.

You can set properties of the ApplicationUpdaterUI object or define elements in the update configuration file to specify which dialog box confirmations the updater displays. For details, see Configuring the update settings.

Managing the update process in the ApplicationUpdater version

You can call the preventDefault() method of event objects dispatched by the ApplicationUpdater object to cancel steps of the update process (see The update process). Canceling the default behavior gives your application a chance to display a message to the user asking if they want to proceed.

The following sections describe how to continue the update process when a step of the process has been canceled.

Downloading and interpreting the update descriptor file

The ApplicationUpdater object dispatches the checkForUpdate event before the update process begins, just before the updater tries to download the update descriptor file. If you cancel the default behavior of the checkForUpdate event, the updater does not download the update descriptor file. You can call the checkForUpdate() method resume the update process:

appUpdater.checkForUpdate();

Calling the checkForUpdate() method causes the updater to asynchronously download and interpret the update descriptor file. As a result of calling the checkForUpdate() method, the updater object can dispatch the following events:

  • StatusUpdateEvent.UPDATE_STATUS—The updater has downloaded and interpreted the update descriptor file successfully. This event has these properties:

    • available—A Boolean value. Set to true if there is a different version available than that of the current application; false otherwise (the version is the same).

    • version—A String. The version from the application descriptor file of the update file

    • details—An Array. If there are no localized versions of the description, this array returns an empty string ("") as the first element and the description as the second element.

      If there are multiple versions of the description (in the update descriptor file), the array contains multiple sub-arrays. Each array has two elements: the first is a language code (such as "en"), and the second is the corresponding description (a String) for that language. See Defining the update descriptor file and adding the AIR file to your web server.

  • StatusUpdateErrorEvent.UPDATE_ERROR—There was an error, and the updater could not download or interpret the update descriptor file.

Downloading the update AIR file

The ApplicationUpdater object dispatches the updateStatus event after the updater successfully downloads and interprets the update descriptor file. The default behavior is to start downloading the update file if it is available. If you cancel the default behavior, you can call the downloadUpdate() method to resume the update process:

appUpdater.downloadUpdate();

Calling this method causes the updater to asynchronously download update version of the AIR file.

The downloadUpdate() method can dispatch the following events:

  • UpdateEvent.DOWNLOAD_START—The connection to the server was established. When using ApplicationUpdaterUI library, this event displays a dialog box with a progress bar to track the download progress.

  • ProgressEvent.PROGRESS—Dispatched periodically as file download progresses.

  • DownloadErrorEvent.DOWNLOAD_ERROR—Dispatched if there is an error while connecting or downloading the update file. It is also dispatched for invalid HTTP statuses (such as “404 - File not found”). This event has an errorID property, an integer defining additional error information. An additional subErrorID property may contain more error information.

  • UpdateEvent.DOWNLOAD_COMPLETE—The updater has downloaded and interpreted the update descriptor file successfully. If you do not cancel this event, the ApplicationUpdater version proceeds to install the update version. In the ApplicationUpdaterUI version, the user is presented with a dialog box that gives them the option to proceed.

Updating the application

The ApplicationUpdater object dispatches the downloadComplete event when the download of the update file is complete. If you cancel the default behavior, you can call the installUpdate() method to resume the update process:

appUpdater.installUpdate(file);

Calling this method causes the updater install an update version of the AIR file. The method includes one parameter, file, which is a File object referencing the AIR file to use as the update.

The ApplicationUpdater object can dispatch the beforeInstall event as a result of calling the installUpdate() method:

  • UpdateEvent.BEFORE_INSTALL—Dispatched just before installing the update. Sometimes, it is useful to prevent the installation of the update at this time, so that the user can complete current work before the update proceeds. Calling the preventDefault() method of the Event object postpones the installation until the next restart and no additional update process can be started. (These include updates that would result by calling the checkNow() method or because of the periodical check.)

Installing from an arbitrary AIR file

You can call the installFromAIRFile() method to install the update version to install from an AIR file on the user’s computer:

appUpdater.installFromAIRFile();

This method causes the updater to install an update version the application from the AIR file.

The installFromAIRFile() method can dispatch the following events:

  • StatusFileUpdateEvent.FILE_UPDATE_STATUS—Dispatched after the ApplicationUpdater successfully validated the file sent using the installFromAIRFile() method. This event has the following properties:

    • available—Set to true if there is a different version available than one of the current application; false otherwise (the versions are the same).

    • version —The string representing the new available version.

    • path—Represents the native path of the update file.

    You can cancel this event if the available property of the StatusFileUpdateEvent object is set to true. Canceling the event cancels the update from proceeding. Call the installUpdate() method to continue the canceled update.

  • StatusFileUpdateErrorEvent.FILE_UPDATE_ERROR—There was an error, and the updater could not install the AIR application.

Canceling the update process

You can call the cancelUpdate() method to cancel the update process:

appUpdater.cancelUpdate();

This method cancels any pending downloads, deleting any incomplete downloaded files, and restarts the periodical check timer.

The method does nothing if the updater object is initializing.

Localizing the ApplicationUpdaterUI interface

The ApplicationUpdaterUI class provides a default user interface for the update process. This includes dialog boxes that let the user start the process, cancel the process, and perform other related actions.

The description element of the update descriptor file lets you define the description of the application in multiple languages. Use multiple text elements that define lang attributes, as in the following:

<?xml version="1.0" encoding="utf-8"?> 
     <update xmlns="http://ns.adobe.com/air/framework/update/description/1.0"> 
       <version>1.1a1</version> 
       <url>http://example.com/updates/sample_1.1a1.air</url> 
       <description> 
           <text xml:lang="en">English description</text> 
           <text xml:lang="fr">French description</text> 
           <text xml:lang="ro">Romanian description</text> 
       </description> 
    </update>

The update framework uses the description that best fits the end user’s localization chain. For more information, see Defining the update descriptor file and adding the AIR file to your web server.

Flex developers can directly add a new language to the "ApplicationUpdaterDialogs" bundle.

JavaScript developers can call the addResources() method of the updater object. This method dynamically adds a new resource bundle for a language. The resource bundle defines localized strings for a language. These strings are used in various dialog box text fields.

JavaScript developers can use the localeChain property of the ApplicationUpdaterUI class to define the locale chain used by the user interface. Typically, only JavaScript (HTML) developers use this property. Flex developers can use the ResourceManager to manage the locale chain.

For example, the following JavaScript code defines resource bundles for Romanian and Hungarian:

appUpdater.addResources("ro_RO", 
                    {titleCheck: "Titlu", msgCheck: "Mesaj", btnCheck: "Buton"}); 
appUpdater.addResources("hu", {titleCheck: "Cím", msgCheck: "Üzenet"}); 
var languages = ["ro", "hu"]; 
languages = languages.concat(air.Capabilities.languages); 
var sortedLanguages = air.Localizer.sortLanguagesByPreference(languages, 
                         air.Capabilities.language, 
                         "en-US"); 
sortedLanguages.push("en-US"); 
appUpdater.localeChain = sortedLanguages;

For details, see the description of the addResources() method of the ApplicationUpdaterUI class in the language reference.