Using the Adobe AIR update framework
Requirements
Prerequisite knowledge
General experience of building applications with Flash CS4 Professional is suggested. For more details on getting started with this Quick Start, refer to Building the Quick Start sample applications with Flash.
Additional Requirements
User level
Beginning
Required products
- Adobe AIR
- Flash Professional (Download trial)
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.
Note: The UpdateSampleFlash application is an example application provided, as is, for instructional purposes.
The sample applications include the following files:
- UpdateSampleFlash/UpdateSampleFlash.fla: The main Flash file for the sample application
- UpdateSampleFlash/UpdateSampleFlash.as: The ActionScript 3.0 class file defining program logic
- UpdateSampleFlash/UpdateSampleFlash-app.xml: The application descriptor file for the AIR application
- UpdateSampleFlash/config/update-config.xml: The update configuration file, containing configuration settings for the updater
- UpdateSampleFlash/icons: A directory of icons used by the application
- UpdateSampleFlash/server/update-descriptor.xml: The update descriptor file, containing information about the update
Testing the application
To test the application:
- 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.)
- Double-click the UpdateSampleFlash1.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 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 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.
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 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 it into an AIR file twice:
- Compile and package the application into an AIR file named UpdateSampleFlash1.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 UpdateSampleFlash2.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 UpdateSampleFlash directory on your localhost web server.
- 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.
