Updating applications programmatically
Back to: Apollo Documentation home page
The Updater class (in the flash.system package) includes one method, update(), which you can use to update the currently running application with a different version.
For example, if the user has a version of the AIR file ("Sample_App_v2.air") located on the desktop, the following code updates the application:
var updater:Updater = new Updater();
var airFile:File = File.desktopDirectory.resolve("Sample_App_v2.air");
updater.update(air);
Results of calling the update() method
When an application running in the Apollo runtime calls the update() method, the runtime closes the application, and it then attempts to install the new version from the AIR file. If installation completes successfully, the Apollo runtime opens the new version of the application. Otherwise (if the installation cannot complete), it re-opens the existing (pre-install) version of the application.
When testing an application using ADL, calling the update() method installs and runs a new version of the application only if the Apollo runtime is installed. If the Apollo runtime is not installed, the call to the update() results in a runtime exception.
Downloading an AIR file to the user's computer
To use the Updater class, you must first save an AIR file locally to the user's machine. For example, the following code reads an AIR file from a URL (http://example.com/apollo/updates/Sample_App_v2.air) and saves the AIR file to the desktop:
var urlString:String = "http://example.com/apollo/updates/Sample_App_v2.air";
var urlReq:URLRequest = new URLRequest(urlString);
var urlStream:URLStream = new URLStream();
var fileData:ByteArray = new ByteArray();
urlStream.addEventListener(Event.COMPLETE, loaded);
urlStream.load(urlReq);
function loaded(event:Event):void {
trace(urlStream.bytesAvailable);
urlStream.readBytes(fileData, 0, urlStream.bytesAvailable);
writeAirFile();
}
function writeAirFile():void {
var file:File = File.desktopDirectory.resolve("My App v2.air");
var fileStream:FileStream = new FileStream();
fileStream.addEventListener(Event.CLOSE, fileClosed);
fileStream.openAsync(file, FileMode.WRITE);
fileStream.writeBytes(fileData, 0, fileData.length);
fileStream.close();
}
function fileClosed(event:Event):void {
trace("The AIR file is written.");
}
For more information on saving files, see Reading and writing files.
Checking to see if an application is running for the first time
You may want to check to see if an application is running for the first time, so that you can display a "getting started" or "welcome" message upon first run.
One way to do this is to install a file in the application store directory upon initializing the application (for example, when a top-level Flex component dispatches the applicationComplete event). Every time the application starts up, it should check for the existence of that file. If the file does not exist, then the application is running for the first time. If the file exists, the application has already run at least once. If the file exists and contains a version number older than the current version number, then you know the user is running the new version for the first time.
Here is a Flex example:
<?xml version="1.0" encoding="utf-8"?>
<mx:ApolloApplication xmlns:mx="http://www.adobe.com/2006/mxml"
layout="vertical"
title="Sample Version Checker Application"
applicationComplete="init()">
<mx:Script>
<![CDATA[
import flash.filesystem.*;
public var file:File;
public var currentVersion:String = "1.2";
public function init():void {
file = File.appStorageDirectory.resolve("Preferences/version.txt");
trace(file.nativePath);
if(file.exists) {
checkVersion();
} else {
firstRun();
}
}
private function checkVersion():void {
var stream:FileStream = new FileStream();
stream.open(file, FileMode.READ);
var prevVersion:String = stream.readUTFBytes(stream.bytesAvailable);
stream.close();
if (prevVersion != currentVersion) {
log.text = "You have updated to version " + currentVersion + ".\n";
} else {
saveFile();
}
log.text += "Welcome to the application.";
}
private function firstRun():void {
log.text = "Thank you for installing the application. \n"
+ "This is the first time you have run it.";
saveFile();
}
private function saveFile():void {
var stream:FileStream = new FileStream();
stream.open(file, FileMode.WRITE);
stream.writeUTFBytes(currentVersion);
stream.close();
}
]]>
</mx:Script>
<mx:TextArea id="log" width="100%" height="100%" />
</mx:ApolloApplication>
Here is an HTML-based example:
<html>
<head>
<script>
var File = runtime.flash.filesystem.File;
var FileMode = runtime.flash.filesystem.FileMode;
var FileStream = runtime.flash.filesystem.FileStream;
var file;
var currentVersion = "1.2";
function init() {
file = File.appStorageDirectory.resolve("Preferences/version.txt");
runtime.trace(file.nativePath);
if(file.exists) {
checkVersion();
} else {
firstRun();
}
}
function checkVersion() {
var stream = new FileStream();
stream.open(file, FileMode.READ);
var prevVersion = stream.readUTFBytes(stream.bytesAvailable);
stream.close();
if (prevVersion != currentVersion) {
window.document.getElementById("log").innerHTML
= "You have updated to version " + currentVersion + ".\n";
} else {
saveFile();
}
window.document.getElementById("log").innerHTML
+= "Welcome to the application.";
}
function firstRun() {
window.document.getElementById("log").innerHTML
= "Thank you for installing the application. \n"
+ "This is the first time you have run it.";
saveFile();
}
function saveFile() {
var stream = new FileStream();
stream.open(file, FileMode.WRITE);
stream.writeUTFBytes(currentVersion);
stream.close();
}
</script>
</head>
<body onLoad="init()">
<textarea id="log" rows="100%" cols="100%" />
</body>
</html>
Back to: Apollo Documentation home page