Builds Android

Compilez et soumettez des applications Android au Google Play Store en utilisant l’infrastructure cloud sécurisée de Capgo.

Avant de compiler

⚠️ Configurez d'abord les identifiants Android

Requis : Vous devez enregistrer vos identifiants Android avant de compiler des applications de production.

Configurer les identifiants Android →

Comment fonctionnent les builds Android

Les builds Android s’exécutent dans des bacs à sable Cloudflare sécurisés :

Infrastructure : Cloudflare Workers avec Android SDK conteneurisé
Outil de build : Gradle avec les outils de build Android
Exécution : Environnement de bac à sable isolé par build
Nettoyage : Suppression instantanée après la fin du build
Sécurité : Pas de stockage persistant, isolation complète entre les builds

Prérequis

Avant de compiler pour Android, vous avez besoin de :

1. Environnement de développement (tests locaux)

Android Studio installé localement (pour la configuration initiale du keystore)
Votre application se compile avec succès avec npx cap open android
Java JDK 17 ou supérieur

2. Keystore de signature

Pour les builds de production, vous avez besoin d’un keystore de signature :

Type de build	Keystore requis	Objectif
Debug	Non	Tests uniquement, généré automatiquement
Release	Oui	Soumission au Play Store

Créer un keystore

Si vous n’avez pas encore de keystore, créez-en un :

keytool -genkey -v \
  -keystore my-release-key.keystore \
  -alias my-key-alias \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000

Répondez aux questions :

Mot de passe : Choisissez un mot de passe fort (sauvegardez-le en sécurité !)
Nom : Votre nom ou nom d’entreprise
Organisation : Votre nom d’entreprise
Localisation : Votre ville, état, pays

Comprendre les composants du keystore

Lors de la création d’un keystore, vous devrez vous souvenir de :

Mot de passe du keystore (KEYSTORE_STORE_PASSWORD) : Le mot de passe du fichier keystore lui-même
Alias de la clé (KEYSTORE_KEY_ALIAS) : Le nom/identifiant de votre clé de signature dans le keystore
Mot de passe de la clé (KEYSTORE_KEY_PASSWORD) : Le mot de passe de la clé spécifique (peut être le même que le mot de passe du magasin)

Exemple de flux de travail :

# Lister les alias dans votre keystore pour vérifier
keytool -list -keystore my-release-key.keystore

# Afficher des informations détaillées sur votre clé
keytool -list -v -keystore my-release-key.keystore -alias my-key-alias

Configuration du build

Variables d’environnement requises

Pour les builds de production, définissez ces identifiants :

# Signature Android (requis pour la production)
ANDROID_KEYSTORE_FILE="<keystore-encodé-en-base64>"
KEYSTORE_KEY_ALIAS="my-key-alias"
KEYSTORE_KEY_PASSWORD="<mot-de-passe-de-la-clé>"
KEYSTORE_STORE_PASSWORD="<mot-de-passe-du-magasin>"

# Publication sur le Play Store (optionnel, pour la soumission automatique)
PLAY_CONFIG_JSON="<json-du-compte-de-service-encodé-en-base64>"

Générer les identifiants en Base64

Fichier keystore :

base64 -i my-release-key.keystore | pbcopy

JSON du compte de service Play Store :

base64 -i play-store-service-account.json | pbcopy

La chaîne base64 est maintenant dans votre presse-papiers.

Configuration du compte de service Play Store

Pour activer les téléversements automatiques vers le Play Store, vous devez créer un compte de service Google Cloud avec les permissions appropriées.

Créer un compte de service dans Google Cloud
- Allez sur Google Play Console → Configuration → Accès API
- Cliquez sur “Créer un nouveau compte de service”
- Suivez le lien vers la Google Cloud Console
- Cliquez sur “Créer un compte de service”
- Entrez un nom (par ex., “Capgo CI/CD”)
- Accordez le rôle “Utilisateur de compte de service”
- Cliquez sur “Terminé”
Créer une clé JSON
- Dans la Google Cloud Console, trouvez votre compte de service
- Cliquez sur l’email du compte de service
- Allez dans l’onglet “Clés”
- Cliquez sur “Ajouter une clé” → “Créer une nouvelle clé”
- Choisissez le format “JSON”
- Téléchargez le fichier JSON (gardez-le en sécurité !)
Accorder les permissions dans la Play Console
- Retournez sur Google Play Console → Configuration → Accès API
- Trouvez votre compte de service dans la liste
- Cliquez sur “Accorder l’accès”
- Sous “Permissions de l’application”, sélectionnez votre application
- Sous “Permissions du compte”, accordez :
  - Versions : “Afficher les informations de l’application et télécharger les rapports en masse (lecture seule)”
  - Versions : “Créer, modifier et supprimer les versions provisoires”
  - Versions : “Publier en production, exclure des appareils et utiliser la signature d’application Play”
- Cliquez sur “Inviter l’utilisateur”
Accepter l’invitation
- Le compte de service recevra un email d’invitation
- Acceptez l’invitation pour activer les permissions

Compiler pour Android

Build de débogage

Parfait pour les tests sans signature :

npx @capgo/cli@latest build com.example.app \
  --platform android \
  --build-mode debug

Cela crée un APK de débogage qui peut être installé sur n’importe quel appareil pour les tests.

Build de production

Pour la soumission au Play Store :

npx @capgo/cli@latest build com.example.app \
  --platform android \
  --build-mode release

Nécessite que les identifiants de signature soient configurés comme variables d’environnement.

Intégration CI/CD

Exemple GitHub Actions

name: Build Android App

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '24'

      - name: Install dependencies
        run: npm ci

      - name: Build web assets
        run: npm run build

      - name: Sync Capacitor
        run: npx cap sync android

      - name: Build Android app
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_STORE_CONFIG }}
        run: |
          npx @capgo/cli@latest build ${{ secrets.APP_ID }} \
            --platform android \
            --build-mode release

Détails du processus de build

Ce qui se passe pendant un build Android

Initialisation du bac à sable (~5 secondes)
- Conteneur sécurisé créé
- Android SDK et Gradle chargés
- Système de fichiers isolé créé
Configuration du projet (~20 secondes)
- Zip du projet téléchargé depuis R2
- Extrait dans le répertoire de build
- Identifiants de signature injectés
Build Gradle (2-4 minutes)
- Dépendances téléchargées
- Compilation APK/AAB
- Optimisation ProGuard/R8 (mode release)
- Signature du code appliquée
Téléversement sur le Play Store (30 secondes, si configuré)
- AAB téléversé sur la Play Console
- Track de version configuré
- Soumission initiée
Nettoyage (immédiat)
- Tous les fichiers supprimés
- Conteneur détruit
- Aucun artefact conservé

Stack de build

Notre environnement de build Android inclut :

Java : OpenJDK 17
Android SDK : Dernière version stable
Gradle : 8.x
Build Tools : 34.x
Node.js : 18.x (LTS)
NPM : Dernière version stable

Sortie du build

APK vs AAB

APK (Android Package) : Fichier installable pour installation directe
AAB (Android App Bundle) : Format recommandé par Google Play (téléchargements plus petits pour les utilisateurs)

Par défaut, les builds Capgo créent :

Mode debug : APK
Mode release : AAB (optimisé pour le Play Store)

Temps de build

Temps de build Android typiques :

Type de build	Temps moyen
Debug	2-3 minutes
Release (sans ProGuard)	3-4 minutes
Release (avec ProGuard)	4-6 minutes

Variantes de build

Variantes de build personnalisées

Si votre application a des variantes de build personnalisées (par ex., staging, production), utilisez build-config :

npx @capgo/cli@latest build com.example.app \
  --platform android \
  --build-mode release \
  --build-config '{"variant":"staging"}'

Cela compilera la variante stagingRelease.

Dimensions de saveur

Pour les applications avec des dimensions de saveur :

--build-config '{"flavor":"premium","variant":"production"}'

Cela compile la variante premiumProductionRelease.

Dépannage

Problèmes courants

“Mot de passe du keystore incorrect”

Vérifiez que KEYSTORE_STORE_PASSWORD correspond à votre keystore
Assurez-vous que KEYSTORE_KEY_PASSWORD correspond au mot de passe de votre alias de clé
Vérifiez les espaces supplémentaires ou caractères spéciaux

“Alias de clé introuvable”

Vérifiez que KEYSTORE_KEY_ALIAS correspond exactement (sensible à la casse)
Listez les alias : keytool -list -keystore my-release-key.keystore

“Échec du build Gradle”

Vérifiez les logs de build pour l’erreur spécifique
Assurez-vous que votre application compile localement avec ./gradlew assembleRelease
Vérifiez que toutes les dépendances natives sont dans build.gradle

“Échec du téléversement sur le Play Store”

Vérifiez que le JSON du compte de service est valide
Assurez-vous que le compte de service a les permissions correctes dans la Play Console
Vérifiez que l’application est correctement configurée dans la Play Console

“Timeout du build”

Les applications volumineuses peuvent nécessiter une optimisation
Vérifiez si des dépendances inutiles peuvent être supprimées
Contactez le support si les builds expirent systématiquement

Logs de débogage

Surveillez ces phases clés dans les logs de build :

→ Téléchargement des dépendances...
→ Exécution de Gradle assembleRelease...
→ Signature APK/AAB...
→ Téléversement sur le Play Store...
✔ Build réussi

Si un build échoue, l’erreur Gradle spécifique sera affichée dans les logs.

Bonnes pratiques

1. Testez d’abord localement

Assurez-vous toujours que votre build Android fonctionne localement :

cd android
./gradlew assembleRelease
# ou
./gradlew bundleRelease

2. Sécurisez votre keystore

Ne committez jamais les keystores dans le contrôle de version
Stockez-les dans une gestion de secrets sécurisée (1Password, AWS Secrets Manager, etc.)
Gardez des copies de sauvegarde dans plusieurs emplacements sécurisés
Documentez les mots de passe dans un gestionnaire de mots de passe sécurisé

3. Gestion des versions

Capgo lit la version depuis votre capacitor.config.json :

{
  "appId": "com.example.app",
  "appName": "My App",
  "version": "1.0.0",
  "build": "1"
}

Incrémentez le numéro build pour chaque version.

4. Configuration ProGuard

Pour les builds de production, assurez-vous que les règles ProGuard sont correctement configurées :

-keep class com.getcapacitor.** { *; }
-keep @com.getcapacitor.annotation.CapacitorPlugin public class * {
  @com.getcapacitor.annotation.PluginMethod public <methods>;
}

5. Surveillez la taille du build

Gardez un œil sur la taille APK/AAB pour vous assurer qu’elle est optimisée :

Le CLI affiche la taille finale :
→ Taille APK : 12.4 MB

Si votre application est volumineuse (>50 MB), considérez :

Activer ProGuard/R8
Utiliser le format AAB (livraison dynamique)
Optimiser les images et assets

Soumission au Play Store

Soumission automatique

Avec PLAY_CONFIG_JSON configuré, les builds sont automatiquement téléversés sur le track de test interne de la Play Console.

Soumission manuelle

Si vous préférez la soumission manuelle :

Exécutez le build sans PLAY_CONFIG_JSON
Téléchargez l’AAB depuis les artefacts de build (si configuré)
Téléversez manuellement sur la Play Console

Prochaines étapes

Builds iOS - Configurer les builds iOS
Dépannage - Problèmes de build courants
Référence CLI - Documentation complète des commandes