Builds Android

Compilez et soumettez vos applications Android au Google Play Store grâce à l’infrastructure dédiée de Capgo.

Ce que vous allez apprendre

• Vous apprendrez à envoyer votre app via Capgo Native Build
• Vous apprendrez à configurer les identifiants pour Capgo Native Build

Prerequisites

• Vous devez disposer d’un compte Google Developer actif
• Vous devez avoir Android Studio installé
• Votre application doit pouvoir être compilée avec succès dans Android Studio

Remarque

Je vais utiliser l’application suivante pour le tutoriel : https://github.com/Cap-go/capgo-native-build-tutorial-app

Recommandé : onboarding automatisé

Vous n’avez pas besoin de faire tout cela manuellement. L’onboarding de Capgo crée et configure vos identifiants de signature Android (keystore + compte de service Google Play) pour vous — c’est le chemin recommandé :

bunx @capgo/cli@latest build init --platform android

Le guide manuel ci-dessous ne s'adresse qu'à ceux qui préfèrent configurer eux-mêmes leurs identifiants ou qui veulent comprendre exactement ce que Capgo fait sous le capot.

Le premier build manuel

Avant de commencer à compiler l'application avec Capgo, nous devons d'abord la configurer et effectuer un premier build Android à la main. Faire un build manuel en premier présente plusieurs avantages :

• Vous préparerez les identifiants pour le build Capgo qui suivra
• Vous créerez une fiche dans la Play Store Console

Compiler l'application manuellement avec Android Studio

Avant de pouvoir compiler l'application avec Capgo, nous devons d'abord la compiler manuellement avec Android Studio.

1. Ouvrir Android Studio

   Exécutez bunx cap open android pour ouvrir le projet Android Studio.

2. Cliquez sur Build -> Generate Signed App Bundles / APKs

3. Sélectionnez Android App Bundle et cliquez sur Next

Créer un keystore

Actuellement, il vous manque le fichier keystore. Ce fichier sert à signer votre application, ce qui permet à Google de vérifier que c’est bien vous qui l’avez créée. Pour le générer, nous utiliserons la méthode graphique fournie par Android Studio. Il existe également une méthode en ligne de commande, mais nous ne l’aborderons pas dans ce tutoriel.

1. Cliquez sur Create new

2. Renseignez le chemin du Key Store

   Attention

   Ceci DOIT ÊTRE SAUVEGARDÉ - il sera utilisé plus tard

3. Définissez le mot de passe du Key Store

   Remarque

   Je recommande d'utiliser le même mot de passe pour le Key Store et le Key Alias.

   Attention

   Ceci DOIT ÊTRE SAUVEGARDÉ - il sera utilisé plus tard

4. Remplissez le reste du formulaire

   1. Gardez l’alias de clé tel quel (key0)
   2. Remplissez les détails du certificat. J’ai utilisé des informations fictives, mais vous devez les remplacer par les vôtres.

   

5. Cliquez sur OK

Fin du build manuel

1. Vérifiez que tous les détails du keystore sont correctement renseignés, puis cliquez sur Next

2. Sélectionnez l’ release variante de build, puis cliquez sur Create

3. Une fois le build réussi, vous devriez voir l’écran suivant

   1. Cette fenêtre indique que le build a réussi.
   2. Cliquez sur locate bouton – cela ouvrira l’explorateur de fichiers et vous devriez y voir le build.

4. Assurez-vous de voir le build dans l’explorateur de fichiers

Création de l'application sur la Play Store Console

1. Accéder à la Google Play Console

2. Sélectionnez le bon compte développeur

3. Cliquez sur Create app

4. Choisissez le nom de l’application et la langue

5. Select the app category and if the app is paid or free

6. Acceptez les conditions générales

   Attention

   Assurez-vous de lire les conditions générales avant de les accepter.

7. Cliquez sur Create

Création du groupe de tests internes

Maintenant que vous avez créé l'application, vous pouvez créer un groupe de tests internes. Comme je ne vais pas vraiment publier l'application pour tout le monde sur le Play Store, je vais devoir créer un groupe de tests internes.

Remarque

Les tests internes restent le moyen le plus rapide de vérifier votre build distribué via le Play Store avant un lancement réel.

Si votre compte développeur est un compte personnel créé après le 13 novembre 2023, les tests internes pas remplacent l'exigence de test fermé pour l'accès à la production. Vous devrez tout de même effectuer un test fermé avec au moins 12 testeurs inscrits pendant 14 jours consécutifs avant la production.

1. Accéder à internal testing Cliquez sur Test and release -> Testing -> Internal testing

   

2. Cliquez sur Testers

3. Cliquez sur Create email list

4. Nommer la liste d’adresses e-mail

5. Ajouter les adresses e-mail des testeurs

6. Appuyez sur Enter et cliquer sur Save

7. Cliquez sur Create group

8. Vérifier que la nouvelle liste est sélectionnée, puis cliquer sur Save

Envoi de l'application au groupe de tests internes

Maintenant que vous avez créé le groupe de test interne, vous pouvez envoyer l’application à ce groupe.

1. Accéder à Test and release -> Testing -> Internal testing

2. Cliquez sur Releases bouton

3. Cliquez sur Create new release

4. Cliquez sur Upload

5. Sélectionner le fichier AAB

   Attention

   Assurez-vous de sélectionner le fichier AAB que vous avez compilé manuellement avec Android Studio. Si ce fichier n'utilise pas le même keystore que celui du build Capgo, le Capgo Native Build échouera.

6. Attendre l'upload du fichier AAB

7. Cliquez sur Next

8. Corriger les erreurs

   Personnellement, à ce stade, je vois cette erreur

   

   C’est parce que je n’ai pas encore vérifié mon numéro de téléphone. Je vais le faire et continuer le tutoriel.

9. Cliquez sur Save and publish Cela publiera l’application dans le groupe de test interne.

10. Confirmer la publication

11. Vérifier que l’application est publiée

12. Obtenir votre nom d’application temporaire

Accepter l'invitation au groupe de tests internes

Maintenant que vous avez envoyé l’application dans le groupe de test interne, vous pouvez accepter l’invitation à ce groupe.

1. Accéder à Test and release -> Testing -> Internal testing

2. Cliquez sur Testers

3. Cliquez sur Copy link

4. Envoyez le lien sur votre téléphone, ouvrez-le dans le navigateur et cliquez sur Accept

5. Confirmez que l’invitation a été acceptée et cliquez sur « Télécharger sur le Play Store »

6. Installer l’application

   1. Si vous aviez installé l’application avant d’utiliser Android Studio, cliquez sur uninstall bouton
   2. Cliquez sur install bouton
   3. Ouvrez l'application et vérifiez qu'elle a bien été téléchargée

   Attention

   Si vous ne voyez pas l'application dans le Play Store, vérifiez que vous avez sélectionné le bon compte dans le Play Store.

Configuration de Capgo Native Build (Android)

Vous êtes maintenant prêt à démarrer la configuration de Capgo Native Build. Félicitations 🎉 !

Exigence	Drapeau	Description	Requis
Fichier keystore	--keystore <path>	Chemin vers votre .jks/.keystore fichier utilisé pour signer l'APK/AAB.	Oui
Alias du keystore	--keystore-alias <alias>	Nom de l'alias de la clé dans le keystore.	Oui
Mot de passe de la clé keystore	--keystore-key-password <password>	Mot de passe de la clé. Si les mots de passe clé/keystore sont identiques, un seul suffit.	Consultez la note ci-dessous
Mot de passe du store Keystore	--keystore-store-password <password>	Mot de passe du keystore. Si les mots de passe clé/keystore sont identiques, un seul suffit.	Consultez la note ci-dessous
Compte de service Google Play	--play-config <path>	Fichier JSON de compte de service pour les uploads sur le Play Store.	Oui

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

Remarque

Si les mots de passe de la clé et du store sont identiques, n'en fournissez qu'un seul : --keystore-key-password ou --keystore-store-password.

Keystore, mot de passe du keystore, mot de passe de la clé du keystore, alias du keystore

Si vous avez suivi les instructions de build manuel, le keystore devrait déjà être généré. Si vous n'avez pas suivi ces instructions, suivez-les pour générer le keystore.

Compte de service Google Play

La création du compte de service Google Play est un processus manuel et complexe. C'est pourtant indispensable pour envoyer votre app sur Google Play. Gardez à l'esprit les points suivants :

• Vous Vous devez être le propriétaire du compte développeur. Sinon, vous ne pourrez pas configurer le compte de service.
• Vous devrez créer un nouveau projet Google Cloud (distinct de votre compte Google Play)

Commençons.

1. Accéder à Console Google Cloud

2. Cliquez sur le sélecteur de projet

3. Si vous avez déjà un projet, sélectionnez-le. Sinon, créez un nouveau projet :

   Remarque

   Les captures d'écran ci-dessous sont illustratives — utilisez un nom adapté à votre projet.

   1. Cliquez sur New project
   2. Nommez votre projet et cliquez sur Create
   3. Assurez-vous d'être sur le bon projet

4. Cliquez sur la barre de recherche et cherchez service accounts et cliquez dessus

5. Cliquez sur Create service account

6. Remplissez le formulaire du compte de service et cliquez sur Done

   1. Je recommande de définir le nom sur Capgo Native Build Service Account
   2. Pour l’ID du compte de service, je recommande de le définir sur capgo-native-build-service-acc
   3. Quant à la description, vous n’êtes pas obligé de la remplir, mais je recommande d’y inscrire Allows Capgo Native Build to build and submit the app to the Play Store

   

7. Cliquez sur le compte de service nouvellement créé Vous devriez maintenant voir le compte de service nouvellement créé dans la liste. Cliquez dessus.

   Remarque

   Copiez également cette adresse e-mail, vous en aurez besoin plus tard.

8. Cliquez sur Keys onglet

9. Cliquez sur Add Key et Create new key

10. Cliquez sur JSON et Create

    Attention

    Cliquer sur Create créera une nouvelle clé et téléchargera le fichier JSON sur votre machine locale.

    Vous devez enregistrer le fichier JSON dans un endroit sûr. Il SERA utilisé plus tard.

11. Télécharger le fichier JSON Le fichier JSON aurait dû être téléchargé automatiquement. Vous pouvez cliquer sur close pour fermer la fenêtre.

Accorder au compte de service l'accès API au Play Store

Le compte de service fraîchement créé n'a pas encore l'accès API au Play Store. Pour l'accorder, rendez-vous sur la Play Store Console.

1. Accéder à la Google Play Console
2. Sélectionnez le bon compte développeur
3. Cliquez sur Users and permissions
4. Cliquez sur Invite new users
5. Copier l’adresse e-mail du compte de service
6. Accéder à Account permissions et accorder les permissions minimales requises :
   • Dans App permissions, accordez l'accès à votre application.
   • Dans Releases, activez Create, edit, and roll out releases.
   • Si votre workflow utilise Play App Signing, activez la permission de signature correspondante.
   • En cas de doute, utilisez Admin uniquement pendant la configuration, puis réduisez les permissions.
7. Cliquez sur Invite user
8. Confirmer l'invitation
9. Confirmer que l'utilisateur a bien été invité

Enregistrement des identifiants

Vous êtes maintenant prêt à enregistrer les identifiants et à lancer votre premier build. Vous pouvez enregistrer les identifiants avec la commande suivante :

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

Configuration CI/CD (GitHub Actions)

Si vous avez déjà terminé Keystore, mot de passe du keystore, mot de passe de la clé du keystore, alias du keystore et Compte de service Google Play, vous avez déjà tout ce qu'il faut pour la CI/CD.\nCette section explique uniquement comment passer ces valeurs en tant que secrets GitHub Actions et variables d'environnement.

1) Convertir les fichiers d'identifiants en base64 sur une seule ligne

# Android keystore (.jks or .keystore)
base64 -i ./path/to/keystore.jks | tr -d '\n' > keystore_base64.txt

# Google Play service account JSON
base64 -i ./play-store-service-account.json | tr -d '\n' > play_config_base64.txt

Astuce

Les secrets GitHub doivent être des valeurs sur une seule ligne. tr -d '\n' supprime les sauts de ligne de la sortie base64.

2) Créer des secrets de dépôt

Dans GitHub > Repository > Settings > Secrets and variables > Actions, ajoutez :

Nom du secret	Valeur
CAPGO_TOKEN	Votre token Capgo API
APP_ID	Votre identifiant d'application Capgo (exemple : com.example.app)
ANDROID_KEYSTORE_FILE	Contenu de keystore_base64.txt
KEYSTORE_KEY_ALIAS	Alias du keystore issu de Keystore, mot de passe du keystore, mot de passe de la clé du keystore, alias du keystore
KEYSTORE_KEY_PASSWORD	Mot de passe de la clé keystore
KEYSTORE_STORE_PASSWORD	Mot de passe du store Keystore
PLAY_CONFIG_JSON	Contenu de play_config_base64.txt

Remarque

Si le mot de passe de la clé et celui du store sont identiques, vous pouvez n’en fournir qu’un KEYSTORE_KEY_PASSWORD ou KEYSTORE_STORE_PASSWORD.

3) Utilisez des variables d'env dans votre workflow GitHub Actions

.github/workflows/android-build.yml

name: Android Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  android-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request Android build with Capgo
        run: bunx @capgo/cli@latest build request ${{ secrets.APP_ID }} --platform android
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

Astuce

Avec cette configuration, la CI envoie les identifiants uniquement via des variables d'environnement. Vous n'avez pas besoin de commiter les fichiers de signature ou de les envoyer comme artefacts de workflow.

Lancement du build

Félicitations 🎉 ! Vous êtes maintenant prêt à lancer votre premier build.

Exécutez :

bunx @capgo/cli@latest build request com.example.app --platform android

Et cela lancera le processus de build 🍾🥂

Soumettre la release Play pour validation

Par défaut, les builds de release Android sont envoyés sur Google Play et peuvent rester inactifs jusqu'à ce que vous terminiez la release dans Play Console. Si votre release CI doit soumettre automatiquement la release Play, passez --submit-to-store-review avec un build de release :

npx @capgo/cli@latest build request com.example.app \
  --platform android \
  --build-mode release \
  --submit-to-store-review \
  --android-track production \
  --store-release-name "1.2.3" \
  --store-release-notes "General improvements" \
  --store-release-notes-locale "en-US=General improvements" \
  --store-release-notes-locale "nl-NL=Algemene verbeteringen" \
  --store-release-notes-locale "fr-FR=Ameliorations generales"

Attention

Sur Android, --submit-to-store-review par défaut sur la Production suivre avec release_status: completed lorsqu’aucun canal n’est défini. Cela peut être déployé à 100 % des utilisateurs. Pass --android-track internal (ou alpha / beta) — ou définissez PLAY_STORE_TRACK en CI — pour garder la release terminée sur une track non de production. Utilisez --android-release-status / PLAY_STORE_RELEASE_STATUS lorsque vous avez besoin d'un statut différent de completed.

Cela nécessite la même configuration du compte de service Google Play que le chemin d'upload normal (PLAY_CONFIG_JSON en CI ou des identifiants Android enregistrés localement). --store-release-name est utilisé comme le Google Play version_name. --store-release-notes est le changelog Play de secours, et chaque --store-release-notes-locale "locale=notes" l'entrée rédige un changelog Play localisé pour cette locale. Capgo envoie la release Play en tant que completed sauf si vous surchargez --android-release-status; si la publication gérée est activée dans la Play Console, Google peut toujours attendre votre publication manuelle après approbation.

Continuer depuis les builds Android

Si vous utilisez Builds Android pour planifier l'automatisation CI/CD, et le connecter avec CI/CD Capgo pour le workflow produit dans le CI/CD de Capgo, Capgo Native Build pour le workflow produit dans les Native Builds de Capgo, Intégrations Capgo pour le workflow produit dans les intégrations de Capgo, Intégration CI/CD pour le détail d'implémentation dans l'intégration CI/CD, et Intégration GitHub Actions pour les détails d'implémentation de l'intégration GitHub Actions.