Aggiornamento di applicazioni AIR

Informazioni sull'aggiornamento delle applicazioni
Presentazione di un'interfaccia utente di aggiornamento personalizzata di un'applicazione
Scaricamento di un file AIR nel computer dell'utente
Controllo per verificare se un'applicazione viene eseguita per la prima volta
Uso del framework di aggiornamento

Gli utenti possono installare o aggiornare un'applicazione AIR facendo doppio clic su un file AIR sul computer o dal browser (utilizzando la funzionalità di installazione invisibile). Il programma di installazione di Adobe® AIR® gestisce l'installazione e avvisa l'utente se sta tentando di aggiornare un'applicazione esistente

Tuttavia, è anche possibile che un'applicazione installata esegua l'aggiornamento automatico a una nuova versione utilizzando la classe Updater (un'applicazione installata può rilevare che una nuova versione è disponibile per essere scaricata e installata). La classe Updater include un metodo update() che consente di selezionare un file AIR sul computer dell'utente e di eseguire l'aggiornamento a quella versione. Il pacchetto dell'applicazione deve essere creato in formato di file AIR per poter utilizzare la classe Updater. Le applicazioni impacchettate come eseguibili o pacchetti nativi devono utilizzare le funzionalità di aggiornamento fornite dalla piattaforma nativa.

L'ID applicazione e l'ID editore di un file AIR di aggiornamento devono corrispondere all'applicazione da aggiornare. L'ID editore viene ricavato dal certificato di firma. Sia l'aggiornamento che l'applicazione da aggiornare devono essere firmati con lo stesso certificato.

Per AIR 1.5.3 e versioni successive, il file descrittore dell'applicazione include un elemento <publisherID>. È necessario utilizzare questo elemento se esistono versioni dell'applicazione sviluppate con AIR 1.5.2 o versioni precedenti. Per ulteriori informazioni, vedete publisherID.

A partire da AIR 1.1 e versioni successive, potete migrare un'applicazione per utilizzare un nuovo certificato per la firma del codice. La migrazione di un'applicazione per utilizzare una nuova firma implica la firma del file AIR aggiornato con i certificati nuovo e originale. La migrazione del certificato è un processo unidirezionale. Dopo la migrazione, solo i file AIR firmati con il nuovo certificato (o con entrambi i certificati) verranno riconosciuti come aggiornamenti di un'installazione esistente.

La gestione degli aggiornamenti delle applicazioni può essere un'operazione complessa. AIR 1.5 include il nuovo framework di aggiornamento per le applicazioni AdobeAIR. In questo framework sono disponibili le API che consentono agli sviluppatori di includere funzioni di aggiornamento adeguate nelle applicazioni AIR.

Potete usare la migrazione del certificato per passare da un certificato autofirmato a un certificato firmato commerciale o da un certificato autofirmato o commerciale a un altro. Se non eseguite la migrazione del certificato, gli utenti esistenti devono rimuovere la versione corrente dell'applicazione prima di installare la nuova versione. Per ulteriori informazioni, vedete Modifica dei certificati.

È consigliabile includere un meccanismo di aggiornamento nella vostra applicazione. Se create una nuova versione dell'applicazione, questo meccanismo può richiedere all'utente di installare la nuova versione.

Il programma di installazione dell'applicazione AIR crea dei file di registro quando l'applicazione viene installata, aggiornata o rimossa. Potete consultare questi registri per individuare la causa di eventuali problemi di installazione. Vedete Installation logs.

Nota: le nuove versioni del runtime di Adobe AIR possono includere versioni aggiornate di WebKit. Una versione aggiornata di WebKit potrebbe determinare modifiche impreviste nel contenuto HTML di un'applicazione AIR distribuita. In alcuni casi dovrete aggiornare l'applicazione per via di queste modifiche. Un meccanismo di aggiornamento può segnalare all'utente la disponibilità della nuova versione dell'applicazione. Per ulteriori informazioni, vedete Informazioni sull'ambiente HTML (sviluppatori ActionScript) o About the HTML environment (sviluppatori HTML).

Informazioni sull'aggiornamento delle applicazioni

La classe Updater (del pacchetto flash.desktop) include un unico metodo, update(), che può essere utilizzato per aggiornare l'applicazione in esecuzione a una versione diversa. Ad esempio, se l'utente dispone di una versione del file AIR ("Sample_App_v2.air") che si trova sul desktop, il codice seguente aggiorna l'applicazione.

Esempio ActionScript:

var updater:Updater = new Updater(); 
var airFile:File = File.desktopDirectory.resolvePath("Sample_App_v2.air"); 
var version:String = "2.01"; 
updater.update(airFile, version);

Esempio JavaScript:

var updater = new air.Updater(); 
var airFile = air.File.desktopDirectory.resolvePath("Sample_App_v2.air"); 
var version = "2.01"; 
updater.update(airFile, version);

Prima che un'applicazione possa utilizzare la classe Updater, l'utente o l'applicazione deve scaricare la versione aggiornata del file AIR sul computer. Per ulteriori informazioni, consultate Scaricamento di un file AIR nel computer dell'utente.

Risultati della chiamata del metodo Updater.update()

Quando un'applicazione nel runtime chiama il metodo update(), il runtime chiude l'applicazione e quindi tenta di installare la nuova versione dal file AIR. Il runtime controlla che l'ID applicazione e l'ID editore specificati nel file AIR corrispondano a quelli dell'applicazione che chiama il metodo update(). Per informazioni sull'ID applicazione e sull'ID editore, vedete File descrittori delle applicazioni AIR. Il runtime controlla, inoltre, che la stringa della versione corrisponda alla stringa version passata al metodo update(). Se l'installazione viene effettuata correttamente, il runtime apre la nuova versione dell'applicazione. In caso contrario, viene riaperta la versione esistente (preinstallazione) dell'applicazione.

In Mac OS, per installare una versione aggiornata di un'applicazione, l'utente deve disporre dei privilegi di sistema appropriati per l'installazione nella directory dell'applicazione. In Windows e Linux, sono richiesti privilegi di amministratore.

Se la versione aggiornata dell'applicazione richiede una versione aggiornata del runtime, viene installata la nuova versione runtime. Per aggiornare il runtime, l'utente deve disporre dei privilegi amministrativi per il computer in uso.

Durante il test di un'applicazione mediante ADL, una chiamata al metodo update() determina un'eccezione di runtime.

Informazioni sulla stringa della versione

La stringa specificata come parametro version del metodo update() deve corrispondere alla stringa nell'elemento version o versionNumber del file descrittore dell'applicazione per il file AIR da installare. L'indicazione del parametro version è richiesta per motivi di sicurezza. Richiedendo all'applicazione di verificare il numero di versione nel file AIR, l'applicazione evita di installare inavvertitamente una versione vecchia, che potrebbe contenere vulnerabilità di sicurezza successivamente risolte. L'applicazione deve anche confrontare la stringa della versione nel file AIR con quella nell'applicazione installata per evitare attacchi di downgrade.

Prima di AIR 2.5, la stringa di versione può essere in qualsiasi formato. Può essere, ad esempio, "2.01" o "versione 2". A partire da AIR 2.5, la stringa di versione deve essere una sequenza composta da fino a tre serie con un massimo di tre cifre ciascuna, separate da punti. Ad esempio, “.0", "1.0" e "67.89.999" sono tutti numeri di versione validi. Dovete convalidare la stringa della versione di aggiornamento prima di aggiornare l'applicazione.

Se un'applicazione Adobe AIR scarica un file AIR tramite il Web, è opportuno disporre di un meccanismo che consente al servizio Web di inviare una notifica riguardo la versione scaricata. L'applicazione può quindi utilizzare questa stringa come parametro version del metodo update(). Se il file AIR file è ottenuto in modo diverso e la versione del file AIR non è nota, l'applicazione AIR può esaminare il file AIR per determinare la versione (un file AIR è un archivio compresso in formato ZIP e il file descrittore dell'applicazione è il secondo record nell'archivio).

Per ulteriori informazioni sul file descrittore dell'applicazione, consultate File descrittori delle applicazioni AIR.

Flusso di lavoro di firma per gli aggiornamenti delle applicazioni

La pubblicazione di aggiornamenti ad-hoc complica il compito di gestire più versioni delle applicazioni e le date di scadenza dei relativi certificati. I certificati potrebbero infatti scadere prima che possiate pubblicare un aggiornamento.

Il runtime Adobe AIR tratta un aggiornamento di un'applicazione pubblicato senza una firma di migrazione come se fosse una nuova applicazione. Gli utenti devono quindi disinstallare l'applicazione AIR corrente per poter installare l'aggiornamento.

Per risolvere il problema, caricate ogni applicazione aggiornata con il certificato più recente su un URL di distribuzione distinto. Includete un meccanismo che vi ricordi di applicare firme di migrazione quando il certificato entra nel periodo di tolleranza di 180 giorni. Vedete Firma di una versione aggiornata di un'applicazione AIR per ulteriori informazioni.

Vedete Comandi ADT per informazioni su come applicare le firme.

Effettuate le seguenti operazioni per semplificare il processo di applicazione delle firme di migrazione:

Caricate ogni applicazione aggiornata su un URL di distribuzione distinto.
Caricate sullo stesso URL il file XML descrittore dell'aggiornamento e il certificato più recente.
Firmate l'applicazione aggiornate con il certificato più recente.
Applicate una firma di migrazione all'applicazione aggiornata con il certificato utilizzato per firmare la versione precedente caricata su un URL diverso.

Presentazione di un'interfaccia utente di aggiornamento personalizzata di un'applicazione

AIR include un'interfaccia di aggiornamento predefinita:

Visualizzazione dell’elemento grafico a dimensioni intere

Questa interfaccia è sempre utilizzata la prima volta che un utente installa una versione dell'applicazione su una macchina. Tuttavia, potete definire un'interfaccia personalizzata da utilizzare per istanze successive. Se nell'applicazione è definita un'interfaccia di aggiornamento personalizzata, specificate un elemento customUpdateUI nel file descrittore dell'applicazione per l'applicazione attualmente installata:

<customUpdateUI>true</customUpdateUI>

Quando l'applicazione è installata e l'utente apre un file AIR con un ID applicazione e un ID editore che corrispondono all'applicazione installata, il runtime apre l'applicazione, anziché il programma di installazione dell'applicazione AIR predefinita. Per ulteriori informazioni, vedete customUpdateUI.

L'applicazione può decidere, quando viene eseguita (quando l'oggetto NativeApplication.nativeApplication invia un evento load), se aggiornare l'applicazione (utilizzando la classe Updater). Se decide di eseguire l'aggiornamento, può presentare all'utente la propria interfaccia di installazione (che è diversa dall'interfaccia di esecuzione standard).

Scaricamento di un file AIR nel computer dell'utente

Per utilizzare la classe Updater, l'utente o l'applicazione deve prima salvare un file AIR localmente sul computer dell'utente.

Nota: in AIR 1.5 è incluso un framework di aggiornamento che consente agli sviluppatori di includere funzioni di aggiornamento adeguate nelle applicazioni AIR. L'uso di questo framework può risultare molto più facile rispetto all'uso diretto del metodo update() della classe Update. Per ulteriori dettagli, consultate Uso del framework di aggiornamento.

Il codice seguente legge un file AIR da un URL (http://example.com/air/updates/Sample_App_v2.air) e salva il file AIR nella directory di memorizzazione dell'applicazione.

Esempio ActionScript:

var urlString:String = "http://example.com/air/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 { 
    urlStream.readBytes(fileData, 0, urlStream.bytesAvailable); 
    writeAirFile(); 
} 
 
function writeAirFile():void { 
    var file:File = File.applicationStorageDirectory.resolvePath("My App v2.air"); 
    var fileStream:FileStream = new FileStream(); 
    fileStream.open(file, FileMode.WRITE); 
    fileStream.writeBytes(fileData, 0, fileData.length); 
    fileStream.close(); 
    trace("The AIR file is written."); 
}

Esempio JavaScript:

var urlString = "http://example.com/air/updates/Sample_App_v2.air"; 
var urlReq = new air.URLRequest(urlString); 
var urlStream = new air.URLStream(); 
var fileData = new air.ByteArray(); 
urlStream.addEventListener(air.Event.COMPLETE, loaded); 
urlStream.load(urlReq); 
 
function loaded(event) { 
    urlStream.readBytes(fileData, 0, urlStream.bytesAvailable); 
    writeAirFile(); 
} 
 
function writeAirFile() { 
    var file = air.File.desktopDirectory.resolvePath("My App v2.air"); 
    var fileStream = new air.FileStream(); 
    fileStream.open(file, air.FileMode.WRITE); 
    fileStream.writeBytes(fileData, 0, fileData.length); 
    fileStream.close(); 
    trace("The AIR file is written."); 
}

Per ulteriori informazioni, vedete:

Flusso di lavoro per lettura e scrittura di file (sviluppatori ActionScript)
Workflow for reading and writing files (sviluppatori HTML)

Controllo per verificare se un'applicazione viene eseguita per la prima volta

Dopo aver completato l'aggiornamento di un'applicazione, potete inviare all'utente un messaggio "operazioni preliminari" o "benvenuto". All'avvio, l'applicazione esegue un controllo per verificare se è la prima volta che viene eseguita, in modo da poter determinare se visualizzare il messaggio.

Nota: in AIR 1.5 è incluso un framework di aggiornamento che consente agli sviluppatori di includere funzioni di aggiornamento adeguate nelle applicazioni AIR. Questo framework fornisce dei metodi semplici per controllare se una versione di un'applicazione viene eseguita per la prima volta. Per ulteriori dettagli, consultate Uso del framework di aggiornamento.

Un modo per eseguire questa operazione è salvare un file nella directory di memorizzazione dell'applicazione durante l'inizializzazione dell'applicazione. A ogni avvio dell'applicazione, è necessario verificare l'esistenza di questo file. Se il file non esiste, allora è la prima volta che l'applicazione è in esecuzione per l'utente corrente. Se il file esiste, l'applicazione è stata già eseguita almeno una volta. Se il file esiste e contiene un numero di versione precedente a quello corrente, allora è la prima volta che l'utente esegue la nuova versione.

Nell'esempio seguente di Flex viene dimostrato il concetto:

<?xml version="1.0" encoding="utf-8"?> 
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml"  
    layout="vertical"  
    title="Sample Version Checker Application" 
    applicationComplete="system extension()"> 
    <mx:Script> 
        <![CDATA[ 
            import flash.filesystem.*; 
            public var file:File; 
            public var currentVersion:String = "1.2"; 
            public function system extension():void { 
                file = File.applicationStorageDirectory; 
                file = file.resolvePath("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 reversion:String = stream.readUTFBytes(stream.bytesAvailable); 
                stream.close(); 
                if (reversion != 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:WindowedApplication>

Il seguente esempio dimostra il concetto in JavaScript:

<html> 
    <head> 
        <script src="AIRAliases.js" /> 
        <script> 
            var file; 
            var currentVersion = "1.2"; 
            function system extension() { 
                file = air.File.appStorageDirectory.resolvePath("Preferences/version.txt"); 
                air.trace(file.nativePath); 
                if(file.exists) { 
                    checkVersion(); 
                } else { 
                    firstRun(); 
                } 
            } 
            function checkVersion() { 
                var stream = new air.FileStream(); 
                stream.open(file, air.FileMode.READ); 
                var reversion = stream.readUTFBytes(stream.bytesAvailable); 
                stream.close(); 
                if (reversion != 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 air.FileStream(); 
                stream.open(file, air.FileMode.WRITE); 
                stream.writeUTFBytes(currentVersion); 
                stream.close(); 
            } 
        </script> 
    </head> 
    <body onLoad="system extension()"> 
        <textarea ID="log" rows="100%" cols="100%" /> 
    </body> 
</html>

Se l'applicazione salva i dati localmente (ad esempio, nella directory di memorizzazione dell'applicazione), è opportuno verificare la presenza di eventuali dati salvati (dalle versioni precedenti) al momento del primo avvio.

Uso del framework di aggiornamento

La gestione degli aggiornamenti delle applicazioni può essere un'operazione laboriosa. Il framework di aggiornamento per applicazioni AdobeAIRfornisce delle API che permettono agli sviluppatori di integrare solide funzionalità di aggiornamento nelle applicazioni AIR. framework di aggiornamento AIR effettua le seguenti operazioni per gli sviluppatori:

Controllare regolarmente la disponibilità di aggiornamenti in base a un intervallo di tempo prestabilito o alle richieste degli utenti
Scaricare i file AIR (aggiornamenti) da un'origine Web
Avvisare l'utente alla prima esecuzione di una nuova versione installata
Verificare che l'utente desidera controllare la disponibilità di aggiornamenti
Visualizzare all'utente informazioni relative alla nuova versione di aggiornamento
Visualizzazione all'utente informazioni sull'avanzamento del download e sugli eventuali errori

Nel framework di aggiornamento di AIR è disponibile un'interfaccia utente di esempio che potete usare per la vostra applicazione. Fornisce all'utente le informazioni di base e le opzioni di configurazione relative agli aggiornamenti dell'applicazione. Nell'applicazione potete anche definire un'interfaccia utente personalizzata da usare con il framework di aggiornamento.

Il framework di aggiornamento di AIR consente di archiviare le informazioni relative alla versione di aggiornamento di un'applicazione AIR in semplici file di configurazione XML. Per la maggior parte delle applicazioni, l'impostazione di questi file di configurazione con l'inclusione di codice di base fornisce all'utente delle buone funzionalità di aggiornamento.

Anche senza utilizzare il framework di aggiornamento, Adobe AIR include una classe Updater che può essere usata dalle applicazioni AIR per l'aggiornamento alle nuove versioni. La classe Updater consente l'aggiornamento di un'applicazione a una versione contenuta in un file AIR sul computer dell'utente. La gestione degli aggiornamenti può tuttavia comportare operazioni più complesse del semplice aggiornamento di un'applicazione basato su un file AIR archiviato localmente.

File del framework di aggiornamento di AIR

Il framework di aggiornamento di AIR si trova nella directory frameworks/libs/air dell'SDK di AIR 2 e comprende i seguenti file:

applicationupdater.swc - Definisce la funzionalità di base della libreria di aggiornamenti (da utilizzare in ActionScript). Questa versione non contiene alcuna interfaccia utente.
applicationupdater.swf - Definisce la funzionalità di base della libreria di aggiornamenti (da utilizzare in JavaScript). Questa versione non contiene alcuna interfaccia utente.
applicationupdater_ui.swc - Definisce una versione Flex 4 della funzionalità di base della libreria di aggiornamenti, includendo un'interfaccia utente che può essere usata dall'applicazione per visualizzare le opzioni di aggiornamento.
applicationupdater_ui.swf - Definisce una versione JavaScript della funzionalità di base della libreria di aggiornamenti, includendo un'interfaccia utente che può essere usata dall'applicazione per visualizzare le opzioni di aggiornamento.

Per ulteriori informazioni, vedete le seguenti sezioni:

Impostazione dell'ambiente di sviluppo Flex

I file SWC contenuti nella directory frameworks/libs/air dell'SDK di AIR 2 definiscono le classi che potete utilizzare per lo sviluppo in Flex e in Flash.

Per usare il framework di aggiornamento quando effettuate la compilazione con Flex SDK, includete il file ApplicationUpdater.swc o ApplicationUpdater_UI.swc nella chiamata al compilatore amxmlc. Nell'esempio riportato di seguito, il compilatore carica il file ApplicationUpdater.swc nella sottodirectory lib della directory Flex SDK:

amxmlc -library-path+=lib/ApplicationUpdater.swc  -- myApp.mxml

Nell'esempio riportato di seguito, il compilatore carica il file ApplicationUpdater_UI.swc nella sottodirectory lib della directory Flex SDK:

amxmlc -library-path+=lib/ApplicationUpdater_UI.swc  -- myApp.mxml

Quando sviluppate un'applicazione con Flash Builder, aggiungete il file SWC nella scheda relativa al percorso della libreria nelle impostazioni del percorso di Flex Builder nella finestra di dialogo delle proprietà.

Assicuratevi di copiare i file SWC nella directory a cui farete riferimento nel compilatore amxmlc (usando Flex SDK) o in Flash Builder.

Inclusione dei file del framework in un'applicazione AIR basata su HTML

Nella directory frameworks/html del framework di aggiornamento sono inclusi i seguenti file SWF:

applicationupdater.swf - Definisce la funzionalità di base della libreria di aggiornamenti, senza interfaccia utente
applicationupdater_ui.swf - Definisce la funzionalità di base della libreria di aggiornamenti, includendo un'interfaccia utente che può essere usata dall'applicazione per visualizzare le opzioni di aggiornamento

Il codice JavaScript nelle applicazioni AIR può usare le classi definite nei file SWF.

Per usare il framework di aggiornamento, includete il file applicationupdater.swf o applicationupdater_ui.swf nella directory (o in una sottodirectory) dell'applicazione. Quindi, nel file HTML che userà il framework (nel codice JavaScript), includete un tag script che carica il file:

<script src="applicationUpdater.swf" type="application/x-shockwave-flash"/>

In alternativa, usate questo tag script per caricare il file applicationupdater_ui.swf:

<script src="applicationupdater_ui.swf" type="application/x-shockwave-flash"/>

L'API definita in questi due file viene descritta nella parte rimanente di questo documento.

Esempio di base: Uso della versione ApplicationUpdaterUI

La versione ApplicationUpdaterUI del framework di aggiornamento fornisce un'interfaccia di base che potete usare facilmente nella vostra applicazione. Di seguito è riportato un esempio di base.

Create innanzitutto un'applicazione AIR che chiama il framework di aggiornamento:

Se la vostra applicazione è un'applicazione AIR basata su HTML, caricate il file applicationupdaterui.swf:
```
<script src="ApplicationUpdater_UI.swf" type="application/x-shockwave-flash"/>
```
Nella logica della vostra applicazione AIR, create un'istanza dell'oggetto ApplicationUpdaterUI.

In ActionScript, usate il seguente codice:
```
var appUpdater:ApplicationUpdaterUI = new ApplicationUpdaterUI(); 
```
In JavaScript, usate il seguente codice:
```
var appUpdater = new runtime.air.update.ApplicationUpdaterUI(); 
```
Potete aggiungere questo codice a una funzione di inizializzazione che viene eseguita dopo il caricamento dell'applicazione.
Create un file di testo denominato updateConfig.xml e aggiungetevi quanto riportato di seguito:
```
<?xml version="1.0" encoding="utf-8"?> 
<configuration xmlns="http://ns.adobe.com/air/framework/update/configuration/1.0"> 
     <url>http://example.com/updates/update.xml</url> 
    <delay>1</delay> 
</configuration>
```
Modificate l'elemento URL del file updateConfig.xml in modo che corrisponda alla posizione finale del file descrittore dell'aggiornamento sul server Web (consultate la procedura successiva).

Il valore delay è il numero di giorni che l'applicazione attende prima di controllare se sono presenti aggiornamenti.
Aggiungete il file updateConfig.xml alla directory project dell'applicazione AIR.
Impostate l'oggetto updater in modo che faccia riferimento al file updateConfig.xml e chiamate il metodo initialize() dell'oggetto.
In ActionScript, usate il seguente codice:
```
appUpdater.configurationFile = new File("app:/updateConfig.xml"); 
appUpdater.initialize();
```
In JavaScript, usate il seguente codice:
```
appUpdater.configurationFile = new air.File("app:/updateConfig.xml"); 
appUpdater.initialize();
```
Create una seconda versione dell'applicazione AIR con una versione diversa rispetto alla prima applicazione. (La versione è specificata nel file descrittore dell'applicazione, nell'elemento version).

Aggiungete quindi la versione di aggiornamento dell'applicazione AIR al server Web:

Copiate la versione di aggiornamento del file AIR sul server Web.
Create un file di testo denominato updateDescriptor.2.5.xml e aggiungetevi il contenuto riportato di seguito:
```
<?xml version="1.0" encoding="utf-8"?> 
     <update xmlns="http://ns.adobe.com/air/framework/update/description/2.5"> 
       <versionNumber>1.1</versionNumber> 
       <url>http://example.com/updates/sample_1.1.air</url> 
       <description>This is the latest version of the Sample application.</description> 
    </update>
```
Modificate gli elementi versionNumber, URL e description del file updateDescriptor.xml in modo che corrispondano al file AIR di aggiornamento. Questo formato del descrittore di aggiornamento viene utilizzato dalle applicazioni che usano il framework di aggiornamento incluso in AIR 2.5 SDK (e versioni successive).
Create un file di testo denominato updateDescriptor.1.0.xml e aggiungetevi il contenuto riportato di seguito:
```
<?xml version="1.0" encoding="utf-8"?> 
     <update xmlns="http://ns.adobe.com/air/framework/update/description/1.0"> 
       <version>1.1</version> 
       <url>http://example.com/updates/sample_1.1.air</url> 
       <description>This is the latest version of the Sample application.</description> 
    </update>
```
Modificate gli elementi version, URL e description del file updateDescriptor.xml in modo che corrispondano al file AIR di aggiornamento. Questo formato del descrittore di aggiornamento viene utilizzato dalle applicazioni che usano il framework di aggiornamento incluso in AIR 2 SDK (e versioni precedenti).

Nota: è necessario creare questo secondo file descrittore di aggiornamento solo se dovete supportare gli aggiornamenti ad applicazioni create prima di AIR 2.5.
Aggiungete i file updateDescriptor.2.5.xml e updateDescriptor.1.0.xml alla stessa directory del server web che contiene il file AIR di aggiornamento.

Questo è un esempio di base che tuttavia fornisce una funzionalità di aggiornamento sufficiente per molte applicazioni. Nella parte restante di questo documento viene descritto come utilizzare il framework di aggiornamento per soddisfare le vostre esigenze specifiche.

Per guardare un altro esempio di utilizzo del framework di aggiornamento, vedere le seguenti applicazioni di esempio in Adobe AIR Developer Center:

Framework di aggiornamento in un'applicazione Flex (http://www.adobe.com/go/learn_air_qs_update_framework_flex_it)
Framework di aggiornamento in un'applicazione Flash (http://www.adobe.com/go/learn_air_qs_update_framework_flash_it)
Framework di aggiornamento in un'applicazione HTML (http://www.adobe.com/go/learn_air_qs_update_framework_html_it)

Aggiornamento ad AIR 2.5

Poiché le regole per assegnare numeri di versione alle applicazioni sono cambiate in AIR 2.5, il framework di aggiornamento AIR non è in grado di analizzare le informazioni di versione di un descrittore AIR 2.5. Questa incompatibilità comporta la necessità di aggiornare l'applicazione utilizzando il nuovo framework di aggiornamento PRIMA di aggiornare l'applicazione per l'uso di AIR 2.5 SDK. In altre parole, l'aggiornamento dell'applicazione ad AIR 2.5 o successivo da qualunque versione di AIR precedente alla 2.5 richiede in realtà DUE aggiornamenti. Il primo aggiornamento deve usare lo spazio dei nomi AIR 2 e includere la libreria del framework di aggiornamento AIR 2.5 (potete comunque creare il pacchetto dell'applicazione utilizzando AIR 2.5 SDK). Per il secondo aggiornare potete usare lo spazio dei nomi AIR 2.5 e includere le nuove funzioni dell'applicazione.

Potete inoltre fare in modo che l'aggiornamento intermedio non abbia alcun effetto oltre a quello di aggiornare l'applicazione AIR 2.5 utilizzando direttamente la classe AIR Updater.

L'esempio seguente mostra come aggiornare un'applicazione dalla versione 1.0 a 2.0. La versione 1.0 usa il vecchio spazio dei nomi 2.0. La versione 2.0 usa invece lo spazio dei nomi 2.5 e include nuove funzioni implementate con le API AIR 2.5.

Create una versione intermedia dell'applicazione (1.0.1), basata sulla versione 1.0.
1. Usate il framework Application Updater di AIR 2.5 per creare l'applicazione.
  
  Nota: utilizzate applicationupdater.swc o applicationupdater_ui.swc per le applicazioni AIR basate sulla tecnologia Flash e applicationupdater.swf o applicationupdater_ui.swf per quelle basate su HTML.
2. Create un file descrittore di aggiornamento per la versione 1.0.1 utilizzando il vecchio spazio dei nomi e la versione così come nell'esempio seguente:
```
<?xml version="1.0" encoding="utf-8"?> 
    <update xmlns="http://ns.adobe.com/air/framework/update/description/2.0"> 
        <version>1.0.1</version> 
        <url>http://example.com/updates/sample_1.0.1.air</url> 
        <description>This is the intermediate version.</description> 
    </update>
```
Create la versione 2.0 dell'applicazione che utilizza le API AIR 2.5 e lo spazio dei nomi 2.5.
Create un descrittore di aggiornamento per aggiornare l'applicazione dalla versione 1.0.1 alla versione 2.0.

<?xml version="1.0" encoding="utf-8"?> 
    <update xmlns="http://ns.adobe.com/air/framework/update/description/2.5"> 
        <version>2.0</version> 
        <url>http://example.com/updates/sample_2.0.air</url> 
        <description>This is the intermediate version.</description> 
    </update>

Definizione dei file descrittori dell'aggiornamento e aggiunta del file AIR al server Web

Quando usate il framework di aggiornamento di AIR, definite le informazioni di base sull'aggiornamento disponibile nei file descrittori dell'aggiornamento archiviati sul server Web. Un file descrittore dell'aggiornamento è un semplice file XML. Il framework di aggiornamento incluso nell'applicazione controlla questo file per verificare se è stata caricata una nuova versione.

Il formato del file descrittore dell'aggiornamento è cambiato in AIR 2.5. Il nuovo formato usa uno spazio dei nomi diverso. Lo spazio dei nomi originale è "http://ns.adobe.com/air/framework/update/description/1.0". Lo spazio dei nomi AIR 2.5 è "http://ns.adobe.com/air/framework/update/description/2.5".

Le applicazioni AIR create prima di AIR 2.5 possono leggere solo la versione 1.0 del descrittore di aggiornamento. Le applicazioni AIR create con il framework di aggiornamento incluso in AIR 2.5 o successivo possono leggere solo la versione 2.5 del descrittore di aggiornamento. A causa di questa incompatibilità tra versioni, spesso è necessario creare due file descrittori di aggiornamento. La logica di aggiornamento nelle versioni AIR 2.5 dell'applicazione deve scaricare un descrittore di aggiornamento che utilizza il nuovo formato, mentre le versioni dell'applicazione AIR devono continuare a utilizzare il formato originale. Entrambi i file devono essere modificati per ogni aggiornamento che rilascerete (finché non cesserete di supportare le versioni create prima di AIR 2.5).

Il file descrittore dell'aggiornamento contiene i seguenti dati:

versionNumber - La nuova versione dell'applicazione AIR. Usate l'elemento versionNumber nei descrittori di aggiornamento utilizzati per aggiornare le applicazioni AIR 2.5. Il valore deve corrispondere alla stringa inclusa nell'elemento versionNumber del nuovo file descrittore dell'applicazione AIR. Se il numero di versione nel file descrittore dell'applicazione non corrisponde a quello del file AIR di aggiornamento, il framework di aggiornamento genera un'eccezione.
version - La nuova versione dell'applicazione AIR. Usate l'elemento version nei descrittori di aggiornamento utilizzati per aggiornare le applicazioni create prima di AIR 2.5. Il valore deve corrispondere alla stringa inclusa nell'elemento version del nuovo file descrittore dell'applicazione AIR. Se la versione nel file descrittore dell'applicazione non corrisponde alla versione del file AIR di aggiornamento, il framework di aggiornamento genera un'eccezione.
versionLabel - La stringa di versione in formato leggibile all'uomo da visualizzare agli utenti. versionLabel è opzionale, ma può essere specificato solo nei file descrittori di aggiornamento 2.5 o successivi. Utilizzatelo se specificate anche l'elemento versionLabel nel descrittore dell'applicazione e impostatelo sullo stesso valore.
url - La posizione del file AIR di aggiornamento. Si tratta del file che contiene la versione di aggiornamento dell'applicazione AIR.
description - Dettagli relativi alla nuova versione. Queste informazioni possono essere visualizzate all'utente durante il processo di aggiornamento.

Gli elementi version e url sono obbligatori. L'elemento description è opzionale.

Di seguito è riportato un esempio di file descrittore dell'aggiornamento in versione 2.5:

<?xml version="1.0" encoding="utf-8"?> 
     <update xmlns="http://ns.adobe.com/air/framework/update/description/2.5"> 
       <versionNumber>1.1.1</versionNumber> 
       <url>http://example.com/updates/sample_1.1.1.air</url> 
       <description>This is the latest version of the Sample application.</description> 
    </update>

E questo è un esempio di file descrittore dell'aggiornamento in versione 1.0:

<?xml version="1.0" encoding="utf-8"?> 
     <update xmlns="http://ns.adobe.com/air/framework/update/description/1.0"> 
       <version>1.1.1</version> 
       <url>http://example.com/updates/sample_1.1.1.air</url> 
       <description>This is the latest version of the Sample application.</description> 
    </update>

Se desiderate definire il tag description in più lingue, usate più elementi text che definiscono un attributo lang:

<?xml version="1.0" encoding="utf-8"?> 
     <update xmlns="http://ns.adobe.com/air/framework/update/description/2.5"> 
       <versionNumber>1.1.1</versionNumber> 
       <url>http://example.com/updates/sample_1.1.1.air</url> 
       <description> 
           <text xml:lang="en">English description</text> 
           <text xml:lang="fr">French description</text> 
           <text xml:lang="ro">Romanian description</text> 
       </description> 
    </update>

Copiate il file descrittore dell'aggiornamento, insieme al file AIR di aggiornamento, sul server Web.

Nella directory templates inclusa nel descrittore dell'aggiornamento sono disponibili esempi di file descrittori dell'aggiornamento. Sono incluse versioni sia monolingua che multilingua.

Creazione di un'istanza di un oggetto updater

Dopo avere caricato il framework di aggiornamento di AIR nel codice (consultate Impostazione dell'ambiente di sviluppo Flex e Inclusione dei file del framework in un'applicazione AIR basata su HTML), dovete creare un'istanza di un oggetto updater, come nell'esempio seguente.

Esempio ActionScript:

var appUpdater:ApplicationUpdater = new ApplicationUpdater();

Esempio JavaScript:

var appUpdater = new runtime.air.update.ApplicationUpdater();

Nel codice precedente viene usata la classe ApplicationUpdater (che non fornisce un'interfaccia utente). Se desiderate usare la classe ApplicationUpdaterUI (che fornisce un'interfaccia utente), usate quanto segue.

Esempio ActionScript:

var appUpdater:ApplicationUpdaterUI = new ApplicationUpdaterUI();

Esempio JavaScript:

var appUpdater = new runtime.air.update.ApplicationUpdaterUI();

Negli altri esempi di codice presenti in questo documento si presuppone che abbiate creato un'istanza di un oggetto updater denominato appUpdater.

Configurazione delle impostazioni di aggiornamento

Potete configurare sia ApplicationUpdater che ApplicationUpdaterUI tramite un file di configurazione fornito con l'applicazione oppure tramite ActionScript o JavaScript nell'applicazione.

Definizione delle impostazioni di aggiornamento in un file di configurazione XML

Il file di configurazione dell'aggiornamento è un file in formato XML che può contenere i seguenti elementi:

updateURL - Un oggetto String, che rappresenta la posizione del descrittore dell'aggiornamento sul server remoto. È consentita qualsiasi posizione URLRequest valida. Dovete definire la proprietà updateURL tramite il file di configurazione oppure tramite uno script (consultate Definizione dei file descrittori dell'aggiornamento e aggiunta del file AIR al server Web). Questa proprietà deve essere definita prima di usare l'oggetto updater (prima di chiamare il metodo initialize() dell'oggetto updater, descritto inInizializzazione del framework di aggiornamento).
delay - Un numero che rappresenta un intervallo di tempo espresso in giorni (sono consentiti valori come 0.25) per il controllo degli aggiornamenti. Un valore 0 (che corrisponde al valore predefinito) specifica che l'oggetto updater non esegue automaticamente un controllo periodico.

Il file di configurazione per ApplicationUpdaterUI può contenere il seguente elemento, oltre agli elementi updateURL e delay:

defaultUI: un elenco di elementi dialog. Ogni elemento dialog ha un attributo name che corrisponde alla finestra di dialogo nell'interfaccia utente. Ogni elemento dialog ha un attributo visible che definisce se la finestra di dialogo è visibile. Il valore predefinito è true. di seguito sono riportati i possibili valori per l'attributo name:
- "checkForUpdate" - Corrisponde alle finestre di dialogo Check for Update, No Update e Update Error (Verifica disponibilità aggiornamenti, Nessun aggiornamento ed Errore durante l'aggiornamento)
- "downloadUpdate" - Corrisponde alla finestra di dialogo Download Update (Scarica aggiornamento)
- "downloadProgress" - Corrisponde alle finestre di dialogo Download Progress e Download Error (Stato scaricamento ed Errore durante lo scaricamento)
- "installUpdate" - Corrisponde alla finestra di dialogo Install Update (Installa aggiornamento)
- "fileUpdate" - Corrisponde alle finestre di dialogo File Update, File No Update e File Error (Aggiornamento file, Nessun aggiornamento del file ed Errore del file)
"unexpectedError" - Corrisponde alla finestra di dialogo Unexpected Error (Errore imprevisto)

Quando è impostato su false, la finestra di dialogo corrispondente non viene visualizzata durante la procedura di aggiornamento.

Di seguito è riportato un esempio del file di configurazione per il framework ApplicationUpdater:

<?xml version="1.0" encoding="utf-8"?> 
<configuration xmlns="http://ns.adobe.com/air/framework/update/configuration/1.0"> 
      <url>http://example.com/updates/update.xml</url> 
      <delay>1</delay> 
</configuration>

Di seguito è riportato un esempio del file di configurazione per il framework ApplicationUpdaterUI, che include una definizione per l'elemento defaultUI:

<?xml version="1.0" encoding="utf-8"?> 
<configuration xmlns="http://ns.adobe.com/air/framework/update/configuration/1.0"> 
      <url>http://example.com/updates/update.xml</url> 
      <delay>1</delay> 
      <defaultUI> 
         <dialog name="checkForUpdate" visible="false" /> 
         <dialog name="downloadUpdate" visible="false" /> 
         <dialog name="downloadProgress" visible="false" /> 
      </defaultUI> 
</configuration>

Puntate la proprietà configurationFile verso la posizione di quel file:

Esempio ActionScript:

appUpdater.configurationFile = new File("app:/cfg/updateConfig.xml");

Esempio JavaScript:

appUpdater.configurationFile = new air.File("app:/cfg/updateConfig.xml");

Nella directory templates del framework di aggiornamento è incluso il file di configurazione di esempio config-template.xml.

Definizione delle impostazioni di aggiornamento nel codice ActionScript o JavaScript

Questi parametri di configurazione possono essere impostati anche usando il codice nell'applicazione, come nell'esempio seguente:

appUpdater.updateURL = " http://example.com/updates/update.xml"; 
appUpdater.delay = 1;

Le proprietà dell'oggetto updater sono updateURL e delay. Queste proprietà definiscono le stesse impostazioni degli elementi updateURL e delay nel file di configurazione: l'URL del file descrittore dell'aggiornamento e l'intervallo per il controllo degli aggiornamenti. Se specificate un file di configurazione e le impostazioni nel codice, le proprietà impostate usando il codice hanno la precedenza sulle impostazioni corrispondenti nel file di configurazione.

Dovete definire la proprietà updateURL tramite il file di configurazione oppure tramite uno script (consultate Definizione dei file descrittori dell'aggiornamento e aggiunta del file AIR al server Web), prima di utilizzare l'oggetto updater (prima di chiamare il metodo initialize() dell'oggetto updater, descritto in Inizializzazione del framework di aggiornamento).

Il framework ApplicationUpdaterUI definisce queste proprietà aggiuntive dell'oggetto updater:

isCheckForUpdateVisible - Corrisponde alle finestre di dialogo Check for Update, No Update e Update Error (Verifica disponibilità aggiornamenti, Nessun aggiornamento ed Errore durante l'aggiornamento)
isDownloadUpdateVisible - Corrisponde alla finestra di dialogo Download Update (Scarica aggiornamento)
isDownloadProgressVisible - Corrisponde alle finestre di dialogo Download Progress e Download Error (Stato scaricamento ed Errore durante lo scaricamento)
isInstallUpdateVisible - Corrisponde alla finestra di dialogo Install Update (Installa aggiornamento)
isFileUpdateVisible - Corrisponde alle finestre di dialogo File Update, File No Update e File Error (Aggiornamento file, Nessun aggiornamento del file ed Errore del file)
isUnexpectedErrorVisible - Corrisponde alla finestra di dialogo Unexpected Error (Errore imprevisto)

Ogni proprietà corrisponde a una o più finestre di dialogo nell'interfaccia utente ApplicationUpdaterUI. Ogni proprietà è un valore booleano, con un valore predefinito true. Quando è impostato su false, le finestre di dialogo corrispondenti non vengono visualizzate durante la procedura di aggiornamento.

Queste proprietà delle finestre di dialogo hanno la precedenza sulle impostazioni nel file di configurazione dell'aggiornamento.

Processo di aggiornamento

Il framework di aggiornamento di AIR completa il processo di aggiornamento nei seguenti passaggi:

L'inizializzazione dell'oggetto updater verifica se è stato effettuato un controllo per rilevare la presenza di un aggiornamento entro l'intervallo di tempo definito (consultate Configurazione delle impostazioni di aggiornamento). Se è previsto un controllo dell'aggiornamento, il processo continua.
L'oggetto updater scarica e interpreta il file descrittore dell'aggiornamento.
L'oggetto updater scarica il file AIR di aggiornamento.
L'oggetto updater installa la versione aggiornata dell'applicazione.

L'oggetto updater invia degli eventi al completamento di ognuno di questi passaggi. Nella versione ApplicationUpdater, potete annullare gli eventi che indicano l'avvenuto completamento di un passaggio del processo. Se annullate uno di questi eventi, il passaggio successivo del processo viene annullato. Nella versione ApplicationUpdaterUI, l'oggetto updater presenta una finestra di dialogo che consente all'utente di annullare ogni singolo passaggio del processo o di procedere.

Se annullate l'evento, potete chiamare i metodi dell'oggetto updater per riprendere il processo.

Mentre la versione ApplicationUpdater procede nel processo di aggiornamento, registra il relativo stato corrente nella proprietà currentState. Questa proprietà è impostata su una stringa con i seguenti valori possibili:

"UNINITIALIZED" - L'oggetto updater non è stato inizializzato.
"INITIALIZING" - L'oggetto updater è in corso di inizializzazione.
"READY" - L'oggetto updater è stato inizializzato.
"BEFORE_CHECKING" - L'oggetto updater non ha ancora effettuato la verifica del file descrittore dell'aggiornamento.
"CHECKING" - L'oggetto updater sta effettuando la verifica del file descrittore dell'applicazione.
"AVAILABLE" - Il file descrittore di updater è disponibile.
"DOWNLOADING" - L'oggetto updater sta scaricando il file AIR.
"DOWNLOADED" - L'oggetto updater ha scaricato il file AIR.
"INSTALLING" - L'oggetto updater sta installando il file AIR.
"PENDING_INSTALLING" - L'oggetto updater ha effettuato l'inizializzazione e vi sono aggiornamenti in sospeso.

Alcuni metodi dell'oggetto updater vengono eseguiti solo in presenza di un determinato stato dell'oggetto stesso.

Inizializzazione del framework di aggiornamento

Dopo l'impostazione delle proprietà di configurazione (consultateEsempio di base: Uso della versione ApplicationUpdaterUI), chiamate il metodo initialize() per inizializzare l'aggiornamento:

appUpdater.initialize();

Questo metodo esegue le seguenti operazioni:

Inizializza il framework di aggiornamento, installa automaticamente in modo sincrono gli aggiornamenti in sospeso. È necessario chiamare questo metodo durante l'avvio dell'applicazione, in quanto potrebbe riavviare l'applicazione quando viene chiamato.
Verifica se è presente un aggiornamento posticipato e lo installa.
Se durante il processo di aggiornamento si verifica un errore, cancella il file di aggiornamento e le informazioni sulla versione dall'area di memorizzazione dell'applicazione.
Se l'intervallo è scaduto, avvia il processo di aggiornamento. In caso contrario riavvia il timer.

La chiamata a questo metodo può attivare l'invio dei seguenti eventi da parte dell'oggetto updater:

UpdateEvent.INITIALIZED - Inviato quando l'inizializzazione è completa.
ErrorEvent.ERROR - Inviato quando si verifica un errore durante l'inizializzazione.

All'invio dell'evento UpdateEvent.INITIALIZED, il processo di aggiornamento viene completato.

Quando chiamate il metodo initialize(), l'oggetto updater avvia il processo di aggiornamento e completa tutti i passaggi in base all'impostazione del ritardo specificato per il timer. Potete comunque avviare il processo di aggiornamento in qualsiasi momento, chiamando il metodo checkNow() dell'oggetto updater:

appUpdater.checkNow();

Questo metodo non attiva alcuna operazione se il processo di aggiornamento è già in esecuzione. Altrimenti, avvia il processo di aggiornamento.

L'oggetto updater può inviare il seguente evento a seguito della chiamata del metodo checkNow():

UpdateEvent.CHECK_FOR_UPDATE, subito prima del tentativo di scaricare il file descrittore dell'aggiornamento.

Se annullate l'evento checkForUpdate, potete chiamare il metodo checkForUpdate() dell'oggetto updater. (Consultate la sezione successiva). Se non annullate l'evento, il processo di aggiornamento continua con la verifica del file descrittore dell'aggiornamento.

Gestione del processo di aggiornamento nella versione ApplicationUpdaterUI

Nella versione ApplicationUpdaterUI, l'utente può annullare il processo tramite i pulsanti Annulla presenti nelle finestre di dialogo dell'interfaccia utente. Potete inoltre annullare il processo di aggiornamento a livello di codice, chiamando il metodo cancelUpdate() dell'oggetto ApplicationUpdaterUI.

Potete impostare le proprietà dell'oggetto ApplicationUpdaterUI o definire gli elementi nel file di configurazione dell'aggiornamento per specificare quali conferme vengono visualizzate nelle finestre di dialogo dall'oggetto updater. Per ulteriori dettagli, consultate Configurazione delle impostazioni di aggiornamento.

Gestione del processo di aggiornamento nella versione ApplicationUpdater

Potete chiamare il metodo preventDefault() degli oggetti evento inviati dall'oggetto the ApplicationUpdater per annullare i passaggi del processo di aggiornamento (consultate Processo di aggiornamento). L'annullamento del comportamento predefinito consente all'applicazione di visualizzare un messaggio per chiedere all'utente se desidera continuare.

Nelle seguenti sezioni viene descritto come continuare il processo di aggiornamento quando viene annullato un passaggio del processo.

Scaricamento e interpretazione del file descrittore dell'aggiornamento

L'oggetto ApplicationUpdater invia l'evento checkForUpdate prima dell'inizio del processo di aggiornamento, subito prima che l'oggetto updater tenti di scaricare il file descrittore dell'aggiornamento. Se annullate il comportamento predefinito dell'evento checkForUpdate, l'oggetto updater non scarica il file descrittore dell'aggiornamento. Per riprendere il processo di aggiornamento, potete chiamare il metodo checkForUpdate():

appUpdater.checkForUpdate();

Se viene chiamato il metodo checkForUpdate(), l'oggetto updater scarica in modo asincrono e interpreta il file descrittore dell'aggiornamento. A seguito della chiamata del metodo checkForUpdate(), l'oggetto updater può inviare i seguenti eventi:

StatusUpdateEvent.UPDATE_STATUS - L'oggetto updater ha scaricato e interpretato correttamente il file descrittore dell'aggiornamento. Questo evento presenta le seguenti proprietà:
- available- Un valore booleano. Impostato su true se è disponibile una versione diversa rispetto a quella dell'applicazione corrente; in caso contrario false (la versione è la stessa).
- version - Un oggetto String. La versione rilevata dal file descrittore dell'aggiornamento del file di aggiornamento.
- details - Un oggetto Array. Se non sono presenti versioni localizzate della descrizione, questo oggetto array restituisce una stringa vuota ("") come primo elemento e la descrizione come secondo elemento.
  
  Se sono presenti più versioni della descrizione (nel file descrittore dell'aggiornamento), l'array contiene più array secondari. Ogni array presenta due elementi: il primo è un codice di lingua (ad esempio "en"), mentre il secondo è la descrizione corrispondente (una stringa) per quella lingua. Consultate Definizione dei file descrittori dell'aggiornamento e aggiunta del file AIR al server Web.
StatusUpdateErrorEvent.UPDATE_ERROR - Si è verificato un errore e l'oggetto updater non ha potuto scaricare o interpretare il file descrittore dell'aggiornamento.

Scaricamento del file AIR di aggiornamento

L'oggetto ApplicationUpdater invia l'evento updateStatus dopo che il file descrittore dell'aggiornamento è stato scaricato e interpretato correttamente. Il comportamento predefinito prevede di avviare lo scaricamento del file di aggiornamento, se è disponibile. Se annullate il comportamento predefinito, potete chiamare il metodo downloadUpdate() per riprendere il processo di aggiornamento:

appUpdater.downloadUpdate();

Se viene chiamato questo metodo, l'oggetto updater scarica in modo asincrono la versione di aggiornamento del file AIR.

Il metodo downloadUpdate() può inviare i seguenti eventi:

UpdateEvent.DOWNLOAD_START - La connessione al server è stata stabilita. Quando usate la libreria di ApplicationUpdaterUI, questo evento visualizza una finestra di dialogo con una barra di avanzamento che traccia lo stato dello scaricamento.
ProgressEvent.PROGRESS - Inviato periodicamente mentre avanza lo scaricamento del file.
DownloadErrorEvent.DOWNLOAD_ERROR - Inviato se si verifica un errore durante la connessione o lo scaricamento del file di aggiornamento. Viene inviato anche in caso di stati HTTP non validi (ad esempio “404 - File non trovato”). Questo evento presenta una proprietà errorID, un valore intero che definisce le informazioni aggiuntive sull'errore. Una proprietà subErrorID aggiuntiva può contenere ulteriori informazioni sull'errore.
UpdateEvent.DOWNLOAD_COMPLETE - L'oggetto updater ha scaricato e interpretato correttamente il file descrittore dell'aggiornamento. Se non annullate questo evento, la versione ApplicationUpdater continua con l'installazione della versione di aggiornamento. Nella versione ApplicationUpdaterUI, viene visualizzata all'utente una finestra di dialogo con l'opzione per continuare.

Aggiornamento dell'applicazione

L'oggetto ApplicationUpdater invia l'evento downloadComplete dopo avere completato lo scaricamento del file di aggiornamento. Se annullate il comportamento predefinito, potete chiamare il metodo installUpdate() per riprendere il processo di aggiornamento:

appUpdater.installUpdate(file);

Se viene chiamato questo metodo, l'oggetto updater installa una versione di aggiornamento del file AIR. Il metodo include il parametro file; un oggetto File che fa riferimento al file AIR da utilizzare come aggiornamento.

L'oggetto ApplicationUpdater può inviare l'evento beforeInstall a seguito della chiamata al metodo installUpdate():

UpdateEvent.BEFORE_INSTALL - Inviato subito prima dell'installazione dell'aggiornamento. A volte, può essere utile impedire l'installazione dell'aggiornamento a questo punto, in modo che l'utente possa completare il lavoro in corso prima di procedere all'aggiornamento. la chiamata al metodo preventDefault() dell'oggetto Event posticipa l'installazione fino al riavvio successivo; non possono essere avviati altri processi di aggiornamento. (Sono inclusi gli aggiornamenti che dovessero risultare della chiamata al metodo checkNow() o dal controllo periodico).

Installazione da un file AIR arbitrario

Potete chiamare il metodo installFromAIRFile() per installare la versione di aggiornamento da un file AIR sul computer dell'utente:

appUpdater.installFromAIRFile();

Con questo metodo, l'oggetto updater installa una versione di aggiornamento dell'applicazione dal file AIR.

Il metodo installFromAIRFile() può inviare i seguenti eventi:

StatusFileUpdateEvent.FILE_UPDATE_STATUS - Inviato dopo che ApplicationUpdater ha completato la convalida del file inviato usando il metodo installFromAIRFile(). Questo evento presenta le seguenti proprietà:
- available - Impostato su true se è disponibile una versione diversa rispetto a quella dell'applicazione corrente; in caso contrario false (le versione sono le stesse).
- version - La stringa che rappresenta la nuova versione disponibile.
- path - Rappresenta il percorso nativo del file di aggiornamento.
Potete annullare questo evento se la proprietà available dell'oggetto StatusFileUpdateEvent è impostata su true. L'annullamento dell'evento comporta l'interruzione dell'aggiornamento. Per continuare l'aggiornamento annullato, chiamate il metodo installUpdate().
StatusFileUpdateErrorEvent.FILE_UPDATE_ERROR - Si è verificato un errore e l'oggetto updater non ha potuto installare l'applicazione AIR.

Annullamento del processo di aggiornamento

Per annullare il processo di aggiornamento, potete chiamare il metodo cancelUpdate():

appUpdater.cancelUpdate();

Questo metodo annulla le eventuali operazioni di scaricamento in sospeso, eliminando i file scaricati incompleti, e riavvia il timer di controllo periodico.

Questo metodo non attiva alcuna operazione se l'oggetto updater è in corso di inizializzazione.

Localizzazione dell'interfaccia ApplicationUpdaterUI

La classe ApplicationUpdaterUI fornisce un'interfaccia utente predefinita per il processo di aggiornamento. Sono incluse le finestre di dialogo che consentono all'utente di avviare o annullare il processo e di eseguire altre azioni correlate.

L'elemento description del file descrittore dell'aggiornamento consente di definire la descrizione dell'applicazione in più lingue. Potete usare più elementi text che definiscono gli attributi lang, come nel seguente esempio:

<?xml version="1.0" encoding="utf-8"?> 
     <update xmlns="http://ns.adobe.com/air/framework/update/description/1.0"> 
       <version>1.1a1</version> 
       <url>http://example.com/updates/sample_1.1a1.air</url> 
       <description> 
           <text xml:lang="en">English description</text> 
           <text xml:lang="fr">French description</text> 
           <text xml:lang="ro">Romanian description</text> 
       </description> 
    </update>

Il framework di aggiornamento utilizza la descrizione che meglio si adatta alla sequenza di localizzazione dell'utente finale. Per ulteriori informazioni, consultate Definizione del file descrittore dell'aggiornamento e aggiunta del file AIR al server Web.

Gli sviluppatori in Flex possono aggiungere direttamente una nuova lingua al pacchetto "ApplicationUpdaterDialogs".

Gli sviluppatori in JavaScript possono chiamare il metodo addResources() dell'oggetto updater. Questo metodo aggiunge dinamicamente un nuovo pacchetto di risorse per una lingua. Nel pacchetto di risorse sono definite le stringhe localizzate per una lingua. Queste stringhe vengono usate in diversi campi di testo delle finestre di dialogo.

Gli sviluppatori in JavaScript possono usare la proprietà localeChain della classe ApplicationUpdaterUI per definire la sequenza di versioni locali usate dall'interfaccia utente. In genere, questa proprietà viene usata solo dagli sviluppatori in JavaScript (HTML). Gli sviluppatori in Flex possono usare ResourceManager per gestire la sequenza di versioni locali.

Il seguente codice JavaScript definisce, ad esempio, pacchetti di risorse per le lingue rumeno e ungherese:

appUpdater.addResources("ro_RO", 
                    {titleCheck: "Titlu", msgCheck: "Mesaj", btnCheck: "Buton"}); 
appUpdater.addResources("hu", {titleCheck: "Cím", msgCheck: "Üzenet"}); 
var languages = ["ro", "hu"]; 
languages = languages.concat(air.Capabilities.languages); 
var sortedLanguages = air.Localizer.sortLanguagesByPreference(languages, 
                         air.Capabilities.language, 
                         "en-US"); 
sortedLanguages.push("en-US"); 
appUpdater.localeChain = sortedLanguages;

Per ulteriori dettagli, consultate la descrizione del metodo addResources() della classe nella Guida di riferimento.