Instalação e execução de aplicativos do AIR de uma página da Web



O recurso de instalação direta permite que você incorpore um arquivo SWF em uma página da Web que permite ao usuário instalar um aplicativo do AIR do navegador. Se o tempo de execução não for instalado, o recurso de instalação direta instalará o tempo de execução. O recurso de instalação direta permite que usuários instalem o aplicativo do AIR sem salvar o arquivo do AIR em seus computadores. Incluído no SDK do AIR está um arquivo badge.swf, que permite a você usar facilmente o recurso de instalação direta. Para obter detalhes, consulte Usando o arquivo badge.swf para instalar um aplicativo do AIR.

Para obter uma demonstração de como usar o recurso de instalação direta, consulte o artigo de amostra de início rápido Distribuição de um aplicativo do AIR pela Web (http://www.adobe.com/go/learn_air_qs_seamless_install_en).

Sobre a personalização de badge.swf para instalação direta

Além de usar o arquivo badge.swf fornecido com o SDK, você pode criar seu próprio arquivo SWF para usar em uma página do navegador. Seu arquivo SWF personalizado pode interagir com o tempo de execução das seguintes maneiras:

Esses recursos são todos fornecidos ao chamar as APIs em um arquivo SWF hospedado em adobe.com: air.swf. Esta seção descreve como usar e personalizar o arquivo badge.swf e como chamar as APIs do air.swf do seu próprio arquivo SWF.

Além disso, um arquivo SWF em execução no navegador pode se comunicar com um aplicativo do AIR em execução usando a classe LocalConnection. Para obter mais informações, consulte Comunicação entre aplicativos.

Importante: Os recursos descritos nesta seção (e as APIs no arquivo air.swf) exigem que o usuário final tenha a atualização 3 do Adobe® Flash® Player 9 instalada no navegador da Web no Windows ou Mac OS. No Linux, o recurso de instalação contínua requer o Flash Player 10 (versão 10,0,12,36 ou posterior). Você pode escrever códigos para verificar a versão instalada do Flash Player e fornecer uma interface alternativa ao usuário se a versão exigida do Flash Player não for instalada. Por exemplo, se uma versão mais antiga do Flash Player for instalada, você poderia fornecer um link para a versão de download do arquivo do AIR (em vez de usar o arquivo badge.swf ou a API do air.swf para instalar um aplicativo).

Usando o arquivo badge.swf para instalar um aplicativo do AIR

Incluído no SDK do AIR está um arquivo badge.swf, que permite a você usar facilmente o recurso de instalação direta. O badge.swf pode instalar o tempo de execução e um aplicativo do AIR de um link em uma página da Web. O arquivo badge.swf e seu código-fonte são fornecidos a você para distribuição no seu site da Web.

As instruções nesta seção fornecem informações sobre a definição de parâmetros do arquivo badge.swf fornecido pela Adobe. Também fornecemos o código-fonte para o arquivo badge.swf, que você pode personalizar.

Incorporação do arquivo badge.swf em uma página da Web

  1. Localize os arquivos a seguir, fornecidos no diretório de exemplos/crachás do SDK do AIR, e adicione-os ao seu servidor Web.

    • badge.swf

    • default_badge.html

    • AC_RunActiveContent.js

  2. Abra a página default_badge.html em um editor de texto.

  3. Na página default_badge.html, na função JavaScript AC_FL_RunContent(), ajuste as definições do parâmetro FlashVars para as seguintes:

    Parâmetro

    Descrição

    appname

    O nome do aplicativo, exibido pelo arquivo SWF quando o tempo de execução não está instalado.

    appurl

    (Obrigatório). A URL do arquivo do AIR a ser obtido por download. Você deve usar uma URL absoluta, e não relativa.

    airversion

    (Obrigatório). Para a versão 1.0 do tempo de execução, defina isso para 1.0.

    imageurl

    A URL da imagem (opcional) para exibir no crachá.

    buttoncolor

    A cor do botão de download (especificada como um valor hexadecimal, como FFCC00).

    messagecolor

    A cor da mensagem de texto exibida abaixo do botão quando o tempo de execução não está instalado (especificada como um valor hexadecimal, como FFCC00).

  4. O tamanho mínimo do arquivo badge.swf é de 217 pixels de largura por 180 pixels de altura. Ajuste os valores dos parâmetros width e height da função AC_FL_RunContent() para se adequar às suas necessidades.

  5. Renomeie o arquivo default_badge.html e ajuste seu código (ou inclua-o em outra página HTML) para se adequar às suas necessidades.

Você também pode editar e recompilar o arquivo badge.swf. Para obter detalhes, consulte Modificação do arquivo badge.swf.

Instalação do aplicativo do AIR de um link de instalação direta em uma página da Web

Depois de ter adicionado o link de instalação direta a uma página, o usuário pode instalar o aplicativo do AIR clicando no link no arquivo SWF.

  1. Navegue até a página HTML em um navegador da Web que tenha Flash Player (versão 9 atualização 3 ou posterior no Windows e Mac OS ou versão 10 no Linux) instalada.

  2. Na página da Web, clique no link no arquivo badge.swf.

    • Se tiver instalado o tempo de execução, passe para a próxima etapa.

    • Se não tiver instalado o tempo de execução, uma caixa de diálogo será exibida perguntando se você gostaria de instalá-lo. Instale o tempo de execução (consulte Instalação do Adobe AIR) e continue com a etapa seguinte.

  3. Na janela de instalação, deixe as configurações padrão selecionadas e clique em Continuar.

    Em um computador Windows, o AIR faz automaticamente o seguinte:

    • Instala o aplicativo em c:\Arquivos de Programas\

    • Cria um atalho na área de trabalho para o aplicativo

    • Cria um atalho no menu Iniciar

    • Adiciona uma entrada para o aplicativo no Painel de Controle Adicionar ou Remover Programas

    No Mac OS, o instalador adiciona o aplicativo ao diretório Aplicativos (por exemplo, no diretório /Aplicativos no Mac OS).

    Em um computador Linux, o AIR faz automaticamente o seguinte:

    • Instala o aplicativo na /saída.

    • Cria um atalho na área de trabalho para o aplicativo

    • Cria um atalho no menu Iniciar

    • Adicione uma entrada para o aplicativo no gerenciador de pacotes do sistema

  4. Selecione as opções desejadas e clique no botão Instalar.

  5. Quando a instalação estiver concluída, clique em Concluir.

Modificação do arquivo badge.swf

O SDK do AIR fornece os arquivos de origem para o arquivo badge.swf. Esses arquivos estão incluídos na pasta samples/badge do SDK:

Arquivos de origem

Descrição

badge.fla

O arquivo de origem do Flash usado para compilar o arquivo badge.swf. O arquivo badge.fla é compilado em um arquivo do SWF 9 (que pode ser carregado no Flash Player).

AIRBadge.as

Uma classe do ActionScript 3.0 que define a classe base usada no arquivo basdge.fla.

Você pode usar o Flash CS3 ou o Flash CS4 para reprojetar a interface visual do arquivo badge.fla.

A função de construtor AIRBadge(), definida na classe AIRBadge, carrega o arquivo air.swf hospedado em http://airdownload.adobe.com/air/browserapi/air.swf. O arquivo air.swf inclui código para usar o recurso de instalação direta.

O método onInit() (na classe AIRBadge) é invocado quando o arquivo air.swf é carregado com sucesso:

private function onInit(e:Event):void { 
    _air = e.target.content; 
    switch (_air.getStatus()) { 
        case "installed" : 
            root.statusMessage.text = ""; 
            break; 
        case "available" : 
            if (_appName && _appName.length > 0) { 
                root.statusMessage.htmlText = "<p align='center'><font color='#"  
                        + _messageColor + "'>In order to run " + _appName +  
                        ", this installer will also set up Adobe® AIR™.</font></p>"; 
            } else { 
                root.statusMessage.htmlText = "<p align='center'><font color='#"  
                        + _messageColor + "'>In order to run this application, " 
                        + "this installer will also set up Adobe® AIR™.</font></p>"; 
            } 
            break; 
        case "unavailable" : 
            root.statusMessage.htmlText = "<p align='center'><font color='#"  
                        + _messageColor  
                        + "'>Adobe® AIR™ is not available for your system.</font></p>"; 
            root.buttonBg_mc.enabled = false; 
            break; 
    } 
}

O código define a variável global _air para a classe principal do arquivo air.swf carregado. Essa classe inclui os seguintes métodos públicos, que o arquivo badge.swf acessa para chamar a funcionalidade de instalação direta:

Método

Descrição

getStatus()

Determina se o tempo de execução é instalado (ou pode ser instalado) no computador. Para obter detalhes, consulte Verificar se o tempo de execução está instalado.

installApplication()

Instala o aplicativo especificado na máquina do usuário. Para obter detalhes, consulte Instalação de um aplicativo do AIR do navegador.

  • url — Uma seqüência de caracteres que define a URL. Você deve usar um caminho de URL absoluta, e não relativa.

  • runtimeVersion — Uma string que indica a versão do tempo de execução (como "1.0.M6") exigida pelo aplicativo a ser instalado.

  • arguments — Argumentos a serem transmitidos ao aplicativo se ele for iniciado na instalação. O aplicativo é iniciado na instalação se o elemento allowBrowserInvocation é definido como true no arquivo do descritor do aplicativo. (Para obter mais informações sobre o arquivo do descritor do aplicativo, consulte Configuração de propriedades do aplicativo do AIR.) Se o aplicativo for iniciado como resultado de uma instalação direta do navegador (com o usuário optando por iniciar na instalação), o objeto NativeApplication do aplicativo despacha um objeto BrowserInvokeEvent apenas se argumentos forem transmitidos. Considere as implicações de segurança de dados que você transmite ao aplicativo. Para obter detalhes, consulte Inicialização de um aplicativo do AIR instalado do navegador.

As configurações para url e runtimeVersion são transmitidas no arquivo SWF pelas configurações do FlashVars na página HTML do contêiner.

Se o aplicativo for iniciado automaticamente na instalação, você poderá usar a comunicação LocalConnection para ter o aplicativo instalado. Entre em contato com o arquivo badge.swf na invocação. Para obter detalhes, consulte Comunicação entre aplicativos.

Você também pode chamar o método getApplicationVersion() do arquivo air.swf para verificar se um aplicativo está instalado. Você pode chamar esse método antes do processo de instalação do aplicativo ou após a instalação ser iniciada. Para obter detalhes, consulte Verificar por uma página da Web se um aplicativo do AIR está instalado.

Carregar o arquivo air.swf

Você pode criar seu próprio arquivo do SWF que usa as APIs no arquivo air.swf para interagir com o tempo de execução e aplicativos do AIR de uma página da Web em um navegador. O arquivo air.swf é hospedado em http://airdownload.adobe.com/air/browserapi/air.swf. Para se referir às APIs do air.swf do seu arquivo SWF, carregue o arquivo air.swf no mesmo domínio de aplicativo do seu arquivo SWF. O código a seguir mostra um exemplo de como carregar o arquivo air.swf no domínio do aplicativo do arquivo SWF que está sendo carregado:

var airSWF:Object; // This is the reference to the main class of air.swf 
var airSWFLoader:Loader = new Loader(); // Used to load the SWF 
var loaderContext:LoaderContext = new LoaderContext();  
                                // Used to set the application domain  
 
loaderContext.applicationDomain = ApplicationDomain.currentDomain; 
 
airSWFLoader.contentLoaderInfo.addEventListener(Event.INIT, onInit); 
airSWFLoader.load(new URLRequest("http://airdownload.adobe.com/air/browserapi/air.swf"),  
                    loaderContext); 
 
function onInit(e:Event):void  
{ 
    airSWF = e.target.content; 
}

Depois que o arquivo air.swf for carregado (quando o objeto contentLoaderInfo do objeto Loader despachar o evento init), você poderá chamar qualquer uma das APIs do air.swf. Essas APIs são descritas nestas seções:

Nota: O arquivo badge.swf, fornecido com o SDK do AIR, carrega automaticamente o arquivo air.swf. Consulte Usando o arquivo badge.swf para instalar um aplicativo do AIR. As instruções desta seção se aplicam à criação do seu próprio arquivo do SWF que carrega o arquivo air.swf.

Verificar se o tempo de execução está instalado

Um arquivo SWF pode verificar se o tempo de execução está instalado chamando o método getStatus() no arquivo air.swf carregado de http://airdownload.adobe.com/air/browserapi/air.swf. Para obter detalhes, consulte Carregar o arquivo air.swf.

Depois que o arquivo air.swf for carregado, o arquivo SWF poderá chamar o método getStatus() do arquivo air.swf como a seguir:

var status:String = airSWF.getStatus();

O método getStatus() retorna um dos seguintes valores de seqüências de caracteres, com base no status do tempo de execução no computador:

Valor de string

Descrição

"available"

O tempo de execução pode ser instalado nesse computador, mas não está instalado no momento.

"unavailable"

O tempo de execução não pode ser instalado neste computador.

"installed"

O tempo de execução está instalado nesse computador.

O método getStatus() lança um erro se a versão necessária do Flash Player (versão 9 atualização 3 ou posterior no Windows e Mac OS ou versão 10 no Linux) não estiver instalada no navegador.

Verificar por uma página da Web se um aplicativo do AIR está instalado

Um arquivo SWF pode verificar se um aplicativo do AIR (com uma ID de aplicativo e uma ID de editor correspondentes) está instalado chamando o método getApplicationVersion() no arquivo air.swf carregado de http://airdownload.adobe.com/air/browserapi/air.swf. Para obter detalhes, consulte Carregar o arquivo air.swf.

Depois que o arquivo air.swf for carregado, o arquivo SWF poderá chamar o método getApplicationVersion() do arquivo air.swf como a seguir:

var appID:String = "com.example.air.myTestApplication"; 
var pubID:String = "02D88EEED35F84C264A183921344EEA353A629FD.1"; 
airSWF.getApplicationVersion(appID, pubID, versionDetectCallback); 
 
function versionDetectCallback(version:String):void 
{ 
    if (version == null) 
    { 
        trace("Not installed."); 
        // Take appropriate actions. For instance, present the user with 
        // an option to install the application. 
    } 
    else 
    { 
        trace("Version", version, "installed."); 
        // Take appropriate actions. For instance, enable the 
        // user interface to launch the application. 
    } 
}

O método getApplicationVersion() possui os seguintes parâmetros:

Parâmetros

Descrição

appID

A ID desse aplicativo. Para obter detalhes, consulte Definição de identidade do aplicativo.

pubID

A ID do editor do aplicativo. Para obter detalhes, consulte Sobre identificadores do editor do AIR.

retorno de chamada

Uma função de retorno de chamada para servir como a função do manipulador. O método getApplicationVersion() opera de modo assíncrono e ao detectar essa versão instalada (ou a falta de uma versão instalada), esse método de retorno de chamada é invocado. A definição do método de retorno de chamada deve incluir um parâmetro, uma seqüência de caracteres, definida para a seqüência de caracteres da versão do aplicativo instalado. Se o aplicativo não for instalado, um valor de nulo será transmitido à função, como ilustrado no exemplo de código anterior.

O método getApplicationVersion() lança um erro se a versão necessária do Flash Player (versão 9 atualização 3 ou posterior no Windows e Mac OS ou versão 10 no Linux) não estiver instalada no navegador.

Instalação de um aplicativo do AIR do navegador

Um arquivo SWF pode instalar um aplicativo do AIR chamando o método installApplication() no arquivo air.swf carregado de http://airdownload.adobe.com/air/browserapi/air.swf. Para obter detalhes, consulte Carregar o arquivo air.swf.

Depois que o arquivo air.swf for carregado, o arquivo SWF poderá chamar o método installApplication() do arquivo air.swf como no código a seguir:

var url:String = "http://www.example.com/myApplication.air"; 
var runtimeVersion:String = "1.0"; 
var arguments:Array = ["launchFromBrowser"]; // Optional 
airSWF.installApplication(url, runtimeVersion, arguments); 

O método installApplication() instala o aplicativo especificado na máquina do usuário. Esse método possui os seguintes parâmetros:

Parâmetro

Descrição

url

Uma seqüência de caracteres que define a URL do arquivo do AIR a instalar. Você deve usar um caminho de URL absoluta, e não relativa.

runtimeVersion

Uma seqüência de caracteres que indica a versão do tempo de execução (como "1.0") exigida pelo aplicativo a ser instalado.

arguments

Uma matriz de argumentos a serem transmitidos ao aplicativo se ele for iniciado na instalação. Somente caracteres alfanuméricos são reconhecidos nos argumentos. Se for necessário passar outros valores, considere o uso de um esquema de codificação.

O aplicativo é iniciado na instalação se o elemento allowBrowserInvocation é definido como true no arquivo do descritor do aplicativo. (Para obter mais informações sobre o arquivo do descritor do aplicativo, consulte Configuração de propriedades do aplicativo do AIR.) Se o aplicativo for iniciado como resultado de uma instalação direta do navegador (com o usuário optando por iniciar na instalação), o objeto NativeApplication do aplicativo despacha um objeto BrowserInvokeEvent apenas se argumentos tiverem sido transmitidos. Para obter detalhes, consulte Inicialização de um aplicativo do AIR instalado do navegador.

O método installApplication() pode operar apenas quando chamado no manipulador de eventos para um evento do usuário, como um clique do mouse.

O método installApplication() lança um erro se a versão necessária do Flash Player (versão 9 atualização 3 ou posterior no Windows e Mac OS ou versão 10 no Linux) não estiver instalada no navegador.

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

Você também pode chamar o método getApplicationVersion() do arquivo air.swf para verificar se um aplicativo já está instalado. Você pode chamar esse método antes que o processo de instalação do aplicativo seja iniciado ou após a instalação ser iniciada. Para obter detalhes, consulte Verificar por uma página da Web se um aplicativo do AIR está instalado. Depois que o aplicativo estiver em execução, ele pode se comunicar com o conteúdo do SWF no navegador usando a classe LocalConnection. Para obter detalhes, consulte Comunicação entre aplicativos.

Inicialização de um aplicativo do AIR instalado do navegador

Para usar o recurso de invocação do navegador (permitindo que ele seja iniciado do navegador), o arquivo do descritor do aplicativo de destino deve incluir a seguinte configuração:

<allowBrowserInvocation>true</allowBrowserInvocation>

Para obter mais informações sobre o arquivo do descritor do aplicativo, consulte Configuração de propriedades do aplicativo do AIR.

Um arquivo SWF no navegador pode iniciar um aplicativo do AIR chamando o método launchApplication() no arquivo air.swf carregado de http://airdownload.adobe.com/air/browserapi/air.swf. Para obter detalhes, consulte Carregar o arquivo air.swf.

Depois que o arquivo air.swf for carregado, o arquivo SWF poderá chamar o método launchApplication() do arquivo air.swf como no código a seguir:

var appID:String = "com.example.air.myTestApplication"; 
var pubID:String = "02D88EEED35F84C264A183921344EEA353A629FD.1"; 
var arguments:Array = ["launchFromBrowser"]; // Optional 
airSWF.launchApplication(appID, pubID, arguments);

O método launchApplication() é definido no nível superior do arquivo air.swf (carregado no domínio do aplicativo do arquivo SWF da interface do usuário). Chamar esse método faz com que o AIR inicie o aplicativo especificado (se ele for instalado e a invocação do navegador for permitida, pela configuração allowBrowserInvocation no arquivo do descritor do aplicativo). O método tem os seguintes parâmetros:

Parâmetro

Descrição

appID

A ID do aplicativo a ser iniciado. Para obter detalhes, consulte Definição de identidade do aplicativo.

pubID

A ID do editor do aplicativo a ser iniciado. Para obter detalhes, consulte Sobre identificadores do editor do AIR.

arguments

Uma matriz de argumentos para transmitir ao aplicativo. O objeto NativeApplication do aplicativo despacha um evento BrowserInvokeEvent que possui uma propriedade de argumentos definida para essa matriz. Somente caracteres alfanuméricos são reconhecidos nos argumentos. Se for necessário passar outros valores, considere o uso de um esquema de codificação.

O método launchApplication() pode operar apenas quando chamado no manipulador de eventos para um evento do usuário, como um clique do mouse.

O método launchApplication() lança um erro se a versão necessária do Flash Player (versão 9 atualização 3 ou posterior no Windows e Mac OS ou versão 10 no Linux) não estiver instalada no navegador.

Se o elemento allowBrowserInvocation for definido como false no arquivo do descritor do aplicativo, chamar o método launchApplication() não terá efeito.

Antes de apresentar a interface do usuário para iniciar o aplicativo, você pode desejar chamar o método getApplicationVersion() no arquivo air.swf. Para obter detalhes, consulte Verificar por uma página da Web se um aplicativo do AIR está instalado.

Quando o aplicativo é invocado pelo recurso de invocação do navegador, o objeto NativeApplication do aplicativo despacha um objeto BrowserInvokeEvent. Para obter detalhes, consulte Invocação do navegador.

Se você usa o recurso de invocação do navegador, certifique-se de considerar implicações de segurança, descritas em Invocação do navegador.

Depois que o aplicativo estiver em execução, ele pode se comunicar com o conteúdo do SWF no navegador usando a classe LocalConnection. Para obter detalhes, consulte Comunicação entre aplicativos.