Using the Adobe AIR update framework
Requirements
Prerequisite knowledge
General experience building applications with Flex Builder or the Flex SDK is suggested. For more details on getting started with this Quick Start, refer to Building the Quick Start sample applications with Flex.
User level
Beginning
Required products
- Adobe AIR
- Flash Builder (Download trial)
- Flex (Download trial)
The Adobe AIR update framework provides developers with an easy way to manage and distribute updated versions of AIR applications.
This article describes how to use the update framework in a sample Flex application built on AIR.
Note: This is a sample application provided, as is, for instructional purposes.
The sample applications include the following files:
- UpdateSampleFlex/src/UpdateSampleFlex.mxml: The main Flex file for the sample application
- UpdateSampleFlex/src/UpdateSampleFlex-app.xml: The application descriptor file for the AIR application
- UpdateSampleFlex/src/config/update-config.xml: The update configuration file, containing configuration settings for the updater
- UpdateSampleFlex/src/icons: A directory of icons used by the application
- UpdateSampleFlex/server/update-descriptor.xml: The update descriptor file, containing information about the update
- more_samples: A directory containing other samples that use the update framework
Testing the application
To test the application:
- Locate the update-descriptor.xml file in the UpdateSampleFlex/server directory of the ZIP source files. Add this file and the UpdateSampleFlex2.air file to the UpdateSampleFlex subfolder of the root of your localhost web server. (The UpdateSampleFlex2.air file is version 2.0 of the sample application.)
- Double-click the UpdateSampleFlex1.air file to install version 1.0 of the sample application.
- Run the installed application (version 1.0).
- The application displays the current version information in the user interface. It then checks for the update descriptor file on your web server and progresses through the update process. The application presents confirmation dialog boxes at each step of the update process.
Understanding the code
The UpdateSampleFlex application uses an ApplicationUpdaterUI object to add update framework functionality. The onApplicationComplete() method is the event listener for the applicationComplete event. The method initializes the application. It first calls the setApplicationNameAndVersion() method, which gets the application name and version information from the application descriptor file for the installed application. It then displays the application name and version in the user interface:
var appXML:XML = NativeApplication.nativeApplication.applicationDescriptor;
var ns:Namespace = appXML.namespace();
lblAppVersion.text = appXML.ns::version;
lblAppName.text = appXML.ns::name;
The onApplicationComplete() method then instantiates an ApplicationUpdaterUI object.
appUpdater = new ApplicationUpdaterUI();
appUpdater.configurationFile = new File("app:/config/update.xml");
appUpdater.addEventListener(ErrorEvent.ERROR, onError);
appUpdater.initialize();
The ApplicationUpdaterUI class is one of the two main classes in the AIR application update framework. The class is defined in the air.update package, and it is included in the applicationupdater_ui.swc file in the frameworks/libs/air directory of the Flex SDK.
The configurationFile property of the appUpdater object points to the update configuration file. This is an XML file that defines update settings. It includes the following information:
<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns="http://ns.adobe.com/air/framework/update/configuration/1.0" >
<url>http://localhost/UpdateSampleFlex/update-descriptor.xml</url>
<delay>1</delay>
<defaultUI>
<dialog name="checkForUpdate" visible="true" />
<dialog name="downloadUpdate" visible="true" />
<dialog name="downloadProgress" visible="true" />
<dialog name="installUpdate" visible="true" />
<dialog name="fileUpdate" visible="true" />
<dialog name="unexpectedError" visible="true" />
</defaultUI>
</configuration>
The url property defines the URL of the update descriptor file on your web server. For this sample application, the URL is defined as the UpdateSampleFlex/update-descriptor.xml file on the localhost server. For your application, you will want to change this to point to the real location of the update descriptor file. (For test purposes, you can also set this to app:/server/update.xml and put the update version of the AIR application in the application directory. However, in a real-world scenario, you would post the update descriptor file and the update AIR file on a web server.)
The update descriptor file is an XML file that contains information on the update version of the AIR application. In this sample application, the update descriptor file contains the following information:
<?xml version="1.0" encoding="utf-8"?>
<update xmlns="http://ns.adobe.com/air/framework/update/description/1.0">
<version>2.0</version>
<url>http://localhost/UpdateSampleFlex/UpdateSampleFlex2.air</url>
<description><![CDATA[
Version 2.0. This new version includes:
* Feature 1
* Feature 2
* Feature 3
]]></description>
</update>
This file defines the version, location, and description of the update AIR file. The version in this XML file must match the version in the application descriptor file of the AIR file for the update to succeed.
The delay property sets the delay between periodic checks for updates. In this case, the application checks every day (1).
The dialog properties of the defaultUI element set which confirmation dialog boxes to display:
checkForUpdate—Corresponding to the Check for Update, No Update, and Update Error dialog boxesdownloadUpdate—Corresponding to the Download Update dialog boxdownloadProgress—Corresponding to Download Progress and Download Error dialog boxesinstallUpdate—Corresponding to Install Update dialog boxisFileUpdateVisible—Corresponding to File Update, File No Update, and File Error dialog boxesisUnexpectedErrorVisible—Corresponding to Unexpected Error dialog box
These properties are all set with visible=true by default. The properties are defined in the sample file so that you can easily change visible to false if you want.
Packaging the application
Before testing the application, you will need to package into an AIR file twice:
- Compile and package the application into an AIR named UpdateSampleFlex1.air. Leave the
versionsetting in the application descriptor file set to1.0, as it is in the source files. - Change the
versionsetting in the application descriptor file (UpdateSample-app.xml) to2.0. Compile and package the application again into an AIR file named UpdateSampleFlex2.air. Be sure to use the same code signing certificate when packaging the application as you did in version 1.0. - Copy the update-descriptor.xml file, in the server directory of the source files, to the UpdateSampleFlex directory on your localhost web server.
- Post the version 2.0 version of the AIR file to the UpdateSampleFlex directory on your localhost web server.
Localizing the user interface
If you need to provide user interface in multiple languages, use the ResourceManager class to set the locale chain. For example, the following code adds French and English to the locale chain:
resourceManager.localeChain = ["fr", "en"];
If you set this in the initialization function (onApplicationComplete()), the updater uses French in the user interface. It would be better if your application were to determine which language (or languages) to use in the locale chain by querying the user. Or you can examine the Capabilities.language and Capabilities.languages properties.
Where to go from here
The update framework has many more features. For example, you can use the ApplicationUpdater class if you want to provide a different user interface than that provided by the ApplicationUpdaterUI class. The more_samples directory of the download ZIP file for this article includes many more examples of the update framework. For more information on the update framework, see the "Using the Update Framework" section in the "Updating AIR applications" chapter of Developing Adobe AIR Applications with Adobe Flex. Also, check out the air.update and air.update.events packages in the Adobe Flex 3 Language Reference, and read Mihai Corlan's Developer Center article on Using the Adobe AIR update framework.
