Table of contents
Created
28 February 2011
Requirements |
||
|
Prerequisite knowledge
Basic knowledge of ActionScript 3 and MXML. |
Required products
Flash Builder (Download trial) Flex 4.1 SDK Adobe AIR |
Sample files
NativeUpdater.zip |
|
Additional requirements
Adobe AIR SDK NativeApplicationUpdater library |
||
|
User level
Intermediate |
With the release of Adobe AIR SDK 2 developers have the ability to package their applications into native installer files. Later these installer files can be launched on different platforms like Windows (EXE), Mac OS X (DMG) and Linux distributions capable of installing from deb or rpm files. This feature can be useful in various scenarios but its main purpose is the introduction of the NativeProcess API that gives developers the ability to execute native code from AIR applications. This new AIR application installation process ensures that the application will run properly on the targeted platform.
Unfortunately the Update Framework that comes with the AIR SDK doesn't support updates of AIR apps packaged into native installers. The good news is that the NativeProcess API makes it easy to help build your own update mechanism.
This article will step you through the process of how to build your own custom update mechanism for the Windows platform. The logic of this mechanism will be encapsulated in the
NativeUpdater class with a single public function updateApplication used to trigger the update process. Download the sample files that accompany this article for the complete source code. For details on how to use the update installer on the Mac OS X platform, refer to the section at the end of this article.The first step that the update mechanism has to do is to download the update descriptor file to check whether an update is available. The update descriptor file can be the same file you would use with the standard AIR Update Framework. The assumption here is that the application will be built with the AIR 2.5 SDK, which includes the new namespace tag
<versionNumber /> (previously <version /> ); this applies to both update descriptor and application descriptor files. The update descriptor file that you can use should look similar to the following:<?xml version="1.0" encoding="utf-8"?>
<update xmlns="http://ns.adobe.com/air/framework/update/description/2.5">
<versionNumber>0.9.1</versionNumber>
<url>app:/remoteFolder/NativeUpdater.exe</url>
<description>This is a new version of NativeUpdater application.</description>
</update>
Note here that the
url tag should point to the application directory where your native installer will be placed (most likely somewhere on your http server).The
downloadUpdateDescriptor function will use the URLLoader class in order to initiate the download process. URLLoader instance will have two event handlers defined to handle complete and IO error events.protected function downloadUpdateDescriptor():void
{
var updateDescLoader:URLLoader = new URLLoader;
updateDescLoader.addEventListener(Event.COMPLETE, updateDescLoader_completeHandler);
updateDescLoader.addEventListener(IOErrorEvent.IO_ERROR, updateDescLoader_ioErrorHandler);
updateDescLoader.load(new URLRequest(UPDATE_DESCRIPTOR_URL));
}
Next, the
updateDescLoader_completeHandler function reads the downloaded update descriptor XML file and compares the current application version with update version. If those values don't match it invokes the downloadUpdate function passing it the URL address of the native installer file.protected function updateDescLoader_completeHandler(event:Event):void
{
var loader:URLLoader = URLLoader(event.currentTarget);
// Closing update descriptor loader
closeUpdateDescLoader(loader);
// Getting update descriptor XML from loaded data
var updateDescriptor:XML = XML(loader.data);
// Getting default namespace of update descriptor
var udns:Namespace = updateDescriptor.namespace();
// Getting application descriptor XML
var applicationDescriptor:XML = NativeApplication.nativeApplication.applicationDescriptor;
// Getting default namespace of application descriptor
var adns:Namespace = applicationDescriptor.namespace();
// Getting versionNumber from update descriptor
var updateVersion:String = updateDescriptor.udns::versionNumber.toString();
// Getting versionNumber from application descriptor
var currentVersion:String = applicationDescriptor.adns::versionNumber.toString();
// Comparing current version with update version
if (currentVersion != updateVersion)
{
// Getting update url
var updateUrl:String = updateDescriptor.udns::url.toString();
// Downloading update file
downloadUpdate(updateUrl);
}
}
In this step the update mechanism has to download the update file from the remote location. Before it can start downloading the file it also has to resolve the name of the downloaded file. This is done by parsing out the last fragment of the URL address and creating a reference to the file with the name of that fragment in the temporary directory.
Now to do the actual download procedure; you can use the URLStream class, which is very efficient in this type of scenarios. You could also use URLLoader, but it would buffer the entire application file in memory before it could write it to the hard drive which is not best practice in the case of large application packages.
protected function downloadUpdate(updateUrl:String):void
{
// Parsing file name out of the download url
var fileName:String = updateUrl.substr(updateUrl.lastIndexOf("/") + 1);
// Creating new file ref in temp directory
updateFile = File.createTempDirectory().resolvePath(fileName);
// Using URLStream to download update file
urlStream = new URLStream;
urlStream.addEventListener(Event.OPEN, urlStream_openHandler);
urlStream.addEventListener(ProgressEvent.PROGRESS, urlStream_progressHandler);
urlStream.addEventListener(Event.COMPLETE, urlStream_completeHandler);
urlStream.addEventListener(IOErrorEvent.IO_ERROR, urlStream_ioErrorHandler);
urlStream.load(new URLRequest(updateUrl));
}
When URLStream is opened, the
urlStream_openHandler function is called. Within this function an instance of the FileStream class can get created; this class will be used to write downloaded bytes into the local update file.protected function urlStream_openHandler(event:Event):void
{
// Creating new FileStream to write downloaded bytes into
fileStream = new FileStream;
fileStream.open(updateFile, FileMode.WRITE);
}
Update file bytes are downloaded in batches, that is why the progress event has to be handled in order to write those bytes to the local file. The
urlStream_progressHandler function is responsible for doing this and it uses ByteArray to read loaded bytes from URLStream and to write these into the FileStream instance.protected function urlStream_progressHandler(event:ProgressEvent):void
{
// ByteArray with loaded bytes
var loadedBytes:ByteArray = new ByteArray;
// Reading loaded bytes
urlStream.readBytes(loadedBytes);
// Writing loaded bytes into the FileStream
fileStream.writeBytes(loadedBytes);
}
When URLStream completes downloading update file bytes, both URLStream and FileStream should be closed. Next, the
installUpdate function can be called.protected function urlStream_completeHandler(event:Event):void
{
// Closing URLStream and FileStream
closeStreams();
// Installing update
installUpdate();
}
The last step to be accomplished is actually running the downloaded update file. In order to do this you can use the NativeProcess API. Remember that in order to use this new API your application descriptor (*-app.xml) file needs to set
supportedProfiles tag to extendedDesktop value as in the following snippet:<supportedProfiles>extendedDesktop</supportedProfiles>
First, the
installUpdate function creates an instance of the NativeProcessStartupInfo class and sets the executable property to the reference of the update file. Next, it uses the NativeProcess class to execute the downloaded update file. At last the application can be closed in order to let the installer run.protected function installUpdate():void
{
// Running the installer using NativeProcess API
var info:NativeProcessStartupInfo = new NativeProcessStartupInfo;
info.executable = updateFile;
var process:NativeProcess = new NativeProcess;
process.start(info);
// Exit application for the installer to be able to proceed
NativeApplication.nativeApplication.exit();
}
When the application exits and the update file is launched, users should see the standard update window displayed by the AIR runtime (see Figure 1). Clicking the Replace button initiates the update process; when finished, the application will automatically relaunch.
Figure 1. The AIR Runtime application update window.
In the case of Mac OS X, the process is a bit more complex. First you have to mount the downloaded DMG file. This can be done using the command line util application, hdiutil, which is usually located in
/usr/bin/hdiutil. Hdiutil should be executed using the NativeProcess API and have three arguments passed: attach, -plist, and the path to downloaded update file. In return hdiutil will pass the plist XML content which can be read with the ProgressEvent.STANDARD_OUTPUT_DATA event handler. From the returned XML data you can extract the path to the mounted DMG file, that is passed as value of the mount-point key node. The last step is to execute the installer file that is located in the Contents/MacOS directory of the mounted DMG file. Next the installer can be executed in the same way as on the Windows platform using the NativeProcess API as described above.Another option that is available when updating applications packaged with the native installer is to use my NativeApplicationUpdater library, which is available on Google Code. The benefit of using this library is that it hides the differences between the OSes. You can find a short tutorial on how to build custom UI for this library on my blog. You can also watch the following video to see how it works:
If you want to build your own updater and also support other OSes I encourage you to look through the NativeApplicationUpdater source code to understand how those other platforms should be handled.