Build Android com Ionic e Capacitor: geração de APK/AAB e assinatura

O que muda em um build Android “de produção”

No Ionic com Capacitor, o app web (HTML/CSS/TypeScript) é empacotado dentro de um projeto Android nativo (Gradle/Android Studio). Para publicar, você precisa: (1) gerar o bundle web otimizado, (2) sincronizar com o projeto Android, (3) configurar identidade visual (ícone/splash), (4) garantir variáveis de ambiente corretas, (5) gerar um artefato de distribuição (APK ou AAB) e (6) assinar o build com uma chave de release.

APK vs AAB (quando usar cada um)

• APK: pacote instalável direto (útil para testes internos, distribuição fora da Play Store, MDM, QA). Normalmente é maior, pois contém recursos para várias arquiteturas/densidades.
• AAB (Android App Bundle): formato recomendado/obrigatório na Play Store para novos apps na maioria dos casos. Você envia o AAB e a Play gera APKs otimizados por dispositivo (split APKs), reduzindo tamanho de download.

Preparar o build de produção

1) Garantir build web otimizado

Antes de abrir o Android Studio, gere o build do app web em modo produção e sincronize com o Android:

# 1) Build web (ajuste conforme seu stack: Angular/React/Vue)
ionic build --prod

# 2) Sincroniza o conteúdo web e plugins com o projeto Android
npx cap sync android

Se você alterou apenas código web, muitas vezes npx cap copy android é suficiente. Se adicionou/removeu plugins nativos, prefira npx cap sync.

2) Configurar ícones e splash

Em projetos Ionic/Capacitor, a forma mais prática é usar o gerador de assets. Garanta que você tenha imagens base (por exemplo, resources/icon.png e resources/splash.png ou conforme sua estrutura) e gere os assets:

# ferramenta comum para gerar ícones/splash
npx @capacitor/assets generate

Depois, sincronize novamente para refletir no Android:

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

npx cap sync android

Valide no Android Studio se os recursos foram atualizados (mipmap/drawable). Em alguns casos, é necessário limpar caches do Gradle/Android Studio para ver mudanças.

3) Variáveis de ambiente (endpoints, chaves e flags)

Para build de produção, o ponto crítico é garantir que o app aponte para os endpoints corretos e que segredos não fiquem expostos no bundle. Boas práticas:

• Endpoints: use uma configuração por ambiente (ex.: API_BASE_URL para dev/staging/prod).
• Flags: habilite/desabilite recursos via flags (ex.: analytics, logs, modo debug).
• Segredos: não coloque chaves sensíveis no código web. Se precisar de chaves públicas (ex.: mapa), trate como “expostas” e restrinja por domínio/assinatura no provedor.

Uma abordagem comum é manter arquivos de ambiente separados e trocar no build. Garanta que o build de produção esteja usando o arquivo/valores corretos antes de gerar o artefato final.

Abrir o projeto no Android Studio

Abra o projeto Android gerado pelo Capacitor:

npx cap open android

Isso abrirá o Android Studio na pasta android/. Aguarde o Gradle sincronizar. Se for a primeira vez, ele pode baixar dependências e pedir atualização de plugins/AGP.

Onde ajustar configurações importantes

• ApplicationId (identificador do app): em geral em android/app/build.gradle (ou build.gradle.kts), dentro de defaultConfig.
• Version Code/Name: também em defaultConfig (ex.: versionCode e versionName).
• Permissões: em android/app/src/main/AndroidManifest.xml.

Atenção: mudar applicationId após publicar cria um “novo app” para a Play Store. Defina isso cedo e evite alterações.

Gerar builds: debug e release

Build debug (para testes rápidos)

O debug é assinado automaticamente com a debug keystore do Android. Você pode gerar via Android Studio ou linha de comando.

No Android Studio:

• Menu Build > Build Bundle(s) / APK(s) > Build APK(s) (geralmente gera debug se a variante estiver em debug).
• Ou selecione a variante em Build Variants (debug) e rode em um dispositivo.

Via Gradle (na pasta android/):

./gradlew assembleDebug

O APK costuma sair em caminho semelhante a android/app/build/outputs/apk/debug/.

Build release (para distribuição)

Release exige assinatura com uma chave de release. Você pode gerar APK release (útil para distribuição direta) ou AAB (para Play Store).

Gerar AAB (recomendado para Play Store):

./gradlew bundleRelease

O arquivo .aab costuma sair em android/app/build/outputs/bundle/release/.

Gerar APK release:

./gradlew assembleRelease

O APK costuma sair em android/app/build/outputs/apk/release/.

Assinatura: como funciona e como configurar

Conceito: por que assinar?

Android exige que apps sejam assinados para garantir integridade e autoria. A assinatura:

• Identifica o autor (chave privada).
• Permite atualizações: a próxima versão precisa ser assinada com a mesma chave.
• Evita adulteração do pacote.

Perder a chave de release normalmente impede atualizar o app publicado (na prática, você teria que publicar outro app com outro applicationId).

Criar uma keystore de release

Você pode criar a keystore com o keytool (vem com o JDK). Exemplo:

keytool -genkeypair -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-key-alias

• Guarde o arquivo .jks em local seguro (backup).
• Guarde senha da keystore e do alias com segurança.
• Não versione a keystore no Git.

Configurar assinatura no Gradle

O padrão é configurar um signingConfig para release e apontar para a keystore. Para evitar expor senhas no repositório, use um arquivo keystore.properties fora do controle de versão.

Exemplo de keystore.properties (coloque em android/keystore.properties e adicione ao .gitignore):

storeFile=/caminho/seguro/my-release-key.jks
storePassword=SENHA_DA_KEYSTORE
keyAlias=my-key-alias
keyPassword=SENHA_DO_ALIAS

Exemplo de configuração em android/app/build.gradle (Groovy):

def keystoreProperties = new Properties()
def keystorePropertiesFile = rootProject.file('keystore.properties')
if (keystorePropertiesFile.exists()) {
  keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
}

android {
  signingConfigs {
    release {
      storeFile file(keystoreProperties['storeFile'])
      storePassword keystoreProperties['storePassword']
      keyAlias keystoreProperties['keyAlias']
      keyPassword keystoreProperties['keyPassword']
    }
  }

  buildTypes {
    release {
      signingConfig signingConfigs.release
      minifyEnabled true
      shrinkResources true
      proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
  }
}

Se seu projeto usa Kotlin DSL (.kts), a sintaxe muda, mas a ideia é a mesma: carregar propriedades e aplicar em signingConfigs.release.

Assinatura na Play Store (Play App Signing)

Ao publicar AAB, é comum habilitar Play App Signing. Nesse modelo, a Play gerencia a chave de assinatura final do app e você usa uma chave de upload para enviar novas versões. Isso reduz risco operacional, mas exige cuidado com a chave de upload (backup e controle de acesso).

Checklist antes do build de release

Configuração e identidade

• applicationId correto e definitivo.
• versionCode incrementado (obrigatório para atualizar na Play).
• versionName coerente (ex.: 1.4.0).
• Ícones e splash atualizados e testados em diferentes densidades.

Permissões e Manifest

• Remover permissões não utilizadas (reduz alertas e rejeições).
• Se usar permissões sensíveis, garantir que o fluxo de consentimento e justificativa esteja claro.
• Validar android:exported em componentes exigidos por versões recentes do Android (principalmente se houver intent-filters).

Endpoints, ambiente e segurança

• Endpoints apontando para produção (API, CDN, auth).
• Chaves expostas revisadas e restritas no provedor (quando aplicável).
• Certificar que http (cleartext) não está habilitado sem necessidade.

Logs, debug e comportamento

• Desativar logs verbosos e flags de debug no build de release.
• Remover telas/rotas internas de teste.
• Validar tratamento de erro sem exibir detalhes sensíveis.

Qualidade e compatibilidade

• Testar em pelo menos 1 dispositivo físico e 1 emulador com versões diferentes do Android.
• Testar fluxos críticos: login, permissões, offline/online, upload/download, navegação principal.
• Verificar tamanho do bundle e tempo de inicialização.

Solução de problemas comuns

1) Alterei o código e não refletiu no app

• Rode ionic build --prod novamente.
• Depois npx cap copy android (ou npx cap sync android se mexeu em plugins).
• No Android Studio: Build > Clean Project e Build > Rebuild Project.

2) Erros de Gradle/AGP ao sincronizar

• Confira a versão do Android Gradle Plugin e do Gradle Wrapper compatíveis.
• Atualize o Android Studio e re-sincronize.
• Se um plugin Capacitor exigir versão mínima, atualize dependências conforme a documentação do plugin.

3) Build release falha por causa de assinatura

• Verifique se o caminho do storeFile está correto e acessível.
• Confirme storePassword, keyAlias e keyPassword.
• Garanta que o arquivo keystore.properties está sendo lido (caminho relativo ao projeto Android).

4) App fecha ao abrir (crash) apenas em release

• Suspeite de minificação/obfuscation (R8/Proguard). Desative temporariamente minifyEnabled para isolar.
• Adicione regras em proguard-rules.pro para bibliotecas que precisam manter classes/reflection.
• Gere logs com adb logcat para identificar a exceção.

5) Problemas de rede em produção (CORS/SSL/cleartext)

• Confirme que a API está em HTTPS e com certificado válido.
• Evite habilitar cleartext traffic; se for inevitável em casos específicos, configure explicitamente e entenda o impacto.
• Valide se o endpoint de produção está acessível no dispositivo (rede corporativa/VPN pode interferir).

6) Ícone/splash não atualiza

• Regere assets (npx @capacitor/assets generate) e rode npx cap sync android.
• Limpe o projeto no Android Studio e reinstale o app no dispositivo (desinstalar antes ajuda a limpar cache de recursos).

Comandos rápidos (resumo operacional)