by Jeff Swartz

Jeff Swartz

Created

17 November 2008

Requirements
Prerequisite knowledge

General experience of building applications
with Flash CS3 is suggested.
For more details on getting started with
this Quick Start, refer to Building the Quick
Start sample applications with Flash.


Additional Requirements

Required products

Sample files

User level

Beginning
 
The AIR update framework provides developers with an easy way to manage and distribute updated versions of Adobe AIR applications.
This article describes how to use the update framework in a sample Flash application built on AIR.
UpdateSampleFlash application
Figure 1. The UpdateSampleFlash example application.
 
Note: The UpdateSampleFlash application is an example application provided, as is, for instructional purposes.
 
The sample applications include the following files:.
 
  • UpdateSampleFlash/UpdateSampleFlash.flaThe main Flash file for the sample application
  • UpdateSampleFlash/UpdateSampleFlash.asThe ActionScript 3.0 class file defining program logic
  • UpdateSampleFlash/UpdateSampleFlash-app.xmlThe application descriptor file for the AIR application
  • UpdateSampleFlash/config/update-config.xmlThe update configuration file, containing configuration settings for the updater
  • UpdateSampleFlash/iconsA directory of icons used by the application
  • UpdateSampleFlash/server/update-descriptor.xml: The update descriptor file, containing information about the update
 
Testing the application
 
  1. Locate the update-descriptor.xml file in the UpdateSampleFlash/server directory of the ZIP source files. Add this file and the UpdateSampleFlash2.air file to the UpdateSampleFlash subfolder of the root of your localhost web server. (The UpdateSampleFlash2.air file is version 2.0 of the sample application.)
  2. Double-click the UpdateSampleFlash1.air file to install version 1.0 of the sample application.
  3. Run the installed application (version 1.0).
  4. 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 UpdateSampleFlash application uses an ApplicationUpdaterUI object to add update framework functionality. To use this class in Flash CS4 Professional, download the Flex SDK. The applicationupdater_UI.swc file is in the frameworks/libs/air subdirectory subdirectory subdirectory of the Flex SDK. Add this SWC file to the Flash library path. (For convenience, the source files for this sample application also include this SWC file.)
 
The Flash project uses the UpdateSampleFlash class (defined in the UpdateSampleFlash.as file) as the document class for the application. It defines all of the program logic.
 
The UpdateSampleFlash() constructor function 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 constructor function then instantiates an ApplicationUpdaterUI object.
 
var appXML:XML = appUpdater = new ApplicationUpdaterUI(); appUpdater.configurationFile = new File("app:/config/update.xml"); appUpdater.addEventListener(ErrorEvent.ERROR, onError); appUpdater.initialize();
 
The configurationFile property of the appUpdater object points to the update configuration file. This is an XML file that defines update settings. It includes this information:
 
<?xml version="1.0" encoding="utf-8"?> <configuration xmlns="http://ns.adobe.com/air/framework/update/configuration/1.0" > <url>http://localhost/UpdateSampleFlash/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 UpdateSampleFlash/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/UpdateSampleFlash/UpdateSampleFlash2.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 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
  • isFileUpdateVisible—Corresponding to File Update, File No Update, and File Error dialog boxes
  • isUnexpectedErrorVisible—Corresponding to Unexpected Error dialog boxThese properties are all set with visible=true by default.

 

Packaging the application
Before testing the application, you will need to package it into an AIR file twice:
  1. Compile and package the application into an AIR file named UpdateSampleFlash1.air. Leave the version setting in the application descriptor file set to 1.0, as it is in the source files.
  2. Change the version setting in the application descriptor file (UpdateSample-app.xml) to 2.0. Compile and package the application again into an AIR file named UpdateSampleFlash2.air. Be sure to use the same code signing certificate when packaging the application as you did in version 1.0.
  3. Copy the update-descriptor.xml file, in the server directory of the source files, to the UpdateSampleFlash directory on your localhost web server.
  4. Post the 2.0 version of the AIR file to the UpdateSampleFlash directory on your localhost web server.

 

 

 
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 Building Adobe AIR Applications. Also, check out the air.update and air.update.events packages in the ActionScript 3 Reference for the Adobe Flash Platform, and read Mihai Corlan's Developer Center article on Using the Adobe AIR update framework.