Aktualizowanie aplikacji AIR

Użytkownicy mogą instalować lub aktualizować aplikację AIR, klikając dwukrotnie plik AIR na komputerze lub używając przeglądarki (funkcji instalacji bezproblemowej). Instalator środowiska Adobe® AIR® zarządza procesem instalacji i ostrzega użytkownika, jeśli ma nastąpić aktualizacja już zainstalowanej aplikacji.

Można jednak również spowodować, że zainstalowana aplikacja będzie samoczynnie aktualizować się do nowej wersji. W mechanizmie tym korzysta się z klasy Updater. (Zainstalowana aplikacja może wykryć dostępność nowej wersji do pobrania i zainstalowania). Klasa Updater zawiera metodę update(), która umożliwia wskazanie pliku AIR na komputerze użytkownika i zaktualizowanie aplikacji do wersji zawartej w pliku. Aby można było korzystać z klasy Updater, aplikacja musi być umieszczona w pakiecie będącym plikiem AIR. Aplikacje umieszczone w macierzystych pakietach wykonywalnych lub w innych pakietach macierzystych powinny używać funkcji aktualizowania udostępnianych przez platformę macierzystą.

Zarówno identyfikator aplikacji, jak i identyfikator wydawcy pliku z aktualizacją muszą być identyczne z odpowiednimi identyfikatorami aktualizowanej aplikacji. Identyfikator wydawcy jest wyznaczany na podstawie certyfikatu podpisującego, co oznacza, że zarówno aktualizacja, jak i aktualizowana aplikacja muszą być podpisane tym samym certyfikatem.

W środowisku AIR 1.5.3 i w późniejszych wersjach plik deskryptora aplikacji zawiera element <publisherID>. Ten element musi być używany, jeśli wersja aplikacji została utworzona w środowisku AIR 1.5.2 lub wcześniejszej wersji. Więcej informacji zawiera sekcja publisherID.

W wersji AIR 1.1 i nowszych istnieje możliwość przeprowadzenia migracji aplikacji w taki sposób, aby używany był dla niej nowy certyfikat do podpisywania kodu. Migracja aplikacji do nowego certyfikatu wymaga podpisania pliku AIR aktualizacji zarówno nowym, jak i oryginalnym certyfikatem. Migracja do nowego certyfikatu jest procesem jednokierunkowym. Po migracji wyłącznie pliki AIR podpisane nowym certyfikatem będą rozpoznawane jako aktualizacje istniejącej instalacji.

Zarządzanie aktualizowaniem aplikacji może być skomplikowanym zagadnieniem. Środowisko AIR 1.5 zawiera nową architekturę aktualizacji aplikacji AdobeAIR. Architektura ta obejmuje elementy interfejsu API pomagające programistom w tworzeniu sprawnych mechanizmów aktualizacji aplikacji AIR.

Migracja certyfikatu umożliwia zmianę certyfikatu samopodpisanego na komercyjny certyfikat podpisujący kod, a także zmianę jednego certyfikatu samopodpisanego lub certyfikatu komercyjnego na inny. Jeśli migracja do nowego certyfikatu nie zostanie przeprowadzona, użytkownicy muszą usunąć swoje bieżące wersje aplikacji przed zainstalowaniem nowej wersji. Więcej informacji zawiera sekcja Zmiana certyfikatów.

Dobrą metodą jest dołączenie mechanizmu aktualizowania do aplikacji. Jeśli zostanie utworzona nowa wersja aplikacji, mechanizm powiadomi użytkownika o możliwości zainstalowania nowej wersji.

Instalator aplikacji AIR tworzy pliki dziennika podczas instalowania, aktualizowania oraz usuwania aplikacji AIR. Dzięki tym dziennikom można określić przyczyny problemów z instalowaniem. Więcej informacji zawiera artykuł Dzienniki instalacji.

Uwaga: Nowe wersje środowiska wykonawczego Adobe AIR mogą zawierać zaktualizowane wersje pakietu WebKit. Zaktualizowana wersja pakietu WebKit może powodować nieoczekiwane zmiany treści HTML we wdrożonej aplikacji AIR. Te zmiany mogą powodować konieczność aktualizowania aplikacji. Mechanizm aktualizacji może informować użytkownika o nowej wersji aplikacji. Więcej informacji zawiera sekcja Informacje o środowisku HTML (dla programistów ActionScript) oraz sekcja Informacje o środowisku HTML (dla programistów HTML).

    Informacje o aktualizowaniu aplikacji

    Klasa Updater (w pakiecie flash.desktop) zawiera jedną metodę, update(), której można użyć w celu zaktualizowania obecnie uruchomionej aplikacji do innej wersji. Na przykład, jeśli użytkownik ma wersję pliku AIR ("Sample_App_v2.air") umieszczoną na pulpicie, poniższy kod zaktualizuje aplikację.

    Przykład w języku 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);

    Przykład w języku JavaScript:

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

    Przed użyciem klasy Updater użytkownik lub aplikacja musi pobrać zaktualizowaną wersję pliku AIR do komputera. Więcej informacji zawiera sekcja Pobieranie pliku AIR na komputer użytkownika.

      Wyniki wywołania metody Updater.update()

      Gdy aplikacja w środowisku wykonawczym wywoła metodę update(), środowisko wykonawcze zamyka aplikację, a następnie próbuje zainstalować nową wersję z pliku AIR. Środowisko wykonawcze sprawdza, czy identyfikatory aplikacji i wydawcy określone w pliku AIR zgadzają się z identyfikatorami aplikacji i wydawcy aplikacji wywołującej metodę update(). (Informacje na temat identyfikatora aplikacji i wydawcy zawiera sekcja Pliki deskryptora aplikacji AIR). Środowisko sprawdza także, czy ciąg znaków wersji jest identyczny z ciągiem znaków version przekazanym do metody update(). Jeśli instalacja zakończy się pomyślnie, środowisko wykonawcze otwiera nową wersję aplikacji. W przeciwnym wypadku (jeśli nie było możliwe zakończenie instalacji), ponownie otwierana jest dotychczasowa (sprzed instalacji) wersja aplikacji.

      W celu zainstalowania zaktualizowanej wersji aplikacji w systemie Mac OS użytkownik musi mieć odpowiednie uprawnienia dostępu do zainstalowania w katalogu aplikacji. W systemach Windows i Linux użytkownik musi mieć uprawnienia administracyjne.

      Jeśli zaktualizowana wersja aplikacji wymaga zaktualizowanej wersji środowiska wykonawczego, instalowana jest nowa wersja tego środowiska. W celu zaktualizowania środowiska wykonawczego użytkownik musi posiadać uprawnienia administracyjne do komputera.

      Podczas testowania aplikacji przy użyciu środowiska ADL wywołanie metody update() powoduje wygenerowanie wyjątku w czasie wykonywania.

      Informacje o ciągu znaków wersji

      Ciąg znaków określony jako parametr version metody update() musi być zgodny z ciągiem znaków w elemencie version lub versionNumber w pliku deskryptora aplikacji dla pliku AIR przeznaczonego do zainstalowania. Określenie parametru version jest wymagane ze względów bezpieczeństwa. Sprawdzanie przez aplikację numeru wersji w pliku AIR zapobiega niezamierzonemu zainstalowaniu starszej wersji. (Starsza wersja aplikacji może zawierać lukę w zabezpieczeniach, która została wyeliminowana w obecnie zainstalowanej wersji.) Aplikacja powinna także porównać ciąg znaków wersji w pliku AIR z ciągiem znaków wersji w instalowanej aplikacji, aby uniemożliwić ataki polegające na podstawieniu starszej wersji.

      W wersjach środowiska AIR starszych niż 2.5 ciąg znaków wersji może mieć dowolny format. Na przykład może mieć wartość „2.01” lub „version 2”. W środowisku AIR 2.5 lub nowszym ciąg znaków wersji musi być sekwencją maksymalnie trzech trzycyfrowych liczb rozdzielonych kropkami. Prawidłowy numer wersji może mieć na przykład postać „.0”, „1.0” lub „67.89.999”. Przed zaktualizowaniem aplikacji należy sprawdzić poprawność ciągu znaków wersji aktualizacji.

      Jeśli aplikacja Adobe AIR pobierze plik AIR z sieci Web, wskazane jest zapewnienie mechanizmu powiadamiania przez usługę Web Service aplikacji Adobe AIR o pobieranej wersji. Aplikacja może następnie wykorzystać odpowiedni ciąg znaków jako parametr version metody update(). Jeśli plik AIR został uzyskany w inny sposób, a jego wersja jest nieznana, aplikacja AIR może przeanalizować plik AIR w celu określenia informacji o wersji. (Plik AIR ma postać archiwum w skompresowanego w formacie ZIP, a plik deskryptora jest drugim rekordem w archiwum).

      Szczegółowe informacje o pliku deskryptora aplikacji zawiera sekcja Pliki deskryptora aplikacji AIR.

      Obieg pracy podpisywania aktualizacji aplikacji

      Publikowanie aktualizacji metodą „ad hoc” komplikuje zarządzanie wieloma wersjami aplikacji, a także utrudnia śledzenie dat utraty ważności certyfikatów. Certyfikaty mogą utracić ważność, zanim będzie możliwe opublikowanie aktualizacji.

      Środowisko wykonawcze Adobe AIR traktuje aktualizację aplikacji opublikowaną bez podpisu migracji jako nową aplikację. Użytkownicy muszą odinstalować bieżącą aplikację AIR, aby móc zainstalować aktualizację aplikacji.

      W celu rozwiązania tego problemu należy wysłać każdą zaktualizowaną aplikację z najnowszym certyfikatem na osobny adres URL wdrażania. Należy uwzględnić mechanizm przypominania o stosowaniu podpisów migracji, gdy rozpocznie się 180-dniowy okres prolongaty certyfikatu. Więcej informacji zawiera sekcja Podpisywanie zaktualizowanej wersji aplikacji AIR.

      Informacje na temat stosowania podpisów zawiera sekcja Polecenia narzędzia ADT.

      Aby usprawnić stosowanie podpisów migracji, należy wykonać następujące zadania:

      • Wyślij każdą zaktualizowaną aplikację na osobny adres URL wdrażania.

      • Wyślij plik XML deskryptora uaktualnienia i najnowszy certyfikat dla aktualizacji na ten sam adres URL.

      • Podpisz zaktualizowaną aplikację za pomocą najnowszego certyfikatu.

      • Zastosuj podpis migracji do zaktualizowanej aplikacji za pomocą certyfikatu użytego do podpisania poprzedniej wersji, umieszczonej pod innym adresem URL.

      Prezentowanie niestandardowego interfejsu aktualizacji aplikacji

      Środowisko AIR zawiera domyślny interfejs aktualizacji:

      Powiększ obraz

      Ten interfejs jest używany zawsze, gdy użytkownik po raz pierwszy instaluje aplikację na komputerze. Można jednak zdefiniować własny interfejs, który będzie używany przy instalowaniu następnych wersji aplikacji. Jeśli aplikacja definiuje niestandardowy interfejs aktualizacji, należy dla obecnie zainstalowanej aplikacji określić element customUpdateUI w pliku deskryptora aplikacji:

      <customUpdateUI>true</customUpdateUI>

      Gdy aplikacja jest już zainstalowana, a użytkownik otworzy plik AIR z identyfikatorem aplikacji i wydawcy identycznymi z odpowiednimi identyfikatorami zainstalowanej aplikacji, środowisko wykonawcze AIR otwiera aplikację, a nie domyślny instalator aplikacji AIR. Więcej informacji zawiera sekcja customUpdateUI.

      Aplikacja w chwili uruchomienia (tj. gdy obiekt NativeApplication.nativeApplication wywoła zdarzenie load) może zdecydować, czy ma dokonać aktualizacji (przy użyciu klasy Updater). Jeśli aktualizacja ma być dokonana, aplikacja może zaprezentować użytkownikowi własny interfejs instalacji (który będzie się różnił od standardowego interfejsu do obsługi aplikacji).

        Pobieranie pliku AIR na komputer użytkownika

        Aby użyć klasy Updater, użytkownik lub aplikacja musi uprzednio zapisać plik AIR lokalnie na dysku swojego komputera.

        Uwaga: W skład środowiska AIR 1.5 wchodzi architektura aktualizacji, która pomaga programistom w realizacji sprawnych mechanizmów aktualizacji aplikacji AIR. Korzystanie z tej architektury może okazać się znacznie łatwiejsze niż bezpośrednie używanie metody update() klasy Update. Szczegółowe informacje zawiera sekcja Korzystanie z architektury aktualizacji.

        Poniższy kod odczytuje plik AIR z adresu URL (http://example.com/air/updates/Sample_App_v2.air) i zapisuje ten plik w katalogu magazynu aplikacji.

        Przykład w języku 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."); 
}

        Przykład w języku 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."); 
}

        Aby znaleźć więcej informacji na ten temat, zobacz:

          Sprawdzanie, czy aplikacja została uruchomiona po raz pierwszy

          Często po zaktualizowaniu aplikacja wyświetla komunikat powitalny lub instrukcję „pierwsze kroki”. Po uruchomieniu aplikacja sprawdza, czy została uruchomiona po raz pierwszy, i na tej podstawie może wyświetlić taki komunikat lub nie.

          Uwaga: W skład środowiska AIR 1.5 wchodzi architektura aktualizacji, która pomaga programistom w realizacji sprawnych mechanizmów aktualizacji aplikacji AIR. Architektura ta udostępnia łatwe metody sprawdzania, czy dana aplikacja jest uruchomiona po raz pierwszy. Szczegółowe informacje zawiera sekcja Korzystanie z architektury aktualizacji.

          Jedna z metod sprawdzenia tego warunku polega na zapisaniu pliku w katalogu magazynu aplikacji po jej zainicjowaniu. Po każdym uruchomieniu aplikacja powinna sprawdzać, czy plik istnieje. Brak pliku oznacza, że aplikacja została uruchomiona po raz pierwszy dla bieżącego użytkownika. Obecność pliku oznacza, że aplikacja była już co najmniej jeden raz uruchamiana. Jeśli plik istnieje i zawiera numer wersji starszej niż bieżąca, można przyjąć że użytkownik uruchamia nową wersję po raz pierwszy.

          Poniższy przykład Flex ilustruje ten sposób postępowania. 

          <?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>

          Poniższy przykład ilustruje to rozwiązanie w języku 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>

          Jeśli aplikacja zapisuje dane lokalnie (np. w katalogu magazynu aplikacji), niekiedy celowe jest sprawdzenie przy pierwszym uruchomieniu, czy istnieją dane zapisane wcześniej przez poprzednie wersje.

            Korzystanie z architektury aktualizacji

            Zarządzanie aktualizacjami aplikacji może być pracochłonne. Infrastruktura aktualizacji dla aplikacji AdobeAIR oferuje interfejsy API, które umożliwiają programistom udostępnienie niezawodnych funkcji aktualizowania w aplikacjach AIR. Infrastruktura aktualizacji środowiska AIR zwalnia programistów z wykonywania następujących zadań:

            • Okresowe sprawdzanie dostępności aktualizacji w odpowiednich interwałach lub na żądanie użytkownika

            • Pobieranie plików AIR (aktualizacji) ze źródła w Internecie

            • Powiadamianie użytkownika przy pierwszym uruchomieniu nowo zainstalowanej wersji

            • Potwierdzanie, że użytkownik chce sprawdzić dostępność aktualizacji

            • Wyświetlanie informacji o wersji nowej aktualizacji

            • Wyświetlanie informacji o postępie pobierania i błędach

            Infrastruktura aktualizacji środowiska AIR zawiera przykładowy interfejs użytkownika dla aplikacji. Interfejs ten udostępnia użytkownikowi podstawowe informacje i opcje konfiguracji związane z aktualizacjami aplikacji. Aplikacja może także definiować własny interfejs użytkownika współpracujący z infrastrukturą aktualizacji.

            Infrastruktura aktualizacji aplikacji AIR umożliwia przechowywanie informacji o wersji aktualizacji aplikacji AIR w prostych plikach konfiguracyjnych XML. W przypadku większości aplikacji przygotowanie tych plików konfiguracyjnych przez dodanie podstawowego kodu wystarczy do zapewnienia użytkownikom końcowym odpowiedniej obsługi aktualizacji.

            Nawet jeśli programista nie zdecyduje się na użycie infrastruktury aktualizacji, aplikacje mogą korzystać z klasy Updater dostępnej w środowisku Adobe AIR, która wspomaga uaktualnianie do nowych wersji. Klasa Updater umożliwia aplikacji uaktualnienie do wersji zawartej w pliku AIR na komputerze użytkownika. Jednak zarządzanie aktualizacjami zwykle nie sprowadza się do prostej aktualizacji aplikacji na podstawie lokalnego pliku AIR.

              Pliki architektury aktualizacji AIR

              Architektura aktualizacji AIR jest zawarta w katalogu frameworks/libs/air pakietu AIR 2 SDK. Zawiera następujące pliki:

              • applicationupdater.swc — definiuje podstawowe funkcje biblioteki aktualizacji, do wykorzystania w kodzie ActionScript. Ta wersja nie zawiera interfejsu użytkownika.

              • applicationupdater.swf — definiuje podstawowe funkcje biblioteki aktualizacji, do wykorzystania w kodzie JavaScript. Ta wersja nie zawiera interfejsu użytkownika.

              • applicationupdater_ui.swc — definiuje podstawową funkcjonalność biblioteki aktualizacji dla Flex 4 wraz z interfejsem użytkownika, którego aplikacja może używać do wyświetlania opcji aktualizacji.

              • applicationupdater_ui.swf — definiuje podstawową funkcjonalność biblioteki aktualizacji dla JavaScript wraz z interfejsem użytkownika, którego aplikacja może używać do wyświetlania opcji aktualizacji.

              Więcej informacji zawierają poniższe sekcje:

              Konfigurowanie środowiska programistycznego Flex

              Pliki SWC w katalogu frameworks/libs/air pakietu AIR 2 SDK definiują klasy używane podczas programowania w środowisku Flex i w programie Flash.

              Aby skorzystać z architektury aktualizacji przy kompilowaniu aplikacji za pomocą pakietu Flex SDK, należy uwzględnić plik ApplicationUpdater.swc albo ApplicationUpdater_UI.swc w wywołaniu kompilatora amxmlc. W poniższym przykładzie kompilator ładuje plik ApplicationUpdater.swc z podkatalogu lib w katalogu pakietu Flex SDK:

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

              W poniższym przykładzie kompilator ładuje plik ApplicationUpdater_UI.swc file z podkatalogu lib pakietu Flex SDK:

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

              W przypadku tworzenia aplikacji za pomocą kompilatora Flash Builder należy dodać plik SWC na karcie ścieżki biblioteki w ustawieniach ścieżki kompilacji Flex w oknie dialogowym właściwości.

              Pliki SWC należy koniecznie skopiować do katalogu, do którego będziemy odwoływać się w kompilatorze amxmlc (w przypadku użycia pakietu Flex SDK) lub w programie Flash Builder.

              Uwzględnianie plików architektury w aplikacji AIR opartej na kodzie HTML

              Katalog frameworks/html architektury aktualizacji zawiera następujące pliki:

              • applicationupdater.swf — definiuje podstawowe funkcje biblioteki aktualizacji, bez interfejsu użytkownika.

              • applicationupdater_ui.swf — definiuje podstawowe funkcje biblioteki aktualizacji wraz z interfejsem użytkownika, którego aplikacja może używać do wyświetlania opcji aktualizacji.

              Kod JavaScript w aplikacjach AIR może korzystać z klas zdefiniowanych w plikach SWF.

              Aby korzystać z infrastruktury aktualizacji, należy umieścić plik applicationupdater.swf albo applicationupdater_ui.swf w katalogu (lub podkatalogu) aplikacji. Następnie w pliku HTML, w którym infrastruktura będzie stosowana (w kodzie JavaScript) należy umieścić znacznik script wczytujący ten plik.

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

              Można też użyć poniższego znacznika script w celu wczytania pliku applicationupdater_ui.swf.

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

              Interfejs API zdefiniowany w tych dwóch plikach został opisany w dalszej części niniejszego dokumentu.

              Prosty przykład: korzystanie z wersji ApplicationUpdaterUI

              Wersja architektury aktualizacji zapisana w pliku ApplicationUpdaterUI udostępnia prosty interfejs, który łatwo można włączyć do własnych aplikacji. Poniżej przedstawiono prosty przykład.

              Najpierw tworzymy aplikację AIR, która wywołuje architekturę aktualizacji:

              1. Jeśli aplikacja AIR jest oparta na języku HTML, należy wczytać plik applicationupdater_ui.swf.

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

              2. W logice programowej aplikacji AIR tworzymy instancję obiektu ApplicationUpdaterUI.

                W języku ActionScript należałoby użyć następującego kodu:

                var appUpdater:ApplicationUpdaterUI = new ApplicationUpdaterUI();

                W języku JavaScript należałoby użyć następującego kodu:

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

                Celowe może być dodanie tego kodu do funkcji inicjującej, wykonywanej po załadowaniu aplikacji.

              3. Tworzymy plik tekstowy o nazwie updateConfig.xml i dodajemy do niego następujący kod:

                <?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>

                Modyfikujemy element URL pliku updateConfig.xml w taki sposób, aby wskazywał docelową lokalizację pliku deskryptora aktualizacji na serwerze WWW (patrz następna procedura).

                Wartość delay to liczba dni, co jaką aplikacja sprawdza dostępność aktualizacji.

              4. Dodajemy plik updateConfig.xml file do katalogu projektu aplikacji AIR.

              5. Powodujemy, że obiekt Updater odwołuje się do pliku updateConfig.xml, i wywołujemy metodę initialize() obiektu.

                W języku ActionScript należałoby użyć następującego kodu:
                appUpdater.configurationFile = new File("app:/updateConfig.xml"); 
appUpdater.initialize();
                W języku JavaScript należałoby użyć następującego kodu:
                appUpdater.configurationFile = new air.File("app:/updateConfig.xml"); 
appUpdater.initialize();

              6. Tworzymy drugą wersję aplikacji AIR, o innym numerze niż pierwsza aplikacja. (Wersja jest podana w pliku deskryptora, w elemencie version).

              Następnie dodajemy zaktualizowaną wersję aplikacji AIR na serwer WWW:

              1. Umieszczamy pliku AIR wersji zaktualizowanej na serwerze WWW.

              2. Należy utworzyć plik tekstowy o nazwie updateDescriptor.2.5.xml i dodać do niego następującą treść:

                <?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>

                Należy edytować elementy versionNumber, URL i description pliku updateDescriptor.xml w taki sposób, aby odpowiadały plikowi AIR aktualizacji. Ten format deskryptora aktualizacji jest używany przez aplikacje korzystające z infrastruktury aktualizacji dołączonej do zestawu SDK środowiska AIR 2.5 i nowszych wersji.

              3. Należy utworzyć plik tekstowy o nazwie updateDescriptor.1.0.xml i dodać do niego następującą treść:

                <?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>

                Należy edytować elementy version, URL i description pliku updateDescriptor.xml w taki sposób, aby wskazywały na plik AIR aktualizacji. Ten format deskryptora aktualizacji jest używany przez aplikacje korzystające z infrastruktury aktualizacji dołączonej do zestawu SDK środowiska AIR 2 i starszych wersji.

                Uwaga: Utworzenie drugiego z podanych plików deskryptora aktualizacji jest konieczne tylko w przypadku obsługi aktualizacji aplikacji opracowanych dla środowiska AIR w wersji starszej niż 2.5.

              4. Należy dodać pliki updateDescriptor.2.5.xml i updateDescriptor.1.0.xml do tego samego katalogu serwera internetowego, który zawiera plik AIR aktualizacji.

              Choć jest to prosty przykład, zapewnia on funkcjonalność aktualizacji wystarczającą w wielu zastosowaniach. W pozostałej części tego dokumentu opisano sposoby wykorzystania architektury aktualizacji odpowiednio do indywidualnych potrzeb.

              Dodatkowe przykłady użycia architektury aktualizacji zawierają następujące aplikacje w serwisie Adobe AIR Developer Center:

              Aktualizowanie do środowiska AIR 2.5

              Zasady przydzielania numerów wersji do aplikacji zostały zmienione w środowisku AIR 2.5, dlatego infrastruktura aktualizacji środowiska AIR 2 nie może przeanalizować informacji o wersji w deskryptorze aplikacji środowiska AIR 2.5. Ta niezgodność oznacza, że należy zaktualizować aplikację w celu korzystania z nowej infrastruktury aktualizacji, ZANIM aplikacja zostanie zaktualizowana w celu korzystania z zestawu SDK środowiska AIR 2.5. Dlatego aktualizowanie aplikacji z dowolnej wersji środowiska AIR starszej niż 2.5 w celu korzystania ze środowiska AIR 2.5 lub nowszej wersji wymaga DWÓCH aktualizacji. Pierwsza aktualizacja musi używać przestrzeni nazw środowiska AIR 2 i uwzględniać bibliotekę infrastruktury aktualizacji środowiska AIR 2.5. (Pakiet aplikacji można utworzyć za pomocą zestawu SDK środowiska AIR 2.5). Druga aktualizacja może używać przestrzeni nazw środowiska AIR 2.5 i uwzględniać nowe funkcje aplikacji.

              Pośrednia aktualizacja może również nie wykonywać żadnych operacji oprócz zaktualizowania aplikacji do wersji dla środowiska AIR 2.5 przy użyciu klasy Updater środowiska AIR w bezpośredni sposób.

              Poniższy przykład przedstawia aktualizowanie aplikacji z wersji 1.0 do 2.0. Wersja 1.0 używa starej przestrzeni nazw wersji 2.0. Wersja 2.0 używa przestrzeni nazw wersji 2.5 i zawiera nowe funkcje zaimplementowane przy użyciu interfejsów API środowiska 2.5.

              1. Utwórz pośrednią wersję aplikacji (1.0.1) na podstawie wersji 1.0.

                1. Podczas tworzenia aplikacji użyj infrastruktury aktualizacji aplikacji środowiska AIR 2.5.

                  Uwaga: W przypadku aplikacji AIR opartej na technologii Flash użyj pliku applicationupdater.swc lub applicationupdater_ui.swc. W przypadku aplikacji AIR opartej na języku HTML użyj pliku applicationupdater.swf lub applicationupdater_ui.swf.

                2. Utwórz plik deskryptora aktualizacji dla wersji 1.0.1, używając starej przestrzeni nazw i wersji, tak jak pokazano poniżej.

                  <?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>

              2. Utwórz wersję 2.0 aplikacji, korzystającą z interfejsów API i przestrzeni nazw środowiska AIR 2.5.

              3. Utwórz deskryptor aktualizacji w celu zaktualizowania aplikacji z wersji 1.0.1 do wersji 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>

              Definiowanie plików deskryptora aktualizacji i dodawanie pliku AIR do serwera internetowego

              Podczas pracy z infrastrukturą aktualizacji środowiska AIR należy zdefiniować podstawowe informacje o dostępnej aktualizacji w plikach deskryptora aktualizacji przechowywanych na serwerze internetowym. Plik deskryptora aktualizacji jest prostym plikiem XML. Infrastruktura aktualizacji dołączona do aplikacji sprawdza zawartość tego pliku, aby stwierdzić, czy na serwerze została umieszczona nowa wersja.

              Format pliku deskryptora aktualizacji uległ zmianie w środowisku AIR 2.5. W nowym formacie jest używana inna przestrzeń nazw. Oryginalna przestrzeń nazw to „http://ns.adobe.com/air/framework/update/description/1.0”. Przestrzeń nazw środowiska AIR 2.5 to „http://ns.adobe.com/air/framework/update/description/2.5”.

              Aplikacje AIR utworzone dla wersji środowiska AIR starszych niż 2.5 mogą odczytywać tylko deskryptor aktualizacji dotyczący wersji 1.0. Aplikacje AIR utworzone za pomocą infrastruktury aktualizacji zawartej w środowisku AIR 2.5 lub nowszym mogą odczytywać tylko deskryptor aktualizacji dotyczący wersji 2.5. Z powodu tej niezgodności wersji często trzeba tworzyć dwa pliki deskryptora aktualizacji. Logika obsługująca aktualizowanie w wersjach aplikacji dla środowiska AIR 2.5 musi pobierać deskryptor aktualizacji korzystający z nowego formatu. Starsze wersje aplikacji AIR muszą nadal korzystać z oryginalnego formatu. Dla każdej wydanej aktualizacji należy zmodyfikować oba pliki (do czasu zakończenia obsługi wersji utworzonych dla wersji środowiska AIR starszych niż 2.5).

              Plik deskryptora aktualizacji zawiera następujące dane:

              • versionNumber — nowa wersja aplikacji AIR. Element versionNumber należy stosować w deskryptorach aktualizacji używanych do aktualizowania aplikacji AIR 2.5. Podana wartość musi być taka sama jak ciąg znaków użyty w elemencie versionNumber w nowym pliku deskryptora aplikacji AIR. Jeśli numer wersji w pliku deskryptora aktualizacji nie jest zgodny z numerem wersji pliku AIR aktualizacji, infrastruktura aktualizacji generuje wyjątek.

              • version — nowa wersja aplikacji AIR. Element version należy stosować w deskryptorach aktualizacji używanych do aktualizowania aplikacji utworzonych dla wersji środowiska AIR starszych niż 2.5. Podana wartość musi być taka sama jak ciąg znaków użyty w elemencie version w nowym pliku deskryptora aplikacji AIR. Jeśli wersja w pliku deskryptora aktualizacji nie jest zgodna z wersją pliku AIR aktualizacji, infrastruktura aktualizacji generuje wyjątek.

              • versionLabel — ciąg znaków w postaci czytelnej dla człowieka, przeznaczony do wyświetlania dla użytkowników. Element versionLabel jest opcjonalny, ale można go określać tylko w plikach deskryptora aktualizacji w wersji 2.5. Ten element należy stosować, jeśli w pliku deskryptora aplikacji jest używany element versionLabel. (Dla obu elementów należy ustawić tę samą wartość).

              • url — lokalizacja pliku AIR aktualizacji. Jest to plik zawierający zaktualizowaną wersję aplikacji AIR.

              • description — opis nowej wersji. Te informacje mogą być wyświetlane dla użytkownika podczas aktualizacji.

              Elementy version i url są wymagane. Element description jest opcjonalny.

              Oto przykładowy plik deskryptora aktualizacji dla wersji 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>

              Oto przykładowy plik deskryptora aktualizacji dla wersji 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>

              Aby zdefiniować znacznik description w wielu językach, należy zastosować wiele elementów text definiujących atrybut 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>

              Umieszczamy plik deskryptora aktualizacji wraz z plikiem AIR aktualizacji na serwerze WWW.

              Katalog templates dołączony do deskryptora aktualizacji zawiera przykładowe pliki deskryptorów aktualizacji. Zawierają one wersje w jednym języku oraz wersje wielojęzyczne.

              Tworzenie instancji klasy Updater

              Po załadowaniu architektury aktualizacji AIR w kodzie (patrz Konfigurowanie środowiska programistycznego Flex i Uwzględnianie plików architektury w aplikacji AIR opartej na kodzie HTML) konieczne jest utworzenie instancji klasy Updater, co ilustruje poniższy przykład.

              Przykład w języku ActionScript:

              var appUpdater:ApplicationUpdater = new ApplicationUpdater();

              Przykład w języku JavaScript:

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

              W powyższym kodzie zastosowano klasę ApplicationUpdater (która nie udostępnia interfejsu użytkownika). Oto kod, w którym zastosowano klasę ApplicationUpdaterUI (z interfejsem użytkownika).

              Przykład w języku ActionScript:

              var appUpdater:ApplicationUpdaterUI = new ApplicationUpdaterUI();

              Przykład w języku JavaScript:

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

              W przykładach kodu zamieszczonych w dalszej części tego dokumentu przyjęto założenie, że został utworzony obiekt Updater o nazwie appUpdater.

              Konfigurowanie ustawień aktualizacji

              Zarówno klasę ApplicationUpdater, jak i klasę ApplicationUpdaterUI można skonfigurować za pośrednictwem pliku konfiguracji dostarczonego z aplikacją lub za pomocą kodu ActionScript bądź JavaScript w aplikacji.

              Definiowanie ustawień aktualizacji w pliku konfiguracyjnym XML

              Plik konfiguracyjny aktualizacji jest plikiem XML. Może zawierać następujące elementy:

              • updateURL — ciąg znaków (String). Reprezentuje lokalizację deskryptora aktualizacji na serwerze zdalnym. Dozwolone są wszelkie poprawne lokalizacje URLRequest. Właściwość updateURL musi być zdefiniowana — albo w pliku konfiguracyjnym, albo za pomocą skryptu (patrz Definiowanie plików deskryptora aktualizacji i dodawanie pliku AIR do serwera internetowego). Właściwość tę należy zdefiniować przed użyciem obiektu Updater (przed wywołaniem metody initialize() obiektu Updater, co opisano w sekcji Inicjowanie architektury aktualizacji).

              • delay — liczba (Number). Reprezentuje interwał (w dniach, dozwolone są wartości ułamkowe, takie jak 0.25) sprawdzania dostępności aktualizacji. Wartość 0 (domyślna) określa, że obiekt Updater nie będzie okresowo automatycznie sprawdzał dostępności aktualizacji.

              Plik konfiguracyjny dla klasy ApplicationUpdaterUI może, oprócz elementów updateURL i delay, zawierać następujący element:

              • defaultUI: lista elementów dialog. Każdy element dialog ma atrybut name odpowiadający oknu dialogowemu w interfejsie użytkownika. Każdy element dialog ma atrybut visible określający, czy okno dialogowe jest widoczne. Wartością domyślną jest true. Oto możliwe wartości atrybutu name:

                • "checkForUpdate" — odpowiada oknom dialogowym Sprawdź dostępność aktualizacji, Brak aktualizacji i Błąd aktualizacji.

                • "downloadUpdate" — odpowiada oknu dialogowemu Pobierz aktualizację.

                • "downloadProgress" — odpowiada oknom dialogowym Postęp pobierania i Błąd pobierania.

                • "installUpdate" — odpowiada oknu dialogowemu Zainstaluj aktualizację.

                • "fileUpdate" — odpowiada oknom dialogowym Aktualizacja pliku, Plik nie jest aktualizacją i Błąd pliku.

              • "unexpectedError" — odpowiada oknu dialogowemu Nieoczekiwany błąd.

                Ustawienie wartości false powoduje, że odpowiednie okna dialogowe nie będą pojawiać się w trakcie procedury aktualizacji.

              Oto przykładowy plik konfiguracyjny dla architektury 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>

              Oto przykładowy plik konfiguracyjny dla architektury ApplicationUpdaterUI zawierający definicję elementów 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>

              Właściwość configurationFile powinna wskazywać na położenie tego pliku:

              Przykład w języku ActionScript:

              appUpdater.configurationFile = new File("app:/cfg/updateConfig.xml");
              Przykład w języku JavaScript:
              appUpdater.configurationFile = new air.File("app:/cfg/updateConfig.xml");

              Katalog templates architektury aktualizacji zawiera przykładowy plik konfiguracyjny o nazwie config-template.xml.

              Definiowanie ustawień aktualizacji za pomocą kodu ActionScript lub JavaScript

              Te same parametry konfiguracyjne można ustawić za pośrednictwem kodu aplikacji, tak jak w poniższym przykładzie:

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

              Obiekt Updater ma właściwości updateURL i delay. Właściwości te opisują te same ustawienia, co elementy updateURL i delay w pliku konfiguracyjnym: adres URL pliku deskryptora aktualizacji i interwał sprawdzania dostępności aktualizacji. W wypadku określenia ustawień w pliku konfiguracyjnym i w kodzie wszelkie właściwości ustawione w kodzie przesłaniają odpowiednie ustawienia w pliku.

              Właściwość updateURL musi być zdefiniowana — albo w pliku konfiguracyjnym, albo za pomocą skryptu (patrz Definiowanie plików deskryptora aktualizacji i dodawanie pliku AIR do serwera internetowego) — przed użyciem obiektu Updater (przed wywołaniem metody initialize() obiektu Updater, co opisano w sekcji Inicjowanie architektury aktualizacji).

              W architekturze ApplicationUpdaterUI zdefiniowane są następujące dodatkowe właściwości obiektu Updater:

              • isCheckForUpdateVisible — odpowiada oknom dialogowym Sprawdź dostępność aktualizacji, Brak aktualizacji i Błąd aktualizacji.

              • isDownloadUpdateVisible — odpowiada oknu dialogowemu Pobierz aktualizację.

              • isDownloadProgressVisible — odpowiada oknom dialogowym Postęp pobierania i Błąd pobierania.

              • isInstallUpdateVisible — odpowiada oknu dialogowemu Zainstaluj aktualizację.

              • isFileUpdateVisible — odpowiada oknom dialogowym Aktualizacja pliku, Plik nie jest aktualizacją i Błąd pliku.

              • isUnexpectedErrorVisible — odpowiada oknu dialogowemu Nieoczekiwany błąd.

              Każda z właściwości odpowiada jednemu lub większej liczbie okien dialogowych w interfejsie użytkownika architektury ApplicationUpdaterUI. Wszystkie właściwości są typu Boolean i mają wartość domyślną true. Ustawienie wartości false powoduje, że odpowiednie okna dialogowe nie będą pojawiać się w trakcie procedury aktualizacji.

              Właściwości okien dialogowych przesłaniają ustawienia w pliku konfiguracyjnym aktualizacji.

              Proces aktualizacji

              Architektura aktualizacji AIR realizuje proces aktualizacji w następujących krokach:

              1. Procedura inicjowania obiektu Updater sprawdza, czy w zdefiniowanym okresie dokonano już sprawdzenia dostępności aktualizacji (patrz Konfigurowanie ustawień aktualizacji). Jeśli przypada termin aktualizacji, proces aktualizacji jest kontynuowany.

              2. Obiekt Updater pobiera i interpretuje plik deskryptora aktualizacji.

              3. Obiekt Updater pobiera plik AIR aktualizacji.

              4. Obiekt Updater instaluje zaktualizowaną wersję aplikacji.

              Obiekt Updater wywołuje zdarzenia po zakończeniu każdego z tych kroków. W architekturze ApplicationUpdater możliwe jest anulowanie zdarzeń wskazujących na pomyślne zakończenie kroków procesu. W wypadku anulowania jednego z takich zdarzeń anulowany zostanie następny krok procesu. W architekturze ApplicationUpdaterUI obiekt Updater wyświetla okno dialogowe umożliwiające użytkownikowi anulowanie lub wykonanie każdego z kroków procesu.

              W wypadku anulowania zdarzenia możliwe jest wznowienie procesu poprzez wywołanie metod obiektu Updater.

              W miarę, jak obiekt Updater w wersji ApplicationUpdater realizuje kolejne etapy aktualizacji, jego bieżący stan jest zapisywany we właściwości currentState. Tej właściwości przypisywany jest ciąg znaków o jednej z następujących możliwych wartości:

              • "UNINITIALIZED" — obiekt Updater nie został zainicjowany.

              • "INITIALIZING" — trwa inicjowanie obiektu Updater.

              • "READY" — obiekt Updater został zainicjowany.

              • "BEFORE_CHECKING" — obiekt Updater nie sprawdził jeszcze, czy istnieje plik deskryptora aktualizacji.

              • "CHECKING" — obiekt Updater sprawdza, czy istnieje plik deskryptora aktualizacji.

              • "AVAILABLE" — plik deskryptora jest dostępny dla obiektu Updater.

              • "DOWNLOADING" — obiekt Updater pobiera plik AIR.

              • "DOWNLOADED" — obiekt Updater pobrał plik AIR.

              • "INSTALLING" — obiekt Updater instaluje plik AIR.

              • "PENDING_INSTALLING" — obiekt Updater jest zainicjowany i istnieją oczekujące aktualizacje.

              Niektóre metody obiektu Updater są wykonywane tylko wtedy, gdy obiekt ten jest w określonym stanie.

              Inicjowanie architektury aktualizacji

              Po ustawieniu właściwości konfiguracyjnych (patrz Prosty przykład: korzystanie z wersji ApplicationUpdaterUI) należy wywołać metodę initialize() w celu zainicjowania aktualizacji:

              appUpdater.initialize();

              Metoda ta wykonuje następujące operacje:

              • Inicjuje architekturę aktualizacji, przeprowadzając cichą instalację wszelkich oczekujących aktualizacji. Wymagane jest wywołanie tej metody podczas uruchamiania aplikacji, ponieważ może ona wymusić ponowne uruchomienie aplikacji.

              • Sprawdza, czy istnieje oczekująca (odłożona w czasie) aktualizacja, a jeśli tak, instaluje ją.

              • Jeśli w procesie aktualizacji wystąpi błąd, metoda usuwa informacje o pliku aktualizacji i o wersji z obszaru pamięci aplikacji.

              • Jeśli minął okres opóźnienia, rozpoczyna proces aktualizacji. W przeciwnym razie ponownie uruchamia licznik czasu.

              Wywołanie tej metody może spowodować, że obiekt Updater wywoła następujące zdarzenia:

              • UpdateEvent.INITIALIZED — wywoływane po zakończeniu inicjowania.

              • ErrorEvent.ERROR — wywoływane, jeśli w trakcie inicjowania wystąpi błąd.

              Po wywołaniu zdarzenia UpdateEvent.INITIALIZED proces aktualizacji jest ukończony.

              Wywołanie metody initialize() powoduje, że obiekt Updater rozpoczyna proces aktualizacji i wykonuje wszystkie kroki z uwzględnieniem ustawionego opóźnienia. Możliwe jest jednak także rozpoczęcie procesu aktualizacji w dowolnej chwili, poprzez wywołanie metody checkNow() obiektu Updater:

              appUpdater.checkNow();

              Jeśli proces aktualizacji już trwa, ta metoda nie wykonuje żadnych czynności. W przeciwnym razie rozpoczyna proces aktualizacji.

              Obiekt Updater może wywoływać następujące zdarzenie w wyniku wywołania metody checkNow():

              • zdarzenie UpdateEvent.CHECK_FOR_UPDATE tuż przed próbą pobrania pliku deskryptora aktualizacji.

              Jeśli zdarzenie checkForUpdate zostanie anulowane, można wywołać metodę checkForUpdate() obiektu Updater. (Patrz następna sekcja). Jeśli zdarzenie nie zostanie anulowane, proces aktualizacji przechodzi do etapu sprawdzania, czy istnieje plik deskryptora aktualizacji.

              Zarządzanie procesem aktualizacji w wersji ApplicationUpdaterUI

              W wersji ApplicationUpdaterUI użytkownik może anulować proces za pomocą przycisków Anuluj w oknach dialogowych interfejsu użytkownika. Możliwe jest także programowe anulowanie procesu aktualizacji poprzez wywołanie metody cancelUpdate() obiektu ApplicationUpdaterUI.

              W celu określenia, które okna dialogowe potwierdzeń mają być wyświetlane przez obiekt Updater, można ustawić właściwości obiektu ApplicationUpdaterUI lub zdefiniować elementy pliku konfiguracyjnego aplikacji. Szczegółowe informacje zawiera sekcja Konfigurowanie ustawień aktualizacji.

              Zarządzanie procesem aktualizacji w wersji ApplicationUpdater

              Możliwe jest wywoływanie metody preventDefault() obiektów zdarzeń wywoływanych przez obiekt ApplicationUpdater w celu anulowania odpowiednich kroków procesu aktualizacji (patrz Proces aktualizacji). Anulowanie domyślnego zachowania stwarza aplikacji możliwość wyświetlenia komunikatu z pytaniem, czy użytkownik chce kontynuować.

              W dalszych sekcjach opisano sposób kontynuacji procesu aktualizacji w wypadku anulowania jednego z kroków procesu.

              Pobieranie i interpretowanie pliku deskryptora aktualizacji

              Obiekt ApplicationUpdater wywołuje zdarzenie checkForUpdate przed rozpoczęciem procesu aktualizacji, tuż przed próbą pobrania pliku deskryptora aktualizacji. Jeśli domyślne zachowanie zdarzenia checkForUpdate zostanie anulowane, obiekt Updater nie pobierze pliku deskryptora aktualizacji. Można wywołać metodę checkForUpdate() i tym samym wznowić proces aktualizacji:

              appUpdater.checkForUpdate();

              Wywołanie metody checkForUpdate() powoduje, że obiekt Updater asynchronicznie pobierze i zinterpretuje plik deskryptora. W wyniku wywołania metody checkForUpdate() obiekt Updater może wywołać następujące zdarzenia:

              • StatusUpdateEvent.UPDATE_STATUS — obiekt Updater pomyślnie pobrał i zinterpretował plik deskryptora aktualizacji. To zdarzenie ma następujące właściwości:

                • available — wartość typu Boolean. Ustawiana na true, jeśli dostępna jest wersja aplikacji inna niż bieżąca; false w przeciwnym wypadku (wersje są takie same).

                • version — ciąg znaków (String). Wersja odczytana z pliku deskryptora aplikacji pliku aktualizacji.

                • details — tablica (Array). Jeśli nie istnieją zlokalizowane wersje opisu, jako pierwszy element tej tablicy jest zwracany pusty ciąg znaków (""), a jako drugi element zwracany jest opis.

                  Jeśli istnieje wiele wersji opisu (w pliku deskryptora aplikacji), tablica zawiera wiele podtablic. Każda tablica ma dwa elementy: pierwszy jest kodem języka (na przykład "en"), a drugi jest odpowiednim opisem (typu String) w tym języku. Patrz Definiowanie plików deskryptora aktualizacji i dodawanie pliku AIR do serwera internetowego.

              • StatusUpdateErrorEvent.UPDATE_ERROR — wystąpił błąd i obiekt Updater nie mógł pobrać lub zinterpretować pliku deskryptora aktualizacji.

              Pobieranie pliku AIR aktualizacji

              Obiekt ApplicationUpdater wywołuje zdarzenie updateStatus po tym, jak pomyślnie pobierze i zinterpretuje plik deskryptora aktualizacji. Zachowanie domyślne polega na rozpoczęciu pobierania pliku aktualizacji, o ile jest on dostępny. Jeśli zachowanie domyślne zostanie anulowane, można wywołać metodę downloadUpdate() w celu wznowienia procesu aktualizacji.

              appUpdater.downloadUpdate();

              Wywołanie tej metody powoduje, że obiekt Updater rozpoczyna asynchroniczne pobieranie wersji pliku AIR będącej aktualizacją.

              Metoda downloadUpdate() może wywoływać następujące zdarzenia:

              • UpdateEvent.DOWNLOAD_START — zostało nawiązane połączenie z serwerem. W przypadku użycia biblioteki ApplicationUpdaterUI to zdarzenie powoduje wyświetlenie okna dialogowego z paskiem postępu pobierania.

              • ProgressEvent.PROGRESS — wywoływane okresowo w trakcie pobierania pliku.

              • DownloadErrorEvent.DOWNLOAD_ERROR — wywoływane, jeśli podczas nawiązywania połączenia lub pobierania pliku aktualizacji wystąpi błąd. To zdarzenie jest także wywoływane w wypadku odebrania niepoprawnego statusu HTTP (np. „404 - nie znaleziono pliku”). To zdarzenie ma właściwość errorID — liczbę całkowitą, która stanowi dodatkową informację o błędzie. Dodatkowa właściwość subErrorID może zawierać dalsze informacje o błędzie.

              • UpdateEvent.DOWNLOAD_COMPLETE — obiekt Updater pomyślnie pobrał i zinterpretował plik deskryptora aktualizacji. Jeśli to zdarzenie nie zostanie anulowane, w wersji ApplicationUpdater nastąpi przejście do instalacji aktualizacji. W wersji ApplicationUpdaterUI zostanie wyświetlone okno dialogowe z opcją kontynuacji.

              Aktualizowanie aplikacji

              Obiekt ApplicationUpdater wywołuje zdarzenie downloadComplete po zakończeniu pobierania pliku aktualizacji. Jeśli zachowanie domyślne zostanie anulowane, można wywołać metodę installUpdate() w celu wznowienia procesu aktualizacji.

              appUpdater.installUpdate(file);

              Wywołanie tej metody powoduje, że obiekt Updater zainstaluje plik AIR aktualizacji. Metoda ma jeden parametr, file, który jest obiektem File wskazującym plik AIR aktualizacji.

              Obiekt ApplicationUpdater może wywołać zdarzenie beforeInstall w wyniku wywołania metody installUpdate():

              • UpdateEvent.BEFORE_INSTALL — wywoływane tuż przed zainstalowaniem aktualizacji. Niekiedy celowe jest zablokowanie instalacji aktualizacji, aby użytkownik mógł dokończyć bieżące zadania przed jej rozpoczęciem. Metoda preventDefault() obiektu Event odracza instalację do następnego uruchomienia i uniemożliwia rozpoczęcie następnego procesu aktualizacji. (Dotyczy to także aktualizacji, które byłyby wynikiem wywołania metody checkNow() lub okresowego sprawdzania dostępności).

              Instalowanie z arbitralnie wybranego pliku AIR

              Istnieje możliwość wywołania metody installFromAIRFile() w celu zainstalowania zaktualizowanej wersji aplikacji z pliku AIR na komputerze użytkownika:

              appUpdater.installFromAIRFile();

              Metoda ta powoduje, że obiekt Updater instaluje aktualizację aplikacji z pliku AIR.

              Metoda installFromAIRFile() może wywoływać następujące zdarzenia:

              • StatusFileUpdateEvent.FILE_UPDATE_STATUS — wywoływane po tym, jak obiekt ApplicationUpdater pomyślnie sprawdzi poprawność pliku przy użyciu metody installFromAIRFile(). To zdarzenie ma następujące właściwości:

                • available — ustawiana na true, jeśli dostępna jest wersja aplikacji inna niż bieżąca; false w przeciwnym wypadku (wersje są takie same).

                • version —ciąg znaków reprezentujący nową dostępną wersję.

                • path — rodzima ścieżka pliku aktualizacji.

                Można anulować to zdarzenie, jeśli właściwość available obiektu StatusFileUpdateEvent jest ustawiona na true. Anulowanie zdarzenia powoduje anulowanie aktualizacji. Aby kontynuować anulowaną aktualizację, należy wywołać metodę installUpdate().

              • StatusFileUpdateErrorEvent.FILE_UPDATE_ERROR — wystąpił błąd, a obiekt Updater nie mógł zainstalować aplikacji AIR.

              Anulowanie procesu aktualizacji

              Metoda cancelUpdate() umożliwia anulowanie procesu aktualizacji:

              appUpdater.cancelUpdate();

              Metoda ta anuluje wszystkie oczekujące operacje pobierania, usuwa wszystkie nie w pełni pobrane pliki i ponownie uruchamia zegar odliczający interwał między sprawdzeniami dostępności aktualizacji.

              Metoda nie wykonuje żadnych czynności, jeśli trwa inicjowanie obiektu Updater.

              Lokalizowanie interfejsu ApplicationUpdaterUI

              Klasa ApplicationUpdaterUI udostępnia domyślny interfejs użytkownika procesu aktualizacji. W jego skład wchodzą okna dialogowe umożliwiające rozpoczęcie procesu, anulowanie procesu i wykonywanie innych pokrewnych czynności.

              Element description pliku deskryptora aktualizacji umożliwia zdefiniowanie opisu aplikacji w wielu językach. Należy w tym celu użyć wielu elementów text definiujących atrybuty lang, co zilustrowano poniżej:

              <?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>

              Architektura aktualizacji wybiera opis najlepiej dopasowany do łańcucha lokalizacji użytkownika końcowego. Więcej informacji zawiera sekcja Definiowanie pliku deskryptora aktualizacji i dodawanie pliku AIR na serwer WWW.

              Programiści korzystający ze środowiska Flex mogą bezpośrednio dodawać nowe języki do pakunku "ApplicationUpdaterDialogs".

              W języku JavaScript można wywoływać metodę addResources() obiektu Updater. Ta metoda dynamicznie dodaje nowy pakunek zasobów dla języka. Pakunek zasobów definiuje zlokalizowane ciągi znaków w danym języku. Ciągi te są używane w polach tekstowych okien dialogowych.

              W języku JavaScript można skorzystać z właściwości localeChain klasy ApplicationUpdaterUI w celu zdefiniowania łańcucha ustawień narodowych używanego w interfejsie użytkownika. Zazwyczaj z właściwości tej korzystają tylko programiści posługujący się językiem JavaScript (HTML). W środowisku Flex do zarządzania łańcuchem ustawień narodowych można używać menedżera zasobów.

              Poniższy przykładowy kod w języku JavaScript definiuje pakunki zasobów dla języka rumuńskiego i węgierskiego:

              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;

              Szczegółowe informacje zawiera opis metody addResources() klasy ApplicationUpdaterUI w skorowidzu języka.