Atualizado 9/9/19. Meses atrás escrevi (para minha própria consulta) um tutorial para instalar o Cordova e começar a brincar de desenvolver apps móveis no Windows. De lá pra cá muita coisa mudou ao ponto de o tutorial antigo hoje ser bem obsoleto. As versões mudaram, software compatível agora é deprecado, o novo software é incompatível, etc. Nova instalação, novo tutorial.

Para quem quer um teste mais breve, o PhoneGap está bem mais fácil de instalar e testar, dá uma olhada neste outro tutorial.

Mas voltando à instalação do Cordova, pode parecer bonitinho, mas não é. Trata-se de uma instalação confusa e mal documentada oficialmente que pode levar mais de uma hora e eu estou reescrevendo porque é impossível lembrar todas “novidades” sem escrever. Todas as etapas mudaram e há pelo menos uma etapa completamente nova no processo. Com todos os downloads e o tempo que leva a execução dos programas, minha última instalação levou aproximadamente duas horas.

Lembra que cada etapa depende da anterior pra funcionar corretamente: sem o NodeJS o Cordova não pode ser instalado, sem o Android SDK o Cordova não cria projetos Android, sem o Gradle o Cordova não cria nada que precise de Java, e sem o Java nenhum desses funciona.

Necessário (links para download ao longo do artigo):

  • Java Development Kit 8 e Java RE 8 (runtime environment, ambiente de execução)
  • Android Studio
  • Gradle
  • NodeJS
  • Git

Versão do Windows usada neste tutorial: Windows 10 64-bit (anteriormente testado com Windows 8.1 32 e 64-bit). Cada pacote de software pode ter pré-requisitos diferentes.

Instalação do Java RE e Java Development Kit

Versão do Java usada neste tutorial: AdoptOpenJDK 8

Observação: eu uso o Java AdoptOpenJDK do Ninite.com por praticidade e rapidez, mas caso não funcione (acontece), você pode baixar o Java oficial no site da Oracle. Nota que no momento o Cordova só funciona com Java 8.

  1. (opcional) Desinstala o Java e JDK, se já estiver na máquina.
  2. Faz download do pacote com Java 8 (ambiente de execução) e JDK 8 (kit de desenvolvimento) em Ninite.com ou em Oracle.com (para o download da Oracle é necessário criar uma conta no site, e o pacote do JDK da Oracle inclui tanto kit de desenvolvimento como ambiente de execução).
    • Nota muito importante: no site da Oracle, cuidado para escolher a versão 32-bit ou 64-bit conforme sua máquina.
  3. Instala pacote de instalação, até o final.
  4. Cria a variável de ambiente: JAVA_HOME=pasta do JDK, sempre sem terminar com / ou \ (no meu é C:\Program Files\Java\jdk1.8.0_191).
  5. Adiciona ao PATH: %JAVA_HOME%\bin. E já que está aqui, cheque se no PATH aparece C:\Windows\System32, do contrário adiciona agora.
  6. Reinicia a máquina.

Instalação do Android SDK

(para poder criar projetos Android com ou sem o Cordova)

Versão do Android SDK usada neste tutorial: Android Studio 3.2.1Android Studio

  1. Download do novo Android Studio: developer.android.com/sdk. Clica em “Download Android Studio” e aceita a licença.
  2. Executa o instalador e seja paciente, isso pode levar um bom tempo.
  3. Terminada a instalação, o instalador pode abrir automaticamente o Android Studio (se não, abre manualmente). Eu uso as opções mais padrão. Deixa rodar a primeira vez, fazer download de atualizações e pacotes.
  4. Cria a variável de ambiente: ANDROID_HOME=pasta do SDK, sem aspas e sem terminar com / ou \ (no meu é C:\Users\<usuário>\AppData\Local\Android\sdk).
    • Nota que no lugar de <usuário> vai o nome do usuário correspondente.
  5. Adiciona ao PATH: %ANDROID_HOME%\tools%ANDROID_HOME%\platform_tools.
  6. (opcional) Se você vai assinar seus apps para a Play Store, faz o seguinte: entra em C:\Users\<usuário>\AppData\Local\Android\sdk\build-tools e nota que dentro tem uma pasta com um número de versão (no meu é 29.0.2). Copia o caminho completo para esta pasta (por exemplo C:\Users\RafaelLVX\AppData\Local\Android\sdk\build-tools\29.0.2 ou melhor ainda %ANDROID_HOME%\build-tools\29.0.2 e adiciona esse valor ao PATH.
  7. Quando a instalação de pacotes no SDK Manager estiver completa, fecha o SDK Manager e Android Studio.
  8. (opcional) Cria atalhos para fácil acesso ao Android Studio. No Windows 8.1, abre a lista completa de programas e clica com botão direito em “Android Studio (novo)” seleciona “Fixar na Tela Inicial”, assim o atalho vai aparecer na Tela Inicial imediatamente e pode ser copiado para a área de trabalho ou outros locais.

(opcional) Criação de um AVD

Eu pessoalmente prefiro testar apps no browser ou direto no celular, não no emulador, mas o emulador pode ser útil para testar versões antigas do Android.

Normalmente o Android Studio cria automaticamente um AVD (Android Virtual Device), que serve para testar apps em um emulador na tela do Windows. Se isso não acontecer, ou se quiser criar um novo, faz o seguinte:

  1. Abre o Android Studio. Na janela de boas-vindas, clica em Configure > AVD Manager.
  2. Clica em “Create Virtual Device” e escolhe um aparelho da lista. Eu uso o Nexus 5X.
  3. Na tela seguinte você tem que escolher a versão do Android. Eu gosto de usar a 4.4.4, que não é padrão. Se você estiver em uma máquina com Intel HAXM (a maioria dos processadores Intel mais novos têm isso), é melhor selecionar uma versão x86. Qualquer que seja a sua versão favorita, seleciona e clica em “Download”, aceita todos os termos de licença e Next. Pode demorar um pouco.
  4. Ao final do download, clica Finish, seleciona a versão recém baixada e clica Next.
  5. Na próxima tela é só clicar em Finish e espera a criação do AVD.

Agora se quiser pode abrir o AVD recém criado (pode demorar) ou fechar o AVD Manager e o Android Studio.


Instalação do Gradle

Versão do Gradle usada neste tutorial: 5.6.2

Este é um passo importante e mal documentado pelo pessoal do Cordova. O Gradle é usado para construir o executável (apk) para Android.

  1. Vai em gradle.org/releases e faz o download do Gradle mais recente binary-only.
  2. Descompacta para o local que julgar conveniente (eu uso C:\Gradle).
  3. Adiciona ao PATH a pasta onde estiver o arquivo gradle.bat (no meu caso é C:\Gradle\bin).
  4. Agora convém testar o Gradle, abrindo uma janela de prompt de comando e executando o comando “gradle -v“. Isso deve exibir a versão do Gradle que você baixou, e algumas informações adicionais, entre elas, a localização do Java em sua máquina. Se isso não acontecer, você pode reiniciar e testar o mesmo comando novamente. Se mesmo assim não funcionar, revise os passos de instalação do Java, JDK e do próprio Gradle; sempre pode ser necessário reiniciar após definir as variáveis de ambiente para que elas sejam reconhecidas, pelo menos até o Windows 8.1.

Instalação do Cordova pelo NodeJS

Versão do NodeJS usada neste tutorial: 10.13.0 LTS
Versão do Cordova usada neste tutorial: 4.2.0

  1. Vai em NodeJS.org, faz o download do NodeJS e instala no computador. No instalador, deixa todas as opções habilitadas, inclusive de adicionar o Path. Aqui na última vez que instalei, o NodeJS queria instalar ferramentas adicionais como Python 2, Visual Studio Tools, Boxstarter, Chocolatey (“Tools for Native Modules”)… essa opção eu declinei, por julgar que nada ali serve para o Cordova ou desenvolvimento Android.
  2. (opcional) Cria atalhos para fácil acesso ao NodeJS. No Windows 8.1, abre a lista completa de programas e clica com botão direito em “Node.js command prompt” seleciona “Fixar na Tela Inicial”, assim o atalho vai aparecer na Tela Inicial imediatamente e pode ser copiado para a área de trabalho ou outros locais.
  3. Abre o Node.js command prompt recém instalado e insere o comando (necessário conexão com a internet):
    npm install -g cordova
  4. Espera até terminar de baixar e instalar todos os pacotes.
  5. (opcional) Você pode configurar o Node.js command prompt para sempre abrir na pasta onde você guarda seus projetos do Cordova. Por padrão, ele abre na sua pasta raiz de usuário do Windows. Para escolher outra pasta, usando o Bloco de Notas como Administrador, edite o arquivo C:\Program Files\nodejs\nodevars.bat. Na linha que diz:
    if "%CD%\"=="%~dp0" cd /d "%HOMEDRIVE%%HOMEPATH%"
    …troque a parte que diz “%HOMEDRIVE%%HOMEPATH%” pela pasta que você preferir.

Se os passos 3 e 4 não funcionarem, reinicia o computador e tenta novamente.


(opcional) Instalação do Git

Versão do Git usada neste tutorial: 2.19.1 64-bit

Alguns plugins do Cordova estão hospedados no Github (e não no Apache.org), tornando necessária essa etapa para quem quiser usá-los.

Pra adicionar ironia à perda de tempo, o NodeJS possui um módulo Git, só que ele não serve pra instalação dos plugins. É necessário instalar o Git completo para o Windows.

  1. Download do Git: git-scm.com/download/win.
  2. Executa o instalador.
  3. Nos componentes a serem instalados, eu desmarco “Windows Explorer integration” porque ele é desnecessário para o uso básico do Cordova em linha de comando, mas pode deixar se for usar o Git para outras coisas.
  4. No passo seguinte (Adjusting your PATH environment), seleciona a opção intermediária/recommended, “Use Git from the Windows Command Prompt”.
  5. Nos outros passos da instalação, deixa as opções padrão (várias telas).
  6. Fecha a instalação quando completada.

(mais opcional ainda) Passos adicionais para publicar um projeto Cordova no Github

  1. Abre o Git Bash.
  2. Executa os comandos:
    git config --global  user.email "[email protected]"
    git config --global  user.name "seunome"

    (No meu caso eu usei o nome de usuário e email que eu já tinha cadastrado no Github, mas não sei se isso é obrigatório.)

Criação e execução de um programa Hello World

Abre o Node.js command prompt e digita os seguintes comandos:

cordova create hello com.exemplo.helloworld HelloWorld
Este comando cria um projeto na pasta hello, com identificador em estilo domínio reverso com.exemplo.helloworld, de um aplicativo chamado HelloWorld. A pasta hello não deve existir antes de o comando ser executado, o Cordova vai criar a pasta e adicionar todos os arquivos do projeto. O aplicativo criado faz só o mais básico: testa se o aparelho está pronto para rodar o aplicativo e exibe uma mensagem na tela. Mas ele não vai rodar até que sejam adicionadas as plataformas (abaixo).

cd hello
Entra na pasta hello.

cordova platform add android
Adiciona a plataforma Android a este projeto, ou em outras palavras, instala os arquivos necessários para que o projeto funcione  nativamente no Android. Lembra que tem que estar dentro da pasta raiz do projeto (hello).

Pra ver o programa funcionando, tem duas opções de comandos principais:

  • cordova emulate android
    Roda o programa em uma janela de emulador Android, se houver um AVD criado anteriormente. Lembra que você tem que estar dentro da pasta raiz do projeto (hello). Isso pode levar alguns minutos.

ou

  • cordova run android
    Instala e roda o programa em um dispositivo Android conectado ao computador por USB. Lembre que você tem que estar dentro da pasta raiz do projeto (hello). Para isso funcionar, a depuração USB tem que estar habilitada no aparelho (normalmente em “Opções de desenvolvedor”). Se não funcionar, o Cordova tentará executar o app em um AVD criado anteriormente (no emulador).

    • Quando isso não funciona, normalmente é porque o aparelho não está sendo reconhecido pelo Android Debug Brigde. Executa o comando adb devices. Deve aparecer algo como:
      List of devices attached
      SDFGKSDHGLSJH HTC ONE

      Se não aparece nenhum nome na lista, é porque o aparelho não foi reconhecido. Isso pode acontecer por muitas razões, mas recomendo instalar os drivers USB do aparelho no PC e procurar mais informações sobre “adb devices xxx” no Google, sendo xxx o modelo do seu aparelho. A Intel tem um fix muito bom para o ADB reconhecer teu aparelho aqui (em inglês). Funcionou no meu Xiaomi Mi A2 Lite, a única coisa que posso adicionar é reiniciar o PC e o celular depois do procedimento. Boa sorte.

Adicionando plugins ao programa (e removendo também)

Abre o Node.js command prompt, navega até a pasta do raiz do projeto (ex.: hello). Para adicionar um plugin do Cordova ao programa, o comando é:

cordova plugin add <pacote>

… onde <pacote> é o nome de um pacote de plugin. Os plugins mais básicos estão aqui. Grandes listas de plugins de Cordova/PhoneGap podem ser encontradas aqui e aqui e aqui. Por exemplo, para trabalhar com o sistema de arquivos do aparelho, é necessário instalar o plugin “File”, com o seguinte comando:

cordova plugin add cordova-plugin-file

Pra remover o mesmo plugin, troca “add” por “rm”.

cordova plugin rm cordova-plugin-file

Esse formato de instalação vale para plugins registrados no índice oficial do Cordova, mas há plugins que só podem ser encontrados fora do índice, isto é normal. Por exemplo, um plugin para trabalhar com banco de dados SQLite está no Github, e é por isso que alguns de nós espertamente instalamos o Git. Para adicionar este tipo de plugin funciona da mesma forma, é só saber de onde baixar (letras maiúsculas e minúsculas importam):

cordova plugin add https://github.com/brodysoft/Cordova-SQLitePlugin

Pra remover é um pouco diferente. Não adianta usar o “rm https://github.com…etc”. Tem que chamar o pacote pelo nome certo. Pra saber o nome, executa o comando:

cordova plugin list

Ele vai retornar todos os pacotes instalados. No caso deste pacote que testamos, vai aparecer assim:

cordova-sqlite-storage 2.5.1 "Cordova sqlite storage plugin"

O nome certo do pacote a ser removido é a primeira parte. Agora sim:

cordova plugin rm cordova-sqlite-storage

Enviando seu projeto para o Github…

Esse passo é útil para fechar builds pelo Adobe Phonegap. Eu devo expandir esta área mais tarde, mas todas as instruções estão aqui (em inglês).

…ou, assinando e enviando direto para a Play Store

Se você preferir, não precisa fechar builds pelo Phonegap. Para ir para a lojinha do Google, só precisa preparar a versão final do apk, assinar e fazer o zipalign. É como eu costumo fazer.

Devo expandir esta seção mais tarde, por serem comandos bastante complexos, mas há instruções corretas aqui e aqui (em inglês), incluindo como gerar sua chave de assinatura.

Tendo a chave, o processo da assinatura do app para a Play Store é assim:

  1. Usando o Node.js Command Prompt, vá até a pasta raiz do projeto.
  2. Salve o apk com o comando:
    cordova build --release android
  3. Vá para a pasta do apk:
    cd platforms\android\app\build\outputs\apk\release
  4. Nela você encontrará o apk não assinado, chamado app-release-unsigned.apk.
  5. Usando o Windows Explorer, copie sua chave de assinatura (arquivo .keystore) para a mesma pasta onde está o apk. Tenha cuidado com as cópias deste arquivo. Você precisa de uma cópia dele para atualizar o app na Play Store. Se perdido, você nunca mais poderá enviar atualizações do seu app para a Play Store.
  6. Voltando ao Node.js Command Prompt, hora de assinar o apk. Execute o comando abaixo, mas note que ele termina com três variáveis.
    jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore minhachave.keystore app-release-unsigned.apk RafaelLVX

    • minhachave.keystore: substitua pelo nome do arquivo da chave de assinatura.
    • app-release-unsigned.apk: substitua pelo nome do arquivo apk a ser assinado.
    • RafaelLVX: substitua pelo apelido/alias usado na criação da chave de assinatura.
  7. Digite a senha de sua chave de assinatura.
  8. O passo final é fazer o zipalign do programa. Aqui também há duas variáveis. Execute o comando:
    zipalign -v 4 app-release-unsigned.apk assinado.apk

    • app-release-unsigned.apk: nome do arquivo que você acabou de assinar (ele fica com o mesmo nome de antes da assinatura).
    • assinado.apk: nome de arquivo que você deseja para o apk finalizado.

Agora o apk assinado está pronto para a lojinha do Google.

Para finalizar, lembre-se que este artigo está no ar graças ao patrocinador. Não esqueça de agradecer a ele também!


Written by RafaelLVX

Publicitário portoalegrense, super-herói e, agora, autor de um novo RPG nacional.

23 thoughts on “Passo-a-passo revisado para usar o Apache Cordova com Android SDK no Windows

  1. Prezado Rafael,

    ótimo post. Muito objetivo.

    Gostaria de tirar uma dúvida, se possível, por favor: ao desenvolver uma app com o Cordova, por exemplo, para Android, utilizando recursos de design responsivo, essa app se ajustará automaticamente às várias resoluções dos aparelhos?

    Obrigado.

    Wilson

    1. Oi Wilson

      Para te dizer a verdade não testei muito trabalhar com diferentes resoluções no Cordova, mas pelo que entendo, isso pode funcionar sim, dependendo de como é feito.

      Em design de sites, eu por exemplo gosto de controlar como cada página é exibida em diferentes resoluções a partir de configurações direto no CSS (exemplo: @media screen and (max-width: 480px) {... ... ...}). Na minha experiência, isso funciona bem em sites no navegador do Android, mas em apps do Cordova, cada div vai ter atributos reconhecidos pelo próprio Cordova (por exemplo, div data-role="content") que têm funções particulares do Cordova e podem confundir o CSS.

      A promessa do Cordova é sempre reconhecer html, css e JavaScript bem escrito, mas como sempre, convém testar, testar, testar…

      Se quiser, posta tuas descobertas por aqui.

      Abraço!

  2. Bom, parabéns pelo post! me ajudou bastante com o Cordova aqui.
    há dias procurava um post que pudesse me ajudar ao invés de confundir ainda mais. Está funcionando tudo direitinho aqui.
    Valeu cara!

  3. Boa tarde Rafael
    fiz todo o procedimento detalhe por detalhe mas na hora de instalar o cordova da o seguinte erro
    C:\Windows\system32>npm install -g cordova
    C:\Users\Diego\AppData\Roaming\npm
    `– (empty)

    npm ERR! Windows_NT 10.0.14393
    npm ERR! argv “C:\\Program Files\\nodejs\\node.exe” “C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js” “install” “-g” “cordova”
    npm ERR! node v6.9.1
    npm ERR! npm v3.10.8
    npm ERR! path C:\Users\Diego\AppData\Roaming\npm\node_modules\.staging\abbrev-f63dd7d6
    npm ERR! code ENOENT
    npm ERR! errno -4058
    npm ERR! syscall rename

    npm ERR! enoent ENOENT: no such file or directory, rename ‘C:\Users\Diego\AppData\Roaming\npm\node_modules\.staging\abbrev-f63dd7d6’ -> ‘C:\Users\Diego\AppData\Roaming\npm\node_modules\cordova\node_modules\npm\node_modules\abbrev’
    npm ERR! enoent ENOENT: no such file or directory, rename ‘C:\Users\Diego\AppData\Roaming\npm\node_modules\.staging\abbrev-f63dd7d6’ -> ‘C:\Users\Diego\AppData\Roaming\npm\node_modules\cordova\node_modules\npm\node_modules\abbrev’
    npm ERR! enoent This is most likely not a problem with npm itself
    npm ERR! enoent and is related to npm not being able to find a file.
    npm ERR! enoent

    npm ERR! Please include the following file with any support request:
    npm ERR! C:\Windows\system32\npm-debug.log
    npm ERR! code 1
    será que podes ajudar?

    1. Oi Diego. Infelizmente não tenho como ajudar. Recomendo reler todos os passos com atenção e reiniciar o processo.
      Uma coisa que não aparece no passo-a-passo e fui descobrir depois é que é recomendável instalar as versões 32 e 64 bits do Java no Windows 64 bits (quase todos hoje em dia). Mas não sei se é esse o problema. Uma orientação que já aparece no artigo é a de reiniciar em caso de erro na instalação do Cordova no Node, mas é difícil dizer se isso resolverá seu problema. Recomendável buscar suporte com a comunidade do NodeJS caso nada mais funcione. Boa sorte.

      1. opa. obrigado pela resposta.
        eu achei a solução.

        no meu caso eu estava reinstalando tudo depois de vários erros e tive que limpar as pastas do node que ficam dentro do appData
        e ai funcionou.
        além do mais no windows 10 tem que executar no cmd como administrador para poder instalar tudo

  4. Rafael, eu posso não estar preparado pra isso, mas qual é o Java 8 (ambiente de execução) e JDK 8 (kit de desenvolvimento) ? Se vc colocar um link ( lá é bem confuso para as pessoas com QI abaixo de 100), faria essa gentileza?
    Abraço, e obrigado pela sua possível resposta gentil.
    Sérgio.

    1. Olá Sergio.

      Como diz o artigo, você pode baixar ambos de Ninite.com ou Oracle.com. O Ninite é o mais fácil, só marca Java 8 e JDK 8 e manda baixar e instalar, ele faz tudo sozinho. Boa sorte.

      1. É aplicativo antigo que preciso atualizar na loja da google. Então, suponho que devo atualizar a versão do cordova. Obrigado

      1. Desculpe-me, sou iniciante, consegui instalar o cordova-plugin-build-architecture, mas não consegui implementa-lo no meu projeto.
        Alguma dica?

  5. ola Rafael tudo bem, tenho um app em cordova a tempos, problema que agora tenho que seguimentar ele pra api 31 ou 32 na playstore e estou tendo dificuldade, vc conseguiria fazer um tutorial mostrando as mudandaças necessarias no ambiente de copilação e gerar o apk, desde ja muito grato pela sua atenção.

    1. Oi João. Eu não tenho previsão de quando vou conseguir pesquisar Cordova de novo. Se isso acontecer, publicarei novamente. Eu desconfio que o Cordova esteja ficando meio pra trás nas atualizações, mas pelo que sei, ainda tem muita gente que usa, e ele acaba se adequando aos poucos. Boa sorte.

    2. Oi, João.
      Caso ainda não tenha resolvido o problema e para ajudar outros que possam cair aqui com este problema na Google Play.
      Estava com o mesmo problema seu e consegui resolver seguindo este tutorial, estou usando no momento o Windows 11, fiz toda instalação do zero e deixei o Android Studio fazer todas atualizações, depois precisei fazer outras 3 alterações:

      1 – A versão do Java precisei alterar usando esta: jdk-11.0.18-windows-x64 conforme este outro tutorial: https://www.stechies.com/installing-cordova-android-sdk-windows-7-8-10-develop-mob/
      2 – No Android Studio vc precisa setar o SDK 33 em Tools>>SDK Manager – https://prnt.sc/cf_VkDa2Yzqb
      3 – Inserir no config.xml essas 3 linhas:

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *