Atualização de aplicativos do AIR

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 AIR. O tempo de execução verifica se a ID do aplicativo e a ID do editor especificadas no arquivo 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 Arquivos descritores 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.

A seqüência de caracteres especificada como o parâmetro version do método update() deve corresponder à string no elemento version ou versionNumber do arquivo de descrição do aplicativo para o arquivo AIR a ser instalado. É necessário especificar o parâmetro version por motivo de segurança. Ao solicitar que o aplicativo verifique o número da versão do arquivo AIR, o aplicativo não instalará uma versão mais antiga de forma inadvertida. (Uma versão mais antiga do aplicativo pode conter uma vulnerabilidade de segurança que foi corrigida no aplicativo instalado no momento.) O aplicativo também deve verificar a string de versão no arquivo AIR com a string de versão no aplicativo instalado para impedir ataques de downgrade.

Antes do AIR 2.5, a seqüência de caracteres da versão pode ser de qualquer formato. Por exemplo, pode ser "2.01" ou "versão 2". No AIR 2.5 ou posterior, a seqüência de caracteres da versão deve ser uma seqüência de até três números de três dígitos separados por pontos. Por exemplo, “.0”, “1.0” e “67.89.999” são todos os números de versão válidos. Você deve validar a seqüência da versão de atualização antes de atualizar o aplicativo.

Se um aplicativo do Adobe AIR baixa um arquivo 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 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 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 Arquivos descritores do aplicativo do AIR.

A publicação de atualizações na forma ad hoc complica as tarefas de gerenciamento de versões de vários aplicativos e também faz monitoramento de dificuldade de datas de validade do certificado. Os certificados podem expirar antes que você possa publicar uma atualização

O tempo de execução do Adobe AIR trata uma atualização de aplicativo publicada sem assinatura de migração como um novo aplicativo. Os usuários devem desinstalar seu aplicativo do AIR atual antes que possam instalar a atualização do aplicativo.

Para resolver o problema, carregue cada aplicativo atualizado com o certificado mais recente para uma URL de implementação separada. Inclua um mecanismo que o lembre de aplicar assinaturas de migração quando o certificado estiver dentro do período de prorrogação de 180 dias. Consulte Assinatura de uma versão atualizada de um aplicativo do AIR para obter mais informações.

Consulte Comandos do ADT para obter mais informações sobre como aplicar assinaturas.

Realize as seguintes tarefas para simplificar o processo de aplicação das assinaturas de migração:

• Carregue cada aplicativo atualizado para uma URL de implementação separada.

• Carregue o arquivo XML descritor e o certificado mais recente para a atualização para a mesma URL.

• Marque o aplicativo atualizado com o certificado mais recente.

• Aplique uma assinatura de migração para o aplicativo atualizado com o certificado usado para assinar a versão anterior localizada em uma URL diferente.

A estrutura de atualização do AIR está incluída no diretório frameworks/libs/air do AIR 2 SDK. Isto inclui os seguintes arquivos:

• applicationupdater.swc — Define a funcionalidade básica da biblioteca de atualização para ser usada no ActionScript. Esta versão não contém nenhuma interface do usuário.

• applicationupdater.swc — Define a funcionalidade básica da biblioteca de atualização para ser usada no JavaScript. Esta versão não contém nenhuma interface do usuário.

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

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

Para mais informações, consulte as seguintes seções:

• Configuração do ambiente de desenvolvimento em Flex

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

• Exemplo básico: Uso da versão ApplicationUpdaterUI

Os arquivos SWC contidos no diretório frameworks/libs/air do AIR 2 SDK definem classes que você pode usar no desenvolvimento em Flex e Flash.

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 Flash Builder, 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 Flash Builder.

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.

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.swf:

   <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.2.5.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/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>

   Edite versionNumber, URL e description do arquivo updateDescriptor.xml para que corresponda ao seu arquivo do AIR. Este formato de descritor de atualização é usado por aplicativos que utilizam a estrutura de atualização incluída com o AIR 2.5 SDK (e posterior).

3. Crie um arquivo de texto updateDescriptor.1.0.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 AIR. Este formato de descritor de atualização é usado por aplicativos que utilizam a estrutura de atualização incluída com o AIR 2 SDK (e anterior).

   Nota: A criação deste segundo arquivo descritor de atualização só é necessária quando você oferece suporte para a atualização para aplicativos criados antes do AIR 2.5.

4. Inclua os arquivos updateDescriptor.2.5.xml e updateDescriptor.1.0.xml no mesmo diretório do servidor Web que contém o arquivo AIR de atualização.

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 ver outro exemplo de uso da estrutura de atualização, consulte os aplicativos de amostra a seguir no Adobe AIR developer center:

Conforme as regras para assinatura de números de versão para aplicativos modificados no AIR 2.5, a estrutura de atualização do AIR 2 não pode analisar as informações de versão em um descritor de aplicativo do AIR 2.5. Esta incompatibilidade significa que você deve atualizar seu aplicativo para usar a nova estrutura atualização ANTES de atualizar seu aplicativo para usar o AIR 2.5 SDK. Assim, a atualização do seu aplicativo para AIR 2.5 ou posterior a partir de qualquer versão do AIR antes do 2.5 requer DUAS atualizações. A primeira atualização deve usar o namespace AIR 2 e incluir a biblioteca de estrutura de atualização AIR 2.5 (você ainda pode criar o pacote de aplicativos usando o AIR 2.5 SDK). A segunda atualização pode usar o namespace AIR 2.5 e incluir os novos recursos do seu aplicativo.

Você também pode ter a atualização intermediária sem fazer nada exceto a atualização para seu aplicativo AIR 2.5 usando a classe Updater do AIR diretamente.

O exemplo a seguir ilustra como atualizar um aplicativo da versão 1.0 para 2.0. A versão 1.0 utiliza o antigo namespace 2.0. A versão 2.0 utiliza o namespace 2.5 e tem novos recursos implementados usando as APIs do AIR 2.5.

1. Crie uma versão intermediária do aplicativo, versão 1.0.1, baseado na versão 1.0 do aplicativo.

   1. Use a estrutura Application Updater do AIR 2.5 ao criar o aplicativo.

      Nota: Use applicationupdater.swc ou applicationupdater_ui.swc para aplicativos AIR com base na tecnologia Flash, e applicationupdater.swf ou applicationupdater_ui.swf para aplicativos AIR com base HTML.

   2. Crie um arquivo descritor de atualização para versão 1.0.1 usando o antigo namespace e a versão conforme demonstrado abaixo:

      <?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. Crie a versão 2.0 do aplicativo que usa o namespace 2.5 e as APIs do AIR 2.5.

3. Crie um descritor de atualização para atualizar o aplicativo a partir da versão 1.0.1 para a 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>

Quando você usa a estrutura de atualização do AIR, define informações básicas sobre a atualização disponível em arquivos de descritor de atualização, armazenados no servidor da Web. Um 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 formato do arquivo de descritor de atualização mudou para AIR 2.5. O novo formato usa um namespace diferente. O namespace original é “http://ns.adobe.com/air/framework/update/description/1.0”. O namespace do AIR 2.5 é “http://ns.adobe.com/air/framework/update/description/2.5”.

Os aplicativos do AIR criados antes do AIR 2.5 só podem ler a versão do descritor de atualização 1.0. Os aplicativos do AIR criados que usam a estrutura do atualizador incluída no AIR 2.5 ou posterior só podem ler o descritor de atualização da versão 2.5. Devido a essa incompatibilidade de versão, muitas vezes você precisa criar dois arquivos de descritor de atualização. A lógica de atualização na versões AIR 2.5 de seu aplicativo deve baixar um descritor de atualização que use o novo formato. As versões anteriores do aplicativo do AIR devem continuar a usar o formato original. Ambos os arquivos devem ser modificados para cada atualização que você lançar (até parar de fornecer suporte para as versões criadas antes do AIR 2.5).

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

• versionNumber — A nova versão do aplicativo do AR. Use o elemento versionNumber nos descritores de atualização usados para atualizar os aplicativos do AIR 2.5. O valor deve ser a mesma seqüência de caracteres usada no elemento versionNumber do novo arquivo de descritor do aplicativo do AIR. Se o número da versão no arquivo de descritor de atualização não corresponder ao da versão no arquivo AIR de atualização, a estrutura de atualização lançará uma exceção.

• version— A nova versão do aplicativo do AIR. Use o elemento version nos descritores de atualização usados para atualizar aplicativos criados antes do AIR 2.5. O valor deve ser a mesma seqüência de caracteres usada no elemento version do novo arquivo de descritor de aplicativo do AIR. Se a versão do arquivo de descritor de atualização não corresponder à versão do arquivo AIR, a estrutura de atualização lançará uma exceção.

• versionLabel — A seqüência de caracteres da versão legível destinada a ser exibida aos usuários. A versionLabel é opcional, mas só pode ser especificada em arquivos de descritor de atualização de versão 2.5. Use-a se utilizar uma versionLabel no descritor do aplicativo e configure-a para o mesmo valor.

• url – O local do arquivo 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 da versão 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>

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

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

Se 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/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>

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.

Após carregar a estrutura de atualização do AIR no 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ê precisa instanciar um objeto atualizador, conforme a seguir:

Exemplo do ActionScript:

var appUpdater:ApplicationUpdater = new ApplicationUpdater();

Exemplo do JavaScript:

var appUpdater = new runtime.air.update.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.

Exemplo do ActionScript:

var appUpdater:ApplicationUpdaterUI = new ApplicationUpdaterUI();

Exemplo do JavaScript:

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

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

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.

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

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

• "INSTALLING" — O atualizador está instalando o arquivo 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.

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.

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.

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.

Você pode chamar o método installFromAIRFile() para instalar a versão de atualização para instalar de um arquivo 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 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.

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.

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