Como utilizar extensões nativas para Adobe AIR

As extensões nativas para Adobe AIR fornecem APIs do ActionScript que permitem o acesso à funcionalidade específica do dispositivo programada em código nativo. Os desenvolvedores de extensões nativas trabalham com os fabricantes de dispositivos e às vezes são desenvolvedores terceirizados.

Caso você esteja desenvolvendo uma extensão nativa, consulte Developing Native Extensions for Adobe AIR.

Uma extensão nativa é uma combinação de:

  • Classes ActionScript.

  • Código nativo.

No entanto, como um desenvolvedor de aplicativos do AIR que usa uma extensão nativa, você trabalha somente com classes ActionScript.

As extensões nativas são úteis nas seguintes situações:

  • A implementação do código nativo fornece o acesso aos recursos específicos da plataforma. Esses recursos específicos da plataforma não estão disponíveis nas classes ActionScript embutidas, e não é possível os implementar nas classes ActionScript específicas do aplicativo. A implementação do código nativo pode fornecer essa funcionalidade porque tem acesso ao hardware e ao software específicos do dispositivo.

  • Uma implementação do código nativo às vezes pode ser mais rápida do que uma implementação que utilize somente o ActionScript.

  • A implementação do código nativo pode fornecer ao ActionScript o acesso ao código nativo legado.

Alguns exemplos de extensões nativas estão no Centro do Desenvolvedor da Adobe. Por exemplo, uma extensão nativa fornece aos aplicativos AIR o acesso ao recurso de vibração do Android. Consulte Native extensions for Adobe AIR.

Arquivos de Extensão Nativa do AIR (ANE)

Os desenvolvedores de extensões nativas fazem a compactação de uma extensão nativa para um arquivo ANE. Um arquivo ANE é um arquivo de arquivo morto que contém as bibliotecas e recursos necessários para a extensão nativa.

Observe que, em alguns dispositivos, o arquivo ANE contém a biblioteca do código nativo que a extensão nativa utiliza. Mas para outros dispositivos a biblioteca do código nativo é instalada no dispositivo. Em alguns casos, a extensão nativa não tem nenhum código nativo para um dispositivo em particular; ele é implementado somente com o ActionScript.

Como um desenvolvedor de aplicativos do AIR, você utiliza o arquivo ANE da seguinte maneira:

  • Inclua o arquivo ANE no caminho da biblioteca do aplicativo da mesma maneira que você incluiu um arquivo SWC no caminho da biblioteca. Esse procedimento permite que o aplicativo busque referências das extensões das classes ActionScript.

    Nota: Ao compilar seu aplicativo certifique-se de usar um vínculo dinâmico para o ANE. Se você usa o Flash Builder, especifique Externo no painel Propriedades do caminho no ActionScript Builder. Caso use a linha de comando, especifique -external-library-path.
  • Empacote o arquivo ANE com o aplicativo do AIR.

Extensões nativas em contraste com a classe ActionScript NativeProcess

O ActionScript 3.0 fornece uma classe NativeProcess. Essa classe permite que o aplicativo do AIR execute processos nativos no sistema operacional host. Essa capacidade é similar a extensões nativas, que fornecem acesso a recursos e bibliotecas específicas de plataforma. Ao decidir utilizar a classe NativeProcess em vez de utilizar uma extensão nativa, considere o seguinte:

  • Somente o perfil extendedDesktop do AIR suporta a classe NativeProcess. Portanto, para aplicativos com os perfis mobileDevice e extendedMobileDevice do AIR, as extensões nativas são a única escolha.

  • Os desenvolvedores de extensões nativas geralmente fornecem implementações nativas para várias plataformas, mas a API do ActionScript que eles fornecem são geralmente as mesmas plataformas cruzadas. Ao usar a classe NativeProcess, o código do ActionScript para iniciar o processo nativo pode variar entre as diferentes plataformas.

  • A classe NativeProcess inicia um processo separado, enquanto que a extensão nativa é executada no mesmo processo do aplicativo do AIR. Portanto, se você está preocupado com o bloqueio de códigos, o uso da classe NativeProcess é mais seguro. No entanto, o processo separado significa que provavelmente você tem uma manipulação de comunicação de interprocessos para implementar.

Extensões nativas em contraste com as bibliotecas da classe ActionScript (arquivos SWC)

Um arquivo SWC file é uma biblioteca da classe ActionScript em um formato de arquivo morto. O arquivo SWC contém um arquivo SWF e outros arquivos de recurso. O arquivo SWC é uma maneira conveniente de compartilhar classes ActionScript em vez de compartilhar arquivos ActionScript de recurso e de código individuais.

Um pacote de extensão nativa é um arquivo ANE. Assim como um arquivo SWC, um arquivo ANE também é uma biblioteca da classe ActionScript, que contém um arquivo SWF e outros arquivos de recurso em formato de arquivo morto. No entanto, a diferença mais importante entre um arquivo ANE file e um arquivo SWC é que somente um arquivo ANE pode obter uma biblioteca de código nativa.

Nota: Ao compilar seu aplicativo certifique-se de usar um vínculo dinâmico para o arquivo ANE. Se você usa o Flash Builder, especifique Externo no painel Propriedades do caminho no ActionScript Builder. Caso use a linha de comando, especifique -external-library-path.

Dispositivos suportados

A partir do AIR 3, é possível utilizar extensões nativas em aplicativos para os seguintes dispositivos:

  • Dispositivos do Android, a partir do Android 2.2

  • Dispositivos do iOS, a partir do iOS 4.0

  • Simulador iOS, a partir do AIR 3.3

  • Blackberry PlayBook

  • Dispositivos pessoais do Windows que suportam o AIR 3.0

  • Dispositivos pessoais do Mac OS X que suportam o AIR 3.0

Geralmente, a mesma extensão nativa é direcionada para múltiplas plataformas. O arquivo ANE da extensão contém bibliotecas do ActionScript e nativas para cada plataforma suportada. Geralmente, as bibliotecas do ActionScript possuem as mesmas interfaces públicas para todas as plataformas. As bibliotecas nativas são basicamente diferentes.

Às vezes, uma extensão nativa é compatível com uma plataforma padrão. A implementação da plataforma padrão tem somente o código do ActionScript, mas nenhum código nativo. Se você empacotar um aplicativo para uma plataforma que a extensão não suporte especificamente, o aplicativo utilizará a implementação padrão ao ser executado. Por exemplo, considere uma extensão que fornece um recurso que se aplica somente a dispositivos móveis. A extensão também poderá fornecer uma implementação padrão que um aplicativo de desktop poderá utilizar para simular o recurso.

Perfis de dispositivo suportados

Os seguintes perfis do AIR suportam extensões nativas:

  • extendedDesktop, a partir do AIR 3.0

  • mobileDevice, a partir do AIR 3.0

  • extendedMobileDevice, a partir do AIR 3.0

Lista de tarefas que utilizam uma extensão nativa

Para usar uma extensão nativa no aplicativo, realize as seguintes tarefas:

  1. Indique a extensão no arquivo de indexação do aplicativo.

  2. Inclua o arquivo ANE no caminho da biblioteca do aplicativo.

  3. Empacotar o aplicativo.

Indicação da extensão no arquivo de indexação do aplicativo

Todos os aplicativos do AIR possuem um arquivo de indexação do aplicativo Quando um aplicativo utiliza uma extensão nativa, o arquivo de indexação do aplicativo inclui um elemento <extensions>. Por exemplo:

<extensions> 
    <extensionID>com.example.Extension1</extensionID> 
    <extensionID>com.example.Extension2</extensionID> 
</extensions>

O elemento extensionID tem o mesmo valor que o elemento id no arquivo descritor de extensão. O arquivo descritor da extensão é um arquivo XML chamado extension.xml. Ele é empacotado em um arquivo ANE. É possível utilizar uma ferramenta de extração de arquivo morto para visualizar o arquivo extension.xml.

Inclusão do arquivo ANE no caminho da biblioteca do aplicativo

Para compilar um aplicativo que utilize uma extensão nativa, inclua o arquivo ANE no caminho da biblioteca.

Uso do arquivo ANE com o Flash Builder

Se o aplicativo utilizar uma extensão nativa, inclua o arquivo ANE para a extensão nativa no caminho da biblioteca. Em seguida, você pode usar o Flash Builder para compilar o seu código ActionScript.

Execute as seguintes etapas, que usam o Flash Builder 4.5.1:

  1. Altere a extensão do nome do arquivo ANE de .ane para .swc. Essa etapa é necessária para que o Flash Builder possa localizar o arquivo.

  2. Selecione Projeto > Propriedades no seu projeto do Flash Builder.

  3. Selecione Caminho de Criação do Flex na caixa de diálogo Propriedades.

  4. Na guia Caminho da Biblioteca, selecione Adicionar SWC....

  5. Navegue para o arquivo SWC e selecione Abrir.

  6. Selecione OK na caixa de diálogo Adicionar SWC...

    O arquivo ANE agora aparece na guia Caminho da Biblioteca, na caixa de diálogo Propriedades.

  7. Expanda a entrada do arquivo SWC. Clique duas vezes em Tipo de Link para abrir a caixa de diálogo Opções de Itens de Caminho da Biblioteca.

  8. Na caixa de diálogo Opções do Item do Caminho da Biblioteca, altere o tipo de link para Externo.

Agora você pode compilar o seu aplicativo usando, por exemplo, Projeto > Criar Projeto.

Uso do arquivo ANE com o Flash Professional

Se o aplicativo utilizar uma extensão nativa, inclua o arquivo ANE para a extensão nativa no caminho da biblioteca. Em seguida, você poderá usar o Flash Professional CS5.5 para compilar o seu código ActionScript. Faça o seguinte:

  1. Altere a extensão do nome do arquivo ANE de .ane para .swc. Essa etapa é necessária para que o Flash Professional possa localizar o arquivo.

  2. Selecione Arquivo > Configurações do ActionScript no seu arquivo FLA.

  3. Selecione a guia Caminho da Biblioteca na caixa de diálogo Configurações Avançadas do ActionScript 3.0.

  4. Selecione o botão Procurar arquivo SWC.

  5. Navegue para o arquivo SWC e selecione Abrir.

    O arquivo SWC agora aparece na guia Caminho da Biblioteca na caixa de diálogo Configurações Avançadas do ActionScript 3.0.

  6. Com o arquivo SWC selecionado, selecione o botão Selecionar Opções de Ligação com uma Biblioteca.

  7. Na caixa de diálogo Opções do Item do Caminho da Biblioteca, altere o tipo de link para Externo.

Compactando um aplicativo que utiliza extensões nativas

Use a ADT para empacotar um aplicativo que utilize extensões nativas. Não é possível empacotar o aplicativo usando o Flash Professional CS5.5 ou o Flash Builder 4.5.1.

Detalhes sobre o uso de ADT podem ser encontrados em Ferramenta do Desenvolvedor do AIR (ADT).

Por exemplo, o seguinte comando de ADT cria um arquivo DMG (um arquivo de instalador nativo para o Mac OS X) para um aplicativo que utiliza extensões nativas:

adt -package 
    -storetype pkcs12 
    -keystore myCert.pfx 
    -target native 
    myApp.dmg 
    application.xml 
    index.html resources 
    -extdir extensionsDir
O seguinte comando cria um pacote APK para um dispositivo do Android:
adt -package 
    -target apk 
    -storetype pkcs12 -keystore ../codesign.p12 
    myApp.apk 
    myApp-app.xml 
    myApp.swf icons 
    -extdir extensionsDir

O seguinte comando cria um pacote iOS para um aplicativo iPhone:

adt -package 
    -target ipa-ad-hoc 
    -storetype pkcs12 -keystore ../AppleDistribution.p12 
    -provisioning-profile AppleDistribution.mobileprofile 
    myApp.ipa 
    myApp-app.xml 
    myApp.swf icons Default.png 
    -extdir extensionsDir

Observe o seguinte:

  • Utilize um tipo de pacote de instalador nativo.

  • Especifique o diretório da extensão.

  • Certifique-se de que o arquivo ANE suporte o dispositivo de destino do aplicativo.

Utilize um tipo de pacote de instalador nativo.

O pacote do aplicativo deverá ser um instalador nativo. Não é possível criar um pacote do AIR de plataformas cruzadas (um pacote .air) para um aplicativo que utilize uma extensão nativa, já que as extensões nativas geralmente contêm o código nativo. No entanto, uma extensão nativa geralmente suporta múltiplas plataformas nativas com as mesmas APIs do ActionScript. Nesses casos, é possível utilizar o mesmo arquivo ANE em diferentes pacotes do instalador nativo.

A seguinte tabela resume o valor de uso para a opção -target do comando ADT:

Plataforma de destino do aplicativo

-target

Dispositivos pessoais do Mac OS X ou Windows

-target nativo

-target conjunto

Android

-target apk

ou outros destinos do pacote do Android.

iOS

-target ipa-ad-hoc

ou outros destinos do pacote do iOS

Simulador iOS

-target ipa-test-interpreter-simulator

-target ipa-debug-interpreter-simulator

Especifique o diretório de extensão

Utilize a opção do ADT -extdir para reportar ao ADT o diretório que contém as extensões nativas (arquivos ANE).

Para obter detalhes sobre esta opção, consulte Opções de caminho e arquivo.

Certifique-se de que o arquivo ANE suporte o dispositivo de destino do aplicativo

Ao fornecer um arquivo ANE, o desenvolvedor da extensão nativa informa quais plataformas a extensão suporta. Também é possível usar uma ferramenta de extração de arquivo morto para visualizar os conteúdos do arquivo ANE. Os arquivos extraídos incluem um diretório para cada plataforma suportada.

Saber quais plataformas a extensão suporta é importante ao compactar o aplicativo que utiliza o arquivo ANE. Considere as seguintes regras:

  • Para criar um pacote de aplicativo do Android, o arquivo ANE deverá incluir a plataforma Android-ARM. Alternativamente, o arquivo ANE deverá incluir a plataforma padrão e pelo menos uma outra plataforma.

  • Para criar um pacote de aplicativo do iOS, o arquivo ANE deverá incluir a plataforma iPhone-ARM. Alternativamente, o arquivo ANE deverá incluir a plataforma padrão e pelo menos uma outra plataforma.

  • Para criar um pacote de aplicativo do simulador iOS, o arquivo ANE deverá incluir a plataforma iPhone-x86.

  • Para criar um pacote de aplicativo do Mac OS X, o arquivo ANE deverá incluir a plataforma MacOS-x86 . Alternativamente, o arquivo ANE deverá incluir a plataforma padrão e pelo menos uma outra plataforma.

  • Para criar um pacote de aplicativo do Windows, o arquivo ANE deverá incluir a plataforma Windows-x86. Alternativamente, o arquivo ANE deverá incluir a plataforma padrão e pelo menos uma outra plataforma.