The location of the configuration file that sets the values for delay and updateURL properties. It also has settings for determining whether the application displays various confirmation dialog boxes during the update process. If this property points to a non-existent file, calling the initialize() method results in an Error being thrown.

Here is a sample configuration file:

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

Instead of loading a configuration file, you can use ActionScript code to set the following properties of the ApplicationUpdaterUI object: delay, isCheckForUpdateVisible, isDownloadProgressVisible, isDownloadUpdateVisible, isFileUpdateVisible, isInstallUpdateVisible, and updateURL properties.

See also

The current version of the application. This property is set during a call to the initialize() method. It is set to the version from the application descriptor file.

The interval, in days, between periodic checks of new updates.

A value of 0 (the default value) indicates that the timer is not active, so no periodic check is done. The delay can be set either via this property or via the configuration file. When the value is set using both methods, the value set using this property is used.

The default value is 0.

See also

Enables the visibility of the Check for Update, No Update, and Update Error dialog boxes. When set to true, the updater displays these dialog boxes as part of the update process. This can also be set in the update configuration file. A value set using this property overrides the setting in the update configuration file.

Enables the visibility of the Download Update dialog box. When set to true, the updater displays this dialog box as part of the update process. This can also be set in the update configuration file. A value set using this property overrides the setting in the update configuration file.

Enables the visibility of the Download Update dialog box. When set to true, the updater displays these dialog boxes as part of the update process. This can also be set in the update configuration file. A value set using this property overrides the setting in the update configuration file.

Enables the visibility of the File Update, File No Update, and File Error dialog boxes. When set to true, the updater displays these dialog boxes as part of the update process. This can also be set in the update configuration file. A value set using this property overrides the setting in the update configuration file.

Whether this is the first run after a successful update (true) or not (false). The updater sets this value during the call to the initialize() method. The developer should check that isFirstRun is set to true if there is a need to migrate data from one version to another.

See also

Enables the visibility of the Install Update dialog box. When set to true, the updater displays this dialog box as part of the update process. This can also be set in the update configuration file. A value set using this property overrides the setting in the update configuration file.

A function that the updater should use to perform version comparisons. By default, the update framework does a version comparison to detect whether the version from the remote site is newer than the version of the installed application. However, sometimes the default comparison does not match the developer's versioning scheme. Set this property to provide a new function that does the comparison.

The default comparision function accepts versions like x.y.z, where x, y, and z can contain letters and digits. There are some special conditions that the default comparision function recognizes. If the test function finds "alpha", "beta", or "rc" in the version strings, the order is alpha < beta < rc.

appUpdate.isNewerVersionFunction = customFn; 

function customFn (currentVersion:String, updateVersion:String):Boolean 
{
    return updateVersion > currentVersion;
}

Enables the visibility of the Unexpected Error dialog box. When set to true, the Application Updater displays this dialog box as part of the update process. This can also be set in the update configuration file. A value set using this property overrides the setting in the update configuration file.

A Boolean property, which is true if an update is running, false otherwise.

An array defining the locale chain used by the user interface. Typically, only JavaScript (HTML) developers use this property.

Flex developers can use the ResourceManager to handle the locale chain.

By default, in an HTML-based application, the languages are sorted between those languages in the Capabilities.languages array and the ten languages supported by the user interface. If no match is found, the user interface uses the English language.

This JavaScript example uses the AIR HTML localization framework, included in the AIR SDK. It sorts the languages against the list of languages, and then it sets English as the default fallback language:

 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;

See also

The previous location of the application storage directory, if it changed after an update. The application storage directory location changes after an upgrade with a certificate migration. If there is no certificate migration, the application storage directory does not change when the user updates the application. and this property is set to null. This property is set during a call to the initialize() method.

A developer can sign new version of AIR application with a new certificate if the developer uses the -migrate option when packaging the AIR file with ADT. If a new version of an AIR application uses a new signing certificate, the local storage directory of the application changes when the user installs the new version. Use this property to transfer data from the old application storage directory to the new application storage directory (File.applicationStorageDirectory). For more information, see "Signing an AIR file to change the application certificate" in the "Creating an AIR application using the command line tools" chapter of the Adobe AIR developer's guide.

The previous version of the application. This property is set during a call to the initialize() method. Returns the previous version of the application before the upgrade (set only if isfirstRun is true); otherwise it is set to null.

The content of the update descriptor file downloaded from the update URL. This property is non-null only after the updater object dispatches an updateStatus event.

The location of the update descriptor file. Any location valid for a URLRequest path is accepted. This is the only mandatory setting required by the updater. You can set the update URL either via this property or via the configuration file. When the value is set using both methods, the updater uses the value set using this property.

See also

Whether there was a postponed update, even if it failed to install (true); false otherwise. The updater sets this property during a call to the initialize() method. Use the wasPendingUpdate and isFirstRun properties to check if an update failed to install (in which case wasPendingUpdate is set to true and isFirstRun is set to false).

See also

The constructor function.

Dynamically adds a new resource bundle for the specified language. JavaScript developers use this method to dynamically add a new language for the dialog boxes that the application updater UI displays. (Flex developers can directly add a new language to the "ApplicationUpdaterDialogs" resource bundle.)

Parameters

See also

Cancels the update process. Calling this method cancels any pending downloads, deleting any incomplete downloaded files, and restarts the periodic check timer.

The update process can be canceled at any time except when the state machine is in "uninitialized" or "initializing" state. It does nothing when it is called in one of the "uninitialized" or "initializing" states.

Starts the update process. Calling this method does not stop the periodic timer; however, the method detects that an update process is running and will skip the current iteration.

This method only executes if the current state is "Ready".

This method can result in the updater object dispatching the following event:

Initializes the updater. Calling this method does the following:

1. It initializes the update framework, silently (and synchronously) installing any pending updates. You should call this method during application startup, since it may restart the application.

2. It checks if there is a postponed update and installs it.

3. If something went wrong with a prior update, it clears the update file and version information from the storage area.

4. If the periodic timer delay has expired, it starts the update process; otherwise it starts the periodic timer. However, when testing an application using the AIR Debug Launcher (ADL) application, attempting to update the application results in a IllegalOperationError exception.

Starts the update process using a local AIR file.

Calling this method has no effect if an update process is running (if the state is not "Downloaded").

This function is useful for an application that has the customUpdateUI element set to true in the application descriptor file.

When testing an application using the AIR Debug Launcher (ADL) application, calling this method results in an IllegalOperationError exception.

Parameters

Dispatched just before installing the update, after the installUpdate() method was called. Sometimes, it is useful to prevent the installation of the update at this time, because the user could lose all current work when the runtime exits the application to install the update.

Calling this event's preventDefault() method postpones the installation until the next restart. If you call the preventDefault() method, no additional update process can be started during this application session (via a call to the installUpdate() method or because of the periodic check).

This event has the following properties:

Dispatched before the update process begins, just before the updater tries to download the update descriptor file. The updater can dispatch this event as a result of directly calling the checkNow() method or because the periodic check timer expired.

This event has the following properties:

Dispatched when the download of the update file is complete.

This event has the following properties:

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

When this event is dispatched the periodic timer is automatically restarted (if the delay is greater than 0).

The errorID property of a DownloadErrorEvent object is an integer defining error information (see the following table). An additional subErrorID property may contain more error information.

Dispatched after a call to the downloadUpdate() method and the connection to the server is established. When using ApplicationUpdater library, you may want the event handler for this event to display a progress bar to report the download progress to the user.

This event has the following properties:

Dispatched when an error occurred either during initialization or during the update process (if something unexpected happens).

This event has the following properties:

Dispatched when an error occurs validating the file passed as the airFile parameter in a call to the installFromAIRFile() method.

Dispatched after the updater successfully validates the file in the call to the installFromAIRFile() method.

This event has the following properties:

Dispatched after the initialization is complete.

This event has the following read-only properties:

• isFirstRun (Boolean) true if this is the first run after a successful update; false otherwise.

• previousVersion (String) The previous version of the application before the upgrade (set only if isfirstRun is true).

• currentVersion (String) The version from the application descriptor file of the currently installed version.

This event has the following properties:

Dispatched after the initialization is complete.

This event has the following properties:

Dispatched if an error occurs while trying to download or parse the update descriptor file.

When the updater dispatches this event, the periodic timer is automatically restarted (if the delay setting is greater than 0). The application should consider hiding any error dialog boxes when the updater dispatches a new checkForUpdate event.

Dispatched after the updater successfully downloads and interprets the update descriptor file.

This event has the following properties: