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.

Downloading the update descriptor file

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).

Implementing the downloadUpdateDescriptor function

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);
}
}

    

Downloading the update file

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));
}

    

Instantiating FileStream

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);
}

    

Writing downloaded bytes into the update file

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();
}

    

Installing the update file

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>

Implementing installUpdate function

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.

Updating on the Mac OS X platform

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.

Where to go from here

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:

This content requires Flash To view this content, JavaScript must be enabled, and you need the latest version of the Adobe Flash Player. To view this content, JavaScript must be enabled, and you need the latest version of the Adobe Flash Player.

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.

Updating Adobe AIR applications packaged with a native installer

by Piotr Walczyszyn

Content

Created

Page tools

Requirements

Prerequisite knowledge

User level

Required products

Sample files

Downloading the update descriptor file

Implementing the downloadUpdateDescriptor function

Downloading the update file

Instantiating FileStream

Writing downloaded bytes into the update file

Installing the update file

Implementing installUpdate function

Updating on the Mac OS X platform

Where to go from here

More Like This

Products

Download

Support & Learning

Buy

Company