Build Android

Build e invia le tue app Android al Google Play Store usando l'infrastruttura dedicata di Capgo.

Cosa imparerai

• Imparerai come fare l'upload della tua app tramite Capgo Native Build
• Imparerai come configurare le credenziali per Capgo Native Build

Prerequisiti

• Devi avere un account Google Developer attivo
• Devi avere Android Studio installato
• La tua app deve poter essere compilata correttamente con Android Studio

Nota

Userò la seguente app per il tutorial: https://github.com/Cap-go/capgo-native-build-tutorial-app

Consigliato: onboarding automatizzato

Non devi fare niente di tutto questo a mano. L'onboarding di Capgo crea e configura per te le credenziali di firma Android (keystore + service account di Google Play) — questo è il percorso consigliato:

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

La guida manuale qui sotto è solo per chi preferisce configurare le credenziali da solo o vuole capire esattamente cosa fa Capgo sotto il cofano.

La prima build manuale

Prima di iniziare a pensare di creare la build dell'app con Capgo, dovremmo prima configurarlo e fare una prima build Android a mano. Ci sono alcuni vantaggi nel fare prima una build manuale:

• Preparerai le credenziali per la successiva build con Capgo
• Creerai un record sulla Play Store Console

Creare la build dell'app manualmente con Android Studio

Prima di poter iniziare a compilare l'app con Capgo, è necessario compilarla manualmente con Android Studio.

1. Apri Android Studio

   Esegui bunx cap open android per aprire il progetto di Android Studio.

2. Clicca su Build -> Generate Signed App Bundles / APKs

3. Seleziona Android App Bundle e clicca su Next

Creazione di un keystore

Al momento ti manca il file keystore. Questo file serve a firmare la tua app, così Google sa che l'hai creata tu. Per generarlo, useremo il metodo con interfaccia grafica di Android Studio. C'è anche un modo per farlo da riga di comando, ma non lo tratteremo in questo tutorial.

1. Clicca su Create new

2. Inserisci il percorso del keystore

   Attenzione

   Questo DEVE ESSERE SALVATO - verrà utilizzato in seguito

3. Imposta la password del keystore

   Nota

   Consiglio di usare la stessa password per il keystore e il Key Alias.

   Attenzione

   Questo DEVE ESSERE SALVATO - verrà utilizzato in seguito

4. Compila il resto del modulo

   1. Mantieni l'alias della chiave invariato (key0)
   2. Inserisci i dettagli del certificato. Ho inserito dei dati fittizi, ma dovresti utilizzare i tuoi dati reali.

   

5. Clicca su OK

Completamento del build manuale

1. Verifica che tutti i dettagli del keystore siano stati inseriti correttamente e clicca su Next

2. Seleziona la release build variant e clicca su Create

3. Una volta completata la build, vedrai la seguente schermata

   1. Questo popup indica che la build è andata a buon fine.
   2. Clicca sul locate pulsante: si aprirà il file explorer e dovresti vedere la build lì.

4. Verifica di poter vedere la build nel file explorer

Creazione dell'app sulla Play Store Console

1. Vai su Google Play Console

2. Seleziona l'account sviluppatore corretto

3. Clicca su Create app

4. Scegli il nome dell'app e la lingua

5. Seleziona la categoria dell'app e se è a pagamento o gratuita

6. Accetta i termini e le condizioni

   Attenzione

   Assicurati di leggere i termini e le condizioni prima di accettarli.

7. Clicca su Create

Creazione del gruppo di test interno

Ora che hai creato l'app, puoi creare un gruppo di test interno. Dato che non pubblicherò davvero l'app per tutti su Play Store, dovrò creare un gruppo di test interno.

Nota

Il test interno è ancora il modo più rapido per fare uno smoke test della build distribuita su Play prima del lancio reale.

Se il tuo account sviluppatore è un account personale creato dopo il 13 novembre 2023, il test interno non hai sostituisce il requisito del test chiuso per l'accesso alla produzione. Avrai comunque bisogno di un test chiuso con almeno 12 tester iscritti per 14 giorni consecutivi prima della produzione.

1. Vai su internal testing Clicca su Test and release -> Testing -> Internal testing

   

2. Clicca su Testers

3. Clicca su Create email list

4. Dai un nome all'elenco email

5. Aggiungi gli indirizzi email dei tester

6. Premi Enter e clicca su Save

7. Clicca su Create group

8. Assicurati che il nuovo elenco sia selezionato e clicca su Save

Upload dell'app al gruppo di test interno

Ora che hai creato il gruppo di test interno, puoi caricare l'app nel gruppo di test interno.

1. Vai su Test and release -> Testing -> Internal testing

2. Clicca sul Releases pulsante

3. Clicca su Create new release

4. Clicca su Upload

5. Seleziona il file AAB

   Attenzione

   Assicurati di selezionare il file AAB compilato manualmente con Android Studio. Se questo file non usa lo stesso keystore di quello che userai per la Capgo build, il Capgo Native Build non andrà a buon fine.

6. Attendi il caricamento del file AAB

7. Clicca su Next

8. Risolvi gli errori

   Personalmente, a questo punto vedo questo errore

   

   Il motivo è che non ho ancora verificato il mio numero di telefono. Lo farò e poi continuerò il tutorial.

9. Clicca su Save and publish Questo pubblicherà l'app nel gruppo di test interno.

10. Conferma la pubblicazione

11. Assicurati che l'app sia pubblicata

12. Ottieni il nome temporaneo dell'app

Accetta l'invito al gruppo di test interno

Ora che hai caricato l'app nel gruppo di test interno, puoi accettare l'invito al gruppo di test interno.

1. Vai su Test and release -> Testing -> Internal testing

2. Clicca su Testers

3. Clicca su Copy link

4. Invia il link al tuo telefono, aprilo nel browser e clicca su Accept

5. Conferma che l'invito è stato accettato e clicca su “Scaricala su Play Store”

6. Installa l'app

   1. Se hai già installato l'app prima di usare Android Studio, clicca su uninstall pulsante
   2. Clicca sul install pulsante
   3. Apri l'app e conferma che il download sia andato a buon fine

   Attenzione

   Se non vedi l'app su Play Store, assicurati di aver selezionato l'account corretto.

Configurazione di Capgo Native Build (Android)

Ora sei pronto per iniziare la configurazione di Capgo Native Build. Congratulazioni 🎉!

Requisito	Flag	Descrizione	Obbligatorio
File keystore	--keystore <path>	Percorso del tuo .jks/.keystore file usato per firmare l'APK/AAB.	Sì
Alias della Keystore	--keystore-alias <alias>	Nome dell'alias della chiave nel keystore.	Sì
Password della chiave Keystore	--keystore-key-password <password>	Password della chiave. Se le password della chiave e del keystore coincidono, puoi fornirne solo una.	Leggi la nota qui sotto
Password del keystore	--keystore-store-password <password>	Password del keystore. Se le password della chiave e del keystore coincidono, puoi fornirne solo una.	Leggi la nota qui sotto
Account di servizio Google Play	--play-config <path>	File JSON dell'account di servizio per gli upload sul Play Store.	Sì

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

Nota

Se le password di key e store sono identiche, fornirne solo una delle --keystore-key-password oppure --keystore-store-password.

Keystore, password keystore, password chiave keystore, alias keystore

Se hai seguito le istruzioni per la build manuale, dovresti già aver generato il keystore. Se non hai seguito le istruzioni, segui le istruzioni per generare il keystore.

Account di servizio Google Play

Generare l'account di servizio di Google Play è un processo manuale e complesso. Tuttavia, è necessario per caricare la tua app su Google Play. Tieni presente quanto segue:

• Tu DEVI essere l'owner del Developer AccountAltrimenti, non potrai configurare il service account.
• Dovrai creare un nuovo progetto Google Cloud (distinto dal tuo account Google Play)

Cominciamo.

1. Vai su Google Cloud Console

2. Clicca sul selettore del progetto

3. Se hai già un progetto, selezionalo. Altrimenti, creane uno nuovo:

   Nota

   Le screenshot qui sono illustrative: usa un nome appropriato per il tuo progetto.

   1. Clicca su New project
   2. Dai un nome al progetto e clicca su Create
   3. Assicurati di essere nel progetto giusto

4. Clicca sulla barra di ricerca e cerca service accounts e clicca su di essa

5. Facciamo clic su Create service account

6. Compila il modulo per l'account di servizio e fai clic su Done

   1. Consiglio di impostare il nome su Capgo Native Build Service Account
   2. Per l'ID dell'account di servizio, consiglio di impostarlo su capgo-native-build-service-acc
   3. Per quanto riguarda la descrizione, non è obbligatorio compilarla, ma ti consiglio di inserirvi Allows Capgo Native Build to build and submit the app to the Play Store

   

7. Fai clic sull'account di servizio appena creato Dovresti ora vedere l'account di servizio appena creato nell'elenco. Fai clic su di esso.

   Nota

   Copia anche questo indirizzo email, ti servirà più avanti.

8. Clicca sul Keys scheda

9. Clicca su Add Key e Create new key

10. Clicca su JSON e Create

    Attenzione

    Cliccando su Create verrà creata una nuova chiave e il file JSON verrà scaricato sul tuo computer.

    Devi salvare il file JSON in un posto sicuro. Ti SERVIRÀ in seguito.

11. Scarica il file JSON Il file JSON dovrebbe essere stato scaricato automaticamente. Puoi cliccare su close per chiudere la finestra.

Concedere al service account l'accesso API al Play Store

Il service account appena creato non ha ancora accesso a API del Play Store. Per concederlo, vai alla Play Store Console.

1. Vai su Google Play Console
2. Seleziona l'account sviluppatore corretto
3. Clicca su Users and permissions
4. Clicca su Invite new users
5. Copia l'indirizzo email dell'account di servizio
6. Vai su Account permissions e concedi i permessi minimi richiesti:
   • In App permissions, concedi l'accesso alla tua app.
   • In Releases, abilita Create, edit, and roll out releases.
   • Se il tuo workflow usa Play App Signing, abilita il relativo permesso di firma.
   • Se non sei sicuro, usa Admin solo durante la configurazione, poi riduci i permessi in seguito.
7. Clicca su Invite user
8. Conferma l'invito
9. Conferma che l'utente è stato invitato

Salvataggio delle credenziali

Ora sei pronto per salvare le credenziali ed eseguire la tua prima build. Puoi salvare le credenziali usando il seguente comando:

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

Configurazione CI/CD (GitHub Actions)

Se hai già completato Keystore, password keystore, password chiave keystore, alias keystore e Account di servizio Google Play, hai già tutto il necessario per la CI/CD. Questa sezione spiega solo come passare quei valori come secret delle GitHub Actions e variabili d'ambiente.

1) Converti i file delle credenziali in base64 su una riga

# 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

Tip

I segreti GitHub devono essere su una singola riga. tr -d '\n' rimuove le interruzioni di riga dall'output base64.

2) Crea i secret del repository

In GitHub > Repository > Settings > Secrets and variables > Actions, aggiungi:

Nome del secret	Valore
CAPGO_TOKEN	Il tuo token Capgo API
APP_ID	Il tuo ID app Capgo (esempio: com.example.app)
ANDROID_KEYSTORE_FILE	Contenuto di keystore_base64.txt
KEYSTORE_KEY_ALIAS	Alias keystore da Keystore, password keystore, password chiave keystore, alias keystore
KEYSTORE_KEY_PASSWORD	Password della chiave Keystore
KEYSTORE_STORE_PASSWORD	Password del keystore
PLAY_CONFIG_JSON	Contenuto di play_config_base64.txt

Nota

Se le password di key e store sono le stesse, puoi fornire solo una delle due KEYSTORE_KEY_PASSWORD oppure KEYSTORE_STORE_PASSWORD.

3) Usa le variabili d'ambiente nel tuo 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 }}

Tip

Con questa configurazione, la CI invia le credenziali solo tramite variabili d'ambiente. Non è necessario committare i file di firma o caricarli come artifact del workflow.

Esecuzione della build

Congratulazioni 🎉! Ora sei pronto per avviare la tua prima build.

Esegui:

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

E questo avvierà il processo di build 🍾🥂

Invia la release Play per la revisione

Di default, le build di rilascio Android vengono caricate su Google Play e possono rimanere inattive finché non completi la release in Play Console. Se la tua release CI deve inviare automaticamente la release Play, passa --submit-to-store-review con un build di 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"

Attenzione

Su Android, --submit-to-store-review predefinito a produzione traccia con release_status: completed quando non imposti una track. Questo può andare live al 100% degli utenti. Passa --android-track internal (o alpha / beta) — oppure imposta PLAY_STORE_TRACK in CI — per mantenere la release completata su una track non di produzione. Usa --android-release-status / PLAY_STORE_RELEASE_STATUS quando hai bisogno di uno status diverso da completed.

Questo richiede la stessa configurazione dell'account di servizio Google Play del percorso di upload normale (PLAY_CONFIG_JSON in CI o credenziali Android salvate localmente). --store-release-name viene utilizzato come Google Play version_name. --store-release-notes è il changelog di fallback di Play, e ogni --store-release-notes-locale "locale=notes" voce scrive un changelog localizzato di Play per quella lingua. Capgo invia il rilascio di Play come completed a meno che non si sovrascriva --android-release-status; se la pubblicazione gestita è abilitata in Play Console, Google può comunque attendere la tua pubblicazione manuale dopo l'approvazione.

Continua da Android Builds

Se stai usando Build Android per pianificare l'automazione CI/CD e connetterla a CI/CD con Capgo per il workflow del prodotto in Capgo CI/CD, Capgo Native Build per il workflow di prodotto in Capgo Native Builds, Integrazioni Capgo per il workflow di prodotto in Integrazioni Capgo, Integrazione CI/CD per i dettagli implementativi in CI/CD Integration, e Integrazione GitHub Actions per i dettagli implementativi in GitHub Actions Integration.