Using the Adobe AIR update framework
Requirements
Prerequisite knowledge
General experience building HTML-based applications is suggested. For more details on getting started with this Quick Start, refer to Building the Quick Start sample applications with HTML.
Additional Requirements
User level
Beginning
Required products
The 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 HTML-based AIR application.
Note: The UpdateSampleHTML application is an example application provided, as is, for instructional purposes.
The sample applications include the following files:
- UpdateSampleHTML/src/index.html: The main HTML file for the sample application
- UpdateSampleHTML/src/application.xml: The application descriptor file for the AIR application
- AIRAliases.js: The AIR JavaScript aliases file
- UpdateSampleHTML/src/SampleStyles.css: A CSS file defining styles used in the application
- UpdateSampleHTML/src/applicationupdater_ui.swf: A SWF file definingthe ApplicationUpdaterUI class
- UpdateSampleHTML/src/config/update-config.xml: The update configuration file, containing configuration settings for the updater
- UpdateSampleHTML/src/icons: A directory of icons used by the application
- UpdateSampleHTML/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 UpdateSampleHTML/server directory of the ZIP source files. Add this file and the UpdateSampleHTML2.air file to the UpdateSampleHTML subdirectory of the root of your localhost web server. (The UpdateSampleHTML2.air file is version 2.0 of the sample application.)
- Double-click the UpdateSampleHTML1.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 UpdateSampleHTML application uses an ApplicationUpdaterUI object to add update framework functionality. The onload event of the body tag calls the init() function. The function initializes the application. It first calls the setApplicationNameAndVersion() function, 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 xmlString = air.NativeApplication.nativeApplication.applicationDescriptor;
var appXml = new DOMParser();
var xmlObject = appXml.parseFromString(xmlString, "text/xml");
var root = xmlObject.getElementsByTagName('application')[0];
var lblAppVersion = document.getElementById("lblAppVersion");
var lblAppName = document.getElementById("lblAppName");
lblAppVersion.value = root.getElementsByTagName("version")[0].firstChild.data;
lblAppName.value = root.getElementsByTagName("name")[0].firstChild.data;
The init() method then instantiates an ApplicationUpdaterUI object.
appUpdater = new air.ApplicationUpdaterUI();
appUpdater.configurationFile = new air.File("app:/config/update.xml");
appUpdater.addEventListener(air.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 applicationupdater_ui.swf file in the frameworks/libs/air directory of the AIR SDK. This application loads the SWF file from the application directory:
<script src="applicationupdater_ui.swf" type="application/x-shockwave-flash" />
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/UpdateSampleHTML/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 is defined as the UpdateSampleHTML/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/UpdateSampleHTML/UpdateSampleHTML2.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 named UpdateSampleHTML1.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 UpdateSampleHTML2.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 UpdateSampleHTML directory on your localhost web server.
- Post the version 2.0 version of the AIR file to the UpdateSampleHTML directory on your localhost web server.
Localizing the user interface
If you need to provide user interface in multiple languages, set the locale chain using the localeChain property of the updater object. For example, the following code adds French and English to the locale chain:
appUpdater.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(s) to use in the locale chain by querying the user. Or you can examine the air.Capabilities.language and air.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 Building Adobe AIR Applications. Also, check out the air.update and air.update.events packages in the Adobe AIR API Reference for HTML Developers, and read Mihai Corlan's Developer Center article on Using the Adobe AIR update framework.
