Atualização de aplicativos do AIR



Os usuários podem instalar ou atualizar um aplicativo do AIR clicando duas vezes no arquivo AIR no computador ou a partir do navegador (usando o recurso de instalação direta). O aplicativo instalador do Adobe® AIR™ gerencia a instalação, alertando o usuário se ele estiver atualizando um aplicativo já existente. (Consulte Distribuição, instalação e execução de aplicativos do AIR.)

No entanto, também é possível que um aplicativo instalado se atualize automaticamente para uma nova versão usando a classe Updater. (Um aplicativo instalado pode detectar que uma nova versão está disponível para download e instalação.) A classe Updater inclui um método update() que permite apontar para um arquivo do AIR no computador do usuário e atualizar para essa versão.

As IDs do aplicativo e do editor de um arquivo do AIR de atualização devem corresponder às do aplicativo a ser atualizado. A ID do editor é derivada do certificado de autenticação, o que significa que a atualização e o aplicativo a ser atualizado devem ser assinados com o mesmo certificado.

A partir do AIR 1.1, é possível migrar um aplicativo para usar um novo certificado de autenticação de código. A migração de um aplicativo para usar uma nova assinatura envolve assinar o arquivo do AIR de atualização com os certificados novo e original. A migração de certificado é um processo unidirecional. Após a migração, somente os arquivos do AIR assinados com o novo certificado (ou com ambos) serão reconhecidos como atualizações de uma instalação existente.

Gerenciar a atualização de aplicativos pode ser complicado. O AIR 1.5 inclui a nova estrutura de atualização para aplicativos do Adobe® AIR™. Essa estrutura fornece APIs para auxiliar os desenvolvedores a fornecer bons recursos de atualização em aplicativos do AIR.

Você pode usar a migração de certificado para mudar de um certificado auto-assinado para um certificado comercial de autenticação de código ou de um certificado auto-assinado ou comercial para outro. Caso você não migre o certificado, os usuários existentes deverão remover a versão atual do seu aplicativo antes de instalar a nova. Para obter mais informações, consulte Alteração de certificados.

Sobre atualização de aplicativos

A classe Updater (no pacote flash.desktop) inclui um método, update(), que você pode usar para atualizar o aplicativo que está sendo executado com outra versão. Por exemplo, se o usuário tem uma versão do arquivo do AIR ("Sample_App_v2.air") localizada na área de trabalho, o seguinte código atualiza o aplicativo:

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

Antes de um aplicativo usar a classe Updater, o usuário ou o aplicativo deve baixar a versão atualizada do arquivo do AIR no computador. Para obter mais informações, consulte Download de um arquivo do AIR no computador do usuário.

Resultados de chamar o método Updater.update()

Quando um aplicativo no tempo de execução chama o método update(), o tempo de execução fecha o aplicativo e tenta instalar a nova versão do arquivo do AIR. O tempo de execução verifica se a ID do aplicativo e a ID do editor especificadas no arquivo do AIR correspondem às IDs do aplicativo e do editor do aplicativo que está chamando o método update(). (Para obter informações sobre a ID do aplicativo e a ID do editor, consulte Configuração de propriedades do aplicativo do AIR.) Ele também verifica se a string de versão corresponde à string version passada para o método update(). Se a instalação for concluída com êxito, o tempo de execução abrirá a nova versão do aplicativo. Do contrário (se a instalação não for concluída), ele reabrirá a versão existente (pré-instalação) do aplicativo.

No Mac OS, para instalar uma versão atualizada de um aplicativo, o usuário deve ter privilégios adequados do sistema para instalar no diretório do aplicativo. No Windows e no Linux, um usuário precisa de privilégios administrativos.

Se a versão atualizada do aplicativo exigir uma versão atualizada do tempo de execução, a nova versão do tempo de execução será instalada. Para atualizar o tempo de execução, o usuário deve ter privilégios administrativos no computador.

Durante o teste de um aplicativo usando o ADL, se o método update() for chamado, será gerada uma exceção do tempo de execução.

Sobre a string de versão

A string especificada como o parâmetro version do método update() deve corresponder à string no atributo version do principal elemento application do arquivo de descrição do aplicativo referente ao arquivo do AIR a ser instalado. É necessário especificar o parâmetro version por motivo de segurança. Ao exigir que o aplicativo verifique o número da versão no arquivo do AIR, o aplicativo não instalará inadvertidamente uma versão mais antiga, que pode conter uma vulnerabilidade de segurança corrigida no aplicativo que está instalado. O aplicativo também deve verificar a string de versão no arquivo do AIR com a string de versão no aplicativo instalado para impedir ataques de downgrade.

A string de versão pode ter qualquer formato. Por exemplo, pode ser "2.01" ou "versão 2". A decisão quanto ao formato dessa string fica a seu critério, que é o desenvolvedor do aplicativo. O tempo de execução não valida a string de versão; o código do aplicativo deve fazer isso antes de atualizar o aplicativo.

Se um aplicativo do Adobe AIR baixa um arquivo do AIR pela web, é recomendável ter um mecanismo através do qual o serviço da web possa notificar o aplicativo sobre a versão que está sendo baixada. O aplicativo poderá então usar essa string como o parâmetro version do método update(). Se o arquivo do AIR for obtido por algum outro meio, no qual a versão do arquivo é desconhecida, o aplicativo do AIR poderá examiná-lo para determinar a informação de versão. (Um arquivo do AIR consiste em um arquivo compactado no formato ZIP, e o arquivo de descrição do aplicativo é o segundo registro no arquivo.)

Para obter detalhes sobre o arquivo de descrição do aplicativo, consulte Configuração de propriedades do aplicativo do AIR.

Apresentação de uma interface de usuário de atualização do aplicativo personalizado

O AIR vem com uma interface de atualização padrão:

Essa interface sempre é usada quando o usuário instala uma versão de um aplicativo em uma máquina pela primeira vez. No entanto, você pode definir sua própria interface para usá-la em ocorrências subseqüentes. Se seu aplicativo definir uma interface de atualização personalizada, especifique um elemento customUpdateUI no arquivo de descritor do aplicativo para o aplicativo instalado no momento:

<customUpdateUI>true</customUpdateUI>

Quando o aplicativo é instalado e o usuário abre um arquivo do AIR com uma ID de aplicativo e uma ID de editor que correspondem às do aplicativo instalado, o tempo de execução abre o aplicativo em vez no instalador de aplicativo padrão do AIR. Para obter mais informações, consulte Fornecer uma interface de usuário personalizada para atualizações de aplicativos.

O aplicativo pode decidir, quando executado (quando o objeto NativeApplication.nativeApplication despacha um evento load), se o aplicativo deve ser atualizado (usando a classe Updater). Se ele optar pela atualização, poderá apresentar ao usuário sua própria interface de instalação (que é diferente da interface padrão que está sendo executada).

Download de um arquivo do AIR no computador do usuário

Para utilizar a classe Updater, primeiro o usuário ou o aplicativo deve salvar um arquivo do AIR localmente no computador do usuário.

Nota: O AIR 1.5 inclui uma estrutura de atualização, que auxilia desenvolvedores no fornecimento de bons recursos de atualização em aplicativos do AIR. Usar essa estrutura pode ser bem mais fácil que usar o método update() da classe Update diretamente. Para obter detalhes, consulte Uso da estrutura de atualização.

O código abaixo lê um arquivo do AIR a partir de uma URL (http://example.com/air/updates/Sample_App_v2.air) e salva o arquivo no diretório de armazenamento do aplicativo:

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

Para obter mais informações, consulte Fluxo de trabalho de leitura e gravação de arquivos.

Verificar se um aplicativo está sendo executado pela primeira vez

Depois que você atualizar um aplicativo, convém exibir para o usuário uma mensagem de "introdução" ou "boas-vindas". Após a inicialização, o aplicativo verifica se está sendo executado pela primeira vez para determinar se deve exibir a mensagem.

Nota: O AIR 1.5 inclui uma estrutura de atualização, que auxilia desenvolvedores no fornecimento de bons recursos de atualização em aplicativos do AIR. Essa estrutura fornece métodos fáceis para verificar se uma versão de um aplicativo está sendo executada pela primeira vez. Para obter detalhes, consulte Uso da estrutura de atualização.

Uma forma de fazer isso é salvar um arquivo no diretório de armazenamento do aplicativo depois de inicializá-lo. Sempre que o aplicativo é inicializado, deve averiguar se esse arquivo existe. Se o arquivo não existir, isso indica que o aplicativo está sendo executado pela primeira vez para o usuário atual. Se o arquivo existir, o aplicativo já foi executado pelo menos uma vez. Se o arquivo existir e contiver um número de versão mais antigo que o atual, você saberá que o usuário está executando a nova versão pela primeira vez.

Se o seu aplicativo salva dados localmente (como no diretório de armazenamento do aplicativo), convém verificar se existem dados já salvos (de versões anteriores) após a primeira execução.

Uso da estrutura de atualização

Gerenciar a atualização de aplicativos pode ser complicado. A estrutura de atualização para aplicativos AdobeAIR fornece APIs para auxiliar desenvolvedores no fornecimento de bons recursos de atualização em aplicativos do AIR. A funcionalidade na estrutura de atualização do AIR auxilia desenvolvedores a:

  • Verificar periodicamente atualizações com base em um intervalo ou na solicitação do usuário

  • Baixar arquivos do AIR (atualizações) de uma fonte da Web

  • Alertar o usuário na primeira execução da versão recém-instalada

  • Confirmar se o usuário deseja verificar atualizações

  • Exibir informações sobre a nova versão de atualização para o usuário

  • Exibir o andamento do download e as informações de erro para o usuário

A estrutura de atualização do AIR fornece um exemplo de interface de usuário que seu aplicativo pode usar. Ela fornece ao usuário informações básicas e opções relacionadas às atualizações do aplicativo. Seu aplicativo também pode definir a própria interface de usuário personalizada para uso com a estrutura de atualização.

A estrutura de atualização do AIR permite armazenar informações sobre a versão de atualização de um aplicativo AIR em arquivos de configuração XML simples. Para a maioria dos aplicativos, definir esses arquivos de configuração e incluir alguns códigos básicos fornece uma boa funcionalidade de atualização para o usuário final.

Mesmo sem usar a estrutura de atualização, o Adobe AIR inclui uma classe Updater que os aplicativos do AIR podem usar para atualizar para novas versões. Essa classe permite que um aplicativo seja atualizado para uma versão contida em um arquivo do AIR no computador do usuário. No entanto, o gerenciamento de atualização pode envolver mais que simplesmente atualizar o aplicativo com base em um arquivo do AIR armazenado localmente.

Arquivos na estrutura de atualização do AIR

A estrutura de atualização do AIR inclui os seguintes diretórios:

  • doc — A documentação (que você está lendo agora) da estrutura de atualização do AIR.

  • estruturas – Esse diretório inclui arquivos SWC, para desenvolvimento em Flex – e arquivos SWF, para desenvolvimento em HTML. Para obter mais informações, consulte estas seções (imediatamente na seqüência):

  • amostras – Este diretório inclui exemplos baseados em HTML e Flex mostrando como usar a estrutura de atualização de aplicativo. Compile e teste esses arquivos, como faria em qualquer aplicativo do AIR.

  • modelos – Este diretório contém arquivos de exemplo do descritor de atualização (simples e localizados) e arquivos de configuração. (Para obter mais informações sobre esses arquivos, consulte Configuração do ambiente de desenvolvimento em Flex e Exemplo básico: Uso da versão ApplicationUpdaterUI).

Configuração do ambiente de desenvolvimento em Flex

O diretório frameworks/flex da estrutura de atualização inclui estes arquivos:

  • ApplicationUpdater.swc — Define a funcionalidade básica da biblioteca de atualização, sem qualquer interface do usuário

  • ApplicationUpdater_UI.swc — Define a funcionalidade básica da biblioteca de atualização, incluindo uma interface de usuário que seu aplicativo usa para exibir opções de atualização

Os arquivos SWC definem classes que você pode usar no desenvolvimento de Flex.

Para usar a estrutura de atualização ao compilar com o Flex SDK, inclua o arquivo ApplicationUpdater.swc ou o ApplicationUpdater_UI.swc na chamada do compilador amxmlc. No exemplo a seguir, o compilador carrega o arquivo ApplicationUpdater.swc no subdiretório lib do diretório Flex SDK:

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

No exemplo a seguir, o compilador carrega o arquivo ApplicationUpdater_UI.swc no subdiretório lib do diretório Flex SDK:

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

Ao desenvolver usando o construtor Flex, adicione o arquivo SWC à guia Caminho da biblioteca das configurações do caminho de criação de Flex na caixa de diálogo Propriedades.

Assegure-se de copiar os arquivos SWC no diretório que você usará como referência no compilador amxmlc (usando o Flex SDK) ou Flex Builder.

Inclusão de arquivos de estrutura em um aplicativo do AIR baseado em HTML

O diretório frameworks/html da estrutura de atualização inclui estes arquivos:

  • ApplicationUpdater.swf — Define a funcionalidade básica da biblioteca de atualização, sem qualquer interface do usuário

  • ApplicationUpdater_UI.swf — Define a funcionalidade básica da biblioteca de atualização, incluindo uma interface de usuário que seu aplicativo usa para exibir opções de atualização

O código JavaScript nos aplicativos do AIT podem usar classes definidas nos arquivos SWF.

Para usar a estrutura de atualização, inclua o arquivo ApplicationUpdater.swf ou o ApplicationUpdater_UI.swf no diretório do aplicativo (ou um subdiretório). Em seguida, no arquivo HTML que usará a estrutura (em código JavaScript), inclua uma tag script que carregue o arquivo:

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

Ou use essa tag script para carregar o arquivo ApplicationUpdater_UI.swf:

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

A API definida nesses dois arquivos é descrita no restante deste documento.

Exemplo básico: Uso da versão ApplicationUpdaterUI

A versão ApplicationUpdaterUI da estrutura de atualização fornece uma interface básica que pode ser facilmente usada no seu aplicativo. A seguir há um exemplo básico:

Primeiro, crie um aplicativo do AIR que chame a estrutura de atualização:

  1. Se seu aplicativo for um aplicativo do AIR baseado em HTML, carregue o arquivo ApplicationUpdaterUI.js:

    <script src="ApplicationUpdater_UI.swf" type="application/x-shockwave-flash"/>
  2. Na lógica de programação do aplicativo do AIR, instancie um objeto do ApplicationUpdaterUI.

    No ActionScript, use o seguinte código:

    var appUpdater:ApplicationUpdaterUI = new ApplicationUpdaterUI(); 

    No JavaScript, use o seguinte código:

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

    Você pode adicionar esse código a uma função de inicialização executada quando o aplicativo é carregado.

  3. Crie um arquivo de texto updateConfig.xml e adicione o seguinte a ele:

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

    Edite o elemento URL do arquivo updateConfig.xml para que corresponda à localização eventual do arquivo de descritor de atualização do seu servidor da Web (veja o próximo procedimento).

    O delay é o número de dias que o aplicativo aguarda entre as verificações de atualizações.

  4. Adicione o arquivo updateConfig.xml ao diretório do projeto do seu aplicativo do AIR.

  5. Faça com que o objeto updater referencie o arquivo updateConfig.xml e chame o método initialize() do objeto.

    No ActionScript, use o seguinte código:
    appUpdater.configurationFile = new File("app:/updateConfig.xml"); 
    appUpdater.initialize();
    No JavaScript, use o seguinte código:
    appUpdater.configurationFile = new air.File("app:/updateConfig.xml"); 
    appUpdater.initialize();
  6. Crie uma segunda versão do aplicativo AIR que tenha uma versão diferente do primeiro aplicativo. (A versão é especificada no arquivo de descritor do aplicativo, no elemento version.)

Em seguida, adicione a versão de atualização do aplicativo do AIR ao servidor da Web:

  1. Coloque a versão de atualização do arquivo AIR no servidor da Web.

  2. Crie um arquivo de texto updateDescriptor.xml e adicione o seguinte conteúdo a ele:

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

    Edite version, URL e description do arquivo updateDescriptor.xml para que corresponda ao seu arquivo do AIR.

  3. Adicione o arquivo updateDescriptor.xml ao mesmo diretório do servidor da Web que contém o arquivo do AIR atualizado.

Esse é um exemplo básico, mas fornece a funcionalidade de atualização suficiente para vários aplicativos. O restante deste documento descreve como usar a estrutura de atualização para atender melhor suas necessidades.

Para obter outro exemplo de uso da estrutura de atualização, consulte o seguinte aplicativo de amostra no Centro de desenvolvedores do Adobe AIR: Estrutura de atualização em um aplicativo com base no Flash(http://www.adobe.com/go/learn_air_qs_update_framework_flash_en).

Definição do arquivo de descritor de atualização a acréscimo do arquivo do AIR ao servidor da Web.

Quando você usa a estrutura de atualização do AIR, define informações básicas sobre a atualização disponível em um arquivo de descritor de atualização, armazenado no servidor da Web. O arquivo de descritor de atualização é um arquivo XML simples. A estrutura de atualização incluída no aplicativo verifica esse arquivo para ver se uma nova versão foi carregada.

O arquivo de descritor de atualização contém os seguintes dados:

  • version— A nova versão do aplicativo do air. Deve ser a mesma seqüência de caracteres usada no novo arquivo de descritor do aplicativo air da versão. Se a versão do arquivo de descritor de atualização não corresponder à versão do arquivo do AIR, a estrutura de atualização lançará uma exceção.

  • url – O local do arquivo do AIR de atualização. Esse arquivo contém a versão de atualização do aplicativo AIR.

  • description — Detalhes relativos à nova versão. Essas informações podem ser exibidas para o usuário durante o processo de atualização.

Os elementos version e url são obrigatórios. O elemento description é opcional.

Este é um exemplo de arquivo de descritor de atualização:

<?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>This is the latest version of the Sample application.</description> 
    </update>

Se desejar definir a tag description usando vários idiomas, use vários elementos text que definam o atributo lang:

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

Coloque o arquivo de descritor de atualização no servidor da Web, juntamente com o arquivo de atualização do AIR.

O diretório modelo incluído com o descritor de atualização inclui exemplos dos arquivos descritores de atualização. Eles incluem versões com um idioma ou vários idiomas.

Instanciação de um objeto atualizador

Depois de carregar a estrutura de atualização do AIR em seu código (consulte Configuração do ambiente de desenvolvimento em Flex e Inclusão de arquivos de estrutura em um aplicativo do AIR baseado em HTML), você deverá instanciar um objeto atualizador, como no exemplo a seguir:

var appUpdater:ApplicationUpdater = new ApplicationUpdater();

O código anterior usa a classe ApplicationUpdater (que não fornece interface de usuário). Se você deseja usar a classe ApplicationUpdaterUI (que fornece uma interface de usuário), use o seguinte:

var appUpdater:ApplicationUpdaterUI = new ApplicationUpdaterUI();

Os exemplos de código restantes neste documento supõem que você tenha instanciado um objeto atualizador appUpdater.

Definição das configurações de atualização

O ApplicationUpdater e o ApplicationUpdaterUI podem ser configurados por meio de um arquivo de configuração fornecido com o aplicativo ou por meio de ActionScript ou JavaScript no aplicativo.

Definição das configurações de atualização em um arquivo de configuração XML

O arquivo de configuração de atualização é um arquivo XML. Ele pode conter os seguintes elementos:

  • updateURL— Uma seqüência de caracteres. Representa a localização do descritor de atualização no servidor remoto. Qualquer localização de URLRequest válida é permitida. Você deve definir a propriedade updateURL pelo arquivo de configuração ou por script (consulte Definição do arquivo de descritor de atualização a acréscimo do arquivo do AIR ao servidor da Web.). Defina essa propriedade antes de usar o atualizador (antes de chamar o método initialize() do objeto atualizador, descrito em Inicialização da estrutura de atualização).

  • delay— Um número. Representa um intervalo de tempo fornecido em dias (valores como 0,25 são permitidos) para verificação de atualizações. Um valor de 0 (que é o valor padrão) especifica que o atualizador não realiza uma verificação automática periódica.

O arquivo de configuração do ApplicationUpdaterUI pode conter o seguinte elemento, além dos elementos updateURL e delay:

  • defaultUI: Uma lista de elementos dialog. Cada elemento dialog tem um atributo name que corresponde à caixa de diálogo na interface do usuário. Cada elemento dialog tem um atributo visible que define se a caixa de diálogo está visível. O valor padrão é true. Valores possíveis para o atributo name são:

    • "checkForUpdate" – Corresponde às caixas de diálogo Verificar atualizações, Nenhuma atualização e Erro de atualização.

    • "downloadUpdate"— Corresponde à caixa de diálogo Fazendo download de atualização.

    • "downloadProgress"—Corresponde às caixas de diálogo Download em andamento e Erro de download.

    • "installUpdate"— Corresponde à caixa de diálogo Instalar atualização.

    • "fileUpdate"— Corresponde às caixas de diálogo Atualização de arquivo, Não atualização de arquivo e Erro de arquivo

  • "unexpectedError"— Corresponde à caixa de diálogo Erro inesperado

    Quando definida como false, a caixa de diálogo correspondente não aparece como parte do procedimento de atualização.

Este é um exemplo do arquivo de configuração para a estrutura 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>

Este é um exemplo do arquivo de configuração para a estrutura ApplicationUpdaterUI, que inclui uma definição para o 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>

Aponte a propriedade configurationFile para o local desse arquivo: como no seguinte

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

O diretório modelo da estrutura de atualização inclui um exemplo de arquivo de configuração, o config-template.xml.

Definição das configurações de atualização do código ActionScript ou JavaScript

Esses parâmetros de configuração também podem ser definidos usando código no aplicativo, como a seguir:

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

As propriedades do objeto atualizador são updateURL e delay. Essas propriedades definem as mesmas configurações dos elementos updateURL e delay no arquivo de configuração: o URL e o arquivo de descritor de atualização e o intervalo de verificação de atualizações. Se você especificar as configurações and de um arquivo de configuração no código, todas as propriedades definidas usando o código terão precedência sobre as configurações correspondentes no arquivo de configuração.

Você deve definir a propriedade updateURL por meio do arquivo de configuração ou por meio de script (consulte Definição do arquivo de descritor de atualização a acréscimo do arquivo do AIR ao servidor da Web.) antes de usar o atualizador (antes de chamar o método initialize() do objeto atualizador, descrito em Inicialização da estrutura de atualização).

A estrutura ApplicationUpdaterUI define essas propriedades adicionais do objeto atualizador:

  • isCheckForUpdateVisible – Corresponde às caixas de diálogo Verificar atualizações, Nenhuma atualização e Erro de atualização.

  • isDownloadUpdateVisible— Corresponde à caixa de diálogo Fazendo download de atualização.

  • isDownloadProgressVisible —Corresponde às caixas de diálogo Download em andamento e Erro de download.

  • isInstallUpdateVisible — Corresponde à caixa de diálogo Instalar atualização.

  • isFileUpdateVisible — Corresponde às caixas de diálogo Atualização de arquivo, Não atualização de arquivo e Erro de arquivo

  • isUnexpectedErrorVisible — Corresponde à caixa de diálogo Erro inesperado

Cada propriedade corresponde a uma ou mais caixa de diálogo da interface de usuário ApplicationUpdaterUI. Cada propriedade é um valor booleano com um valor padrão true. Quando definida como false, a caixa de diálogo correspondente não aparece como parte do procedimento de atualização.

Essas propriedades de caixa de diálogo substituem as configurações no arquivo de configuração de atualização.

O processo de atualização

A estrutura de atualização do AIR completa o processo de atualização nas seguintes etapas:

  1. A inicialização do atualizador verifica se foi realizada uma verificação de atualização no intervalo de tempo definido (consulte Definição das configurações de atualização). Se estiver faltando uma verificação de atualização, o processo de atualização continuará.

  2. O atualizador baixa e interpreta o arquivo de descritor de atualização.

  3. O atualizador baixa o arquivo AIR de atualização.

  4. O atualizador instala a versão atualizada do aplicativo.

O objeto atualizador despacha eventos na conclusão de cada uma das etapas. Na versão do ApplicationUpdater, você pode cancelar os eventos que indicam a conclusão bem-sucedida de uma etapa no processo. Se você cancelar um desses eventos, a próxima etapa do processo será cancelada. Na versão do ApplicationUpdaterUI, o atualizador apresenta uma caixa de diálogo permitindo que o usuário cancele ou continue para a próxima etapa do processo.

Se você cancelar o evento, poderá chamar métodos do objeto atualizador para retomar o processo.

Conforme a versão do ApplicationUpdater do atualizador progride pelo processo de atualização, ela registra seu estado atual em uma propriedade currentState. Essa propriedade é definida como uma seqüência de caracteres com os seguintes valores possíveis:

  • "UNINITIALIZED" — O atualizador não foi inicializado.

  • "INITIALIZING" — O atualizador está sendo inicializado.

  • "READY" — O atualizador foi inicializado

  • "BEFORE_CHECKING" — O atualizador ainda não verificou se existe um arquivo de descritor de atualização.

  • "CHECKING" — O atualizador está verificando se existe um arquivo de descritor de atualização.

  • "AVAILABLE" — O arquivo de descritor de atualização está disponível.

  • "DOWNLOADING" — O atualizador está baixando o arquivo do AIR.

  • "DOWNLOADED" — O atualizador baixou o arquivo do AIR.

  • "INSTALLING" — O atualizador está instalando o arquivo do AIR.

  • "PENDING_INSTALLING" — O atualizador foi inicializado e não há atualizações pendentes.

Alguns métodos do objeto atualizador só serão executados se o atualizador estiver em determinado estado.

Inicialização da estrutura de atualização

Depois de definir as propriedades de configuração (consulte Exemplo básico: Uso da versão ApplicationUpdaterUI), chame o método initialize() para inicializar a atualização:

appUpdater.initialize();

Esse método faz o seguinte:

  • Ele inicializa a estrutura de atualização, instalando de forma silenciosa e síncrona todas as atualizações pendentes. É necessário para chamar esse método durante a inicialização do aplicativo, pois ele pode reiniciar o aplicativo quando chamado.

  • Ele verifica se existe uma atualização adiada e a instala;

  • Se houver um erro durante o processo de atualização, ele limpa o arquivo de atualização e as informações de versão da área de armazenamento do aplicativo.

  • Se o tempo limite tiver expirado, o processo de atualização e iniciado. Caso contrário, ele inicia o timer.

Chamar esse método pode resultar no despacho dos seguintes eventos pelo objeto atualizador:

  • UpdateEvent.INITIALIZED — Despachado quando a inicialização é concluída.

  • ErrorEvent.ERROR — Despachado quando há um erro na inicialização.

No despacho do evento UpdateEvent.INITIALIZED, o processo de atualização é concluído.

Quando você chama o método initialize(), o atualizador inicia o processo de atualização e conclui todas as etapas com base na configuração de tempo do timer. No entanto, você também pode iniciar o processo de atualização a qualquer momento chamando o método checkNow() do objeto atualizador:

appUpdater.checkNow();

Esse método não faz nada se o processo de atualização já estiver em execução. Caso contrário, ele começa o processo de atualização.

O objeto atualizador pode despachar o seguinte evento como resultado de chamar o método checkNow():

  • Evento UpdateEvent.CHECK_FOR_UPDATE, antes de ele tentar baixar o arquivo de descritor de atualização.

Se você cancelar o evento checkForUpdate, poderá chamar o método checkForUpdate() do objeto atualizador. (Consulte a próxima seção.) Se você não cancelar o evento, o processo de atualização continuará para verificar se há arquivo de descritor de atualização.

Gerenciamento do processo de atualização na versão ApplicationUpdaterUI

Na versão ApplicationUpdaterUI, o usuário pode cancelar o processo pelos botões Cancelar das caixas de diálogo da interface de usuário. Além disso, você pode cancelar de forma programática o processo de atualização chamando o método cancelUpdate() do objeto ApplicationUpdaterUI.

Você pode definir as propriedades do objeto ApplicationUpdaterUI ou definir elementos no arquivo de configuração de atualização para especificar quais confirmações de caixa de diálogo o atualizador exibe. Para obter detalhes, consulte Definição das configurações de atualização.

Gerenciamento do processo de atualização na versão ApplicationUpdater

Você pode chamar o método preventDefault() dos objetos de evento despachados pelo objeto ApplicationUpdater para cancelar etapas do processo de atualização (consulte O processo de atualização). Cancelar o comportamento padrão fornece ao seu aplicativo uma chance de exibir uma mensagem ao usuário perguntando se ele deseja continuar.

As seções a seguir descrevem como continuar o processo de atualização quando uma etapa do processo é cancelada.

Download e interpretação do arquivo de descritor de atualização

O objeto ApplicationUpdater despacha o evento checkForUpdate antes do processo de atualização ser iniciado, logo antes de o atualizador tentar baixar o arquivo de descritor de atualização. Se você cancelar o comportamento padrão do evento checkForUpdate, o atualizador não baixará o arquivo de descritor de atualização. Você pode chamar o método checkForUpdate() para retomar o processo de atualização:

appUpdater.checkForUpdate();

Chamar o método checkForUpdate() faz com que o atualizador baixe de forma assíncrona e interprete o arquivo de descritor de atualização. Como resultado de chamar o método checkForUpdate(), o objeto atualizador poderá despachar os seguintes eventos:

  • StatusUpdateEvent.UPDATE_STATUS — O atualizador baixou e interpretou o arquivo de descritor de atualização com êxito. Esse evento tem estas propriedades:

    • available — Um valor booleano. Defina como true se houver uma versão disponível diferente da versão do aplicativo atual; false, para o contrário (a versão é a mesma).

    • version — Uma seqüência de caracteres. A versão do arquivo de descritor de aplicativo do arquivo de atualização

    • details — Uma matriz. Se não houver versões localizadas da descrição, essa matriz retornará uma seqüência de caracteres vazia ("") como primeiro elemento e a descrição como segundo elemento.

      Se houver várias versões da descrição (no arquivo de descritor de atualização), a matriz conterá várias submatrizes. Cada matriz tem dois elementos: o primeiro é um código de idiomas (como "en") e o segundo é a descrição correspondente (uma seqüência de caracteres) para o idioma. Consulte Definição do arquivo de descritor de atualização a acréscimo do arquivo do AIR ao servidor da Web..

  • StatusUpdateErrorEvent.UPDATE_ERROR — Ocorreu e o atualizador não pôde baixar ou interpretar o arquivo de descritor de eventos.

Download do arquivo de atualização do AIR

O objeto ApplicationUpdater despacha o evento updateStatus depois que o atualizador baixa e interpreta com êxito o arquivo de descritor de atualização. O comportamento padrão é começar a baixar o arquivo de atualização, se ele estiver disponível. Se você cancelar o comportamento padrão, poderá chamar o método downloadUpdate() para retomar o processo de atualização.

appUpdater.downloadUpdate();

Chamar esse método faz com que o atualizador baixe de forma assíncrona a versão de atualização do arquivo do AIR.

O método downloadUpdate() pode despachar os seguintes eventos:

  • UpdateEvent.DOWNLOAD_START — Foi estabelecida a conexão com o servidor. Quando você usa a biblioteca ApplicationUpdaterUI, esse evento exibe uma caixa de diálogo com uma barra de progresso para controlar o andamento do download.

  • ProgressEvent.PROGRESS — Despachado periodicamente conforme o download do arquivo progride.

  • DownloadErrorEvent.DOWNLOAD_ERROR — Despachado se houver um erro na conexão ou no download do arquivo de atualização. Também é despachado para status de HTTP inválidos (como " 404 - Arquivo não encontrado"). Esse evento tem uma propriedade errorID, um inteiro que define informações de erro adicionais. Uma propriedade subErrorID adicional pode conter mais informações de erro.

  • UpdateEvent.DOWNLOAD_COMPLETE — O atualizador baixou e interpretou o arquivo de descritor de atualização com êxito. Se você não cancelar esse evento, a versão do ApplicationUpdater continuará a instalar a versão de atualização. Na versão do ApplicationUpdaterUI, o usuário visualiza uma caixa de diálogo que fornece a opção de continuar.

Atualização do aplicativo

O objeto ApplicationUpdater despacha o evento downloadComplete quando o download do arquivo de atualização é concluído. Se você cancelar o comportamento padrão, poderá chamar o método installUpdate() para retomar o processo de atualização.

appUpdater.installUpdate(file);

Chamar esse método faz com que o atualizador instale uma versão de atualização do arquivo do AIR. O método inclui um parâmetro, file, que é um objeto File que referencia o arquivo do AIR a ser usado como atualização.

O objeto ApplicationUpdater pode despachar e evento beforeInstall como resultado de chamar o método installUpdate():

  • UpdateEvent.BEFORE_INSTALL — Despachado antes de instalar a atualização. Às vezes, é útil impedir a instalação da atualização nesse momento, para que o usuário possa concluir o trabalho atual antes de a atualização continuar. Chamar o método preventDefault() do objeto Event adia a instalação até o próximo reinício, e nenhum processo de atualização adicional pode ser iniciado. (Isso inclui atualizações que resultariam de chamar o método checkNow() ou de verificações periódicas.)

Instalação de um arquivo do AIR arbitrário

Você pode chamar o método installFromAIRFile() para instalar a versão de atualização para instalar de um arquivo do AIR no computador do usuário.

appUpdater.installFromAIRFile();

Esse método faz com que o atualizador instale uma versão de atualização do aplicativo a partir do arquivo do AIR.

O método installFromAIRFile() pode despachar os seguintes eventos:

  • StatusFileUpdateEvent.FILE_UPDATE_STATUS — Despachado depois que ApplicationUpdater valida com êxito o arquivo envaido usando o método installFromAIRFile(). Esse evento tem as seguintes propriedades:

    • available — Definida como true se houver uma versão diferente da versão do aplicativo atual; false caso contrário (as versões são as mesmas).

    • version — A string que representa a nova versão disponível.

    • path — Representa o caminho nativo do arquivo de atualização.

    Você pode cancelar esse evento se a propriedade disponível do objeto StatusFileUpdateEvent estiver definida como true. O cancelamento do evento impede a continuidade da atualização. Chame o método installUpdate() para continuar a atualização cancelada.

  • StatusFileUpdateErrorEvent.FILE_UPDATE_ERROR — Ocorreu um erro e o atualizador não pôde instalar o aplicativo AIR.

Cancelamento do processo de atualização

Você pode chamar o método cancelUpdate() para cancelar o processo de atualização:

appUpdater.cancelUpdate();

Esse método cancela os downloads pendentes, excluindo arquivos baixados incompletos, e reinicia o timer de verificação periódica.

O método não faz nada se o objeto atualizador estiver sendo inicializado.

Localização da interface ApplicationUpdaterUI

A classe ApplicationUpdaterUI fornece uma interface de usuário padrão para o processo de atualização. Isso inclui caixas de diálogo que permitem que o usuário inicie o processo, cancele o processo e realize outras ações relacionadas.

O elemento description do arquivo de descritor de atualização permite definir a descrição do aplicativo em vários idiomas. Use vários elementos text que definem atributos lang, como a seguir:

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

A estrutura de atualização usa a descrição mais adequada para a cadeia de localização do usuário. Para obter mais informações, consulte Definição do arquivo de descritor de atualização a acréscimo do arquivo do AIR ao servidor da Web.

Desenvolvedores de Flex podem adicionar diretamente um novo idioma ao grupo "ApplicationUpdaterDialogs".

Desenvolvedores de JavaScript podem chamar o método addResources() do objeto atualizador. Esse método adiciona dinamicamente um novo conjunto de recursos para um idioma. O conjunto de recursos define seqüências de caracteres localizadas para um idioma. Essas seqüências de caracteres são usadas em vários campos de texto de caixa de diálogo.

Desenvolvedores de JavaScript podem usar a propriedade localeChain da classe ApplicationUpdaterUI para definir a cadeia de localização usada pela interface do usuário. Geralmente, somente desenvolvedores de JavaScript (HTML) usam essa propriedade. Desenvolvedores de Flex usam o ResourceManager para gerenciar a cadeia de localização.

Por exemplo, o código de JavaScript a seguir define grupos de recursos para romano e húngaro.

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;

Para obter detalhes, consulte a descrição do método addResources() da classe ApplicationUpdaterUI na referência de idiomas.