Costruzioni Android

Costruisci e invia app Android al Google Play Store utilizzando l'infrastruttura dedicata di Capgo.

Cosa imparerai

• Imparerai a caricare il tuo app tramite Capgo Build nativo
• Imparerai a configurare le credenziali per Capgo Build nativo

Requisiti

• Hai bisogno di avere un account Google Developer attivo
• Hai bisogno di avere Android Studio installato
• La tua app deve essere in grado di costruirsi con successo con Android Studio

Nota

Utilizzerò l'app seguente per il tutorial: https://github.com/Cap-go/capgo-tutorial-app-nativo

Consigliato: onboarding automatizzato

Non devi fare nulla di tutto ciò a mano. L'onboarding di Capgo crea e configura i tuoi credenziali di firma Android (keystore + account del servizio Google Play) per te — questo è il percorso consigliato:

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

La guida passo-passo manuale che segue è solo per coloro che preferiscono configurare le credenziali da soli, o vogliono capire esattamente cosa Capgo fa sotto la cappa.

La prima costruzione manuale

Prima di poter iniziare a pensare a costruire l'applicazione con Capgo, dovremmo prima configurarla e fare una prima costruzione Android a mano. Ci sono alcuni vantaggi a fare una costruzione manuale prima:

• Preparerai le credenziali per la successiva costruzione Capgo
• Creerai un record sul Console di Store Play

Costruisci l'applicazione manualmente con Android Studio

Prima di poter iniziare a costruire l'applicazione con Capgo, dobbiamo costruire l'applicazione manualmente con Android Studio.

1. Apre Android Studio

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

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

3. Scegli Android App Bundle e clicca su Next

Creazione di un Keystore

Al momento attuale, manchi il file del keystore. Questo file viene utilizzato per firmare il tuo app, il che consente a Google di sapere che è stato tu a creare l'app. Per generarla, utilizzeremo il metodo GUI fornito da Android Studio. Esiste anche una possibilità di farlo con la riga di comando, ma non lo copriremo in questo tutorial.

1. Clicca su Create new

2. Inserisci percorso del Key Store

   Attenzione

   Questo DEVE ESSERE SALVATO - verrà utilizzato in seguito

3. Imposta la password del Key Store

   Nota

   Raccomando di utilizzare la stessa password per il Key Store e il Key Alias.

   Attenzione

   Questo DEVE ESSERE SALVATO - verrà utilizzato in seguito

4. Compilare il resto del modulo

   1. Mantieni il Key Alias come è (key0)
   2. Compilare i dettagli del certificato. Ho riempito i dettagli con dati falsi, ma dovresti riempirli con i tuoi dettagli.

   

5. Clicca su OK

Eseguire la costruzione manuale

1. Assicurati che tutti i dettagli per la chiave di sicurezza siano stati inseriti correttamente e clicca su Next

2. Seleziona il release varianta di costruzione e clicca su Create

3. Dopo che la costruzione ha avuto successo, dovresti vedere lo schermo seguente

   1. Questa finestra di popup indica che la costruzione è riuscita.
   2. Clicca sul locate tasto - questo aprirà l'esploratore dei file e dovresti vedere il build lì.

4. Assicurati di poter vedere il build nell'esploratore dei file

Creazione dell'app sul Console di Google Play

1. Vai a Console di Google Play

2. Seleziona il profilo del developer corretto

3. Clicca su Create app

4. Scegli il nome dell'app e la lingua

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

6. Accetta i termini e le condizioni

   Attenzione

   Assicurati di aver letto i termini e le condizioni prima di accettarli.

7. Clicca su Create

Stai creando il gruppo di testing interno

Ora che hai creato l'app, puoi creare un gruppo di testing interno. Poiché non pubblicherò effettivamente l'app per tutti su Play Store, dovrò creare un gruppo di testing interno.

Nota

Il testing interno è ancora la via più veloce per testare a fumo la tua build distribuita su Play prima di una vera e propria uscita.

Se il tuo account di sviluppatore è un account personale creato dopo il 13 novembre 2023, il testing interno non non rileva il requisito di testing chiuso per l'accesso alla produzione. Dovrai comunque avere un test chiuso con almeno 12 tester che hanno scelto di partecipare per 14 giorni consecutivi prima della produzione.

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

   

2. Clicca su Testers

3. Clicca su Create email list

4. Nomi la lista email

5. Aggiungi gli indirizzi email dei tester

6. Premi Enter e clicca su Save

7. Clicca su Create group

8. Assicurati di aver selezionato la nuova lista e clicca su Save

Caricare l'applicazione nel gruppo di testing interno

Ora che hai creato il gruppo di testing interno, puoi caricare l'applicazione nel gruppo di testing interno.

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

2. Clicca sul Releases tasto

3. Clicca sul Create new release

4. Clicca su Upload

5. Seleziona il file AAB

   Attenzione

   Assicurati di selezionare il file AAB che hai creato manualmente con Android Studio. Se questo file non utilizza la stessa chiave di sicurezza del keystore che utilizzerai per la Capgo build, la Capgo Build nativa fallirà.

6. Aspetta che il file AAB venga caricato

7. Clicca su Next

8. Correggi gli errori

   Personalmente, in questo stadio vedo questo errore

   

   Questo è perché non ho ancora verificato il mio numero di telefono. Lo farò e continuerò il tutorial.

9. Clicca su Save and publish Ciò pubblicherà l'applicazione nel gruppo di testing interno.

10. Conferma la pubblicazione

11. Assicurati che l'applicazione sia pubblicata

12. Ottieni il nome temporaneo dell'applicazione

Accetta l'invito al gruppo di testing interno

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

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

2. Clicca su Testers

3. Clicca su Copy link

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

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

6. Installa l'app

   1. Se hai già installato l'app prima di utilizzare Android Studio, clicca sul uninstall tasto
   2. Clicca sul install tasto
   3. Apri l'app e conferma che sia stato scaricato con successo

   Attenzione

   If non vedi l'applicazione nel negozio Play, assicurati di aver selezionato l'account corretto nel negozio Play.

Configurazione di Capgo Build nativo (Android)

Ora sei pronto a iniziare la configurazione di Capgo Build nativo. Congratulazioni! 🎉

Requisito	Flag	Descrizione	Obbligatorio
File del keystore	--keystore <path>	Percorso del tuo .jks/.keystore file utilizzato per firmare l'APK/AAB.	Sì
Alias del keystore	--keystore-alias <alias>	Nome dell'alias della chiave all'interno del keystore.	Sì
Password della chiave del keystore	--keystore-key-password <password>	Password della chiave. Se le password della chiave e del keystore coincidono, puoi fornire solo una.	Guarda la nota qui sotto
Password del keystore	--keystore-store-password <password>	Password del keystore. Se le password della chiave e del keystore coincidono, puoi fornire solo una.	Guarda la nota qui sotto
Account servizio Google Play	--play-config <path>	File JSON del servizio account per le pubblicazioni su 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 della chiave e dello store sono identiche, fornisci solo una delle due --keystore-key-password o --keystore-store-password.

Keystore, password del keystore, password della chiave del keystore, alias del keystore

Se hai seguito le istruzioni di costruzione manuale, dovresti avere già generato il keystore. Se non hai seguito le istruzioni, per favore segui le istruzioni per generare il keystore.

Account del servizio Google Play

La generazione dell'account del servizio Google Play è un processo manuale e complesso. Tuttavia, è necessario per caricare il tuo app su Google Play. Per favore, tenga presente le seguenti cose:

• Tu DEVI essere il proprietario dell'Account del Developer. Altrimenti, non sarai in grado di configurare l'account del servizio.
• Devi creare un nuovo progetto di Google Cloud (separato dal tuo account di Google Play)

Cominciamo.

1. Vai a Console di Google Cloud

2. Clicca sul selettore del progetto

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

   Nota

   I screenshot sotto sono illustrativi - utilizza un nome appropriato per il tuo progetto.

   1. Clicca su New project
   2. Nome il tuo progetto e clicca Create
   3. Assicurati di essere sul progetto giusto

4. Clicca sul campo di ricerca e cerca service accounts e clicca su di esso

5. Clicca su Create service account

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

   1. Raccomando di impostare il nome a Capgo Native Build Service Account
   2. Per l'ID dell'account di servizio, raccomando di impostarlo a capgo-native-build-service-acc
   3. Per quanto riguarda la descrizione, non è necessario compilare il campo, ma raccomando di riempirlo con Allows Capgo Native Build to build and submit the app to the Play Store

   

7. Clicca sull'account di servizio appena creato Ora dovresti vedere l'account di servizio appena creato nella lista. Clicca su di esso.

   Nota

   Copia anche questa email, ne avrai bisogno più tardi.

8. Clicca sul Keys tab

9. tab delle chiavi in Google Console Add Key Clicca su Create new key

10. aggiungi una nuova chiave in Google Console JSON Clicca su Create

    Attenzione

    Cliccando su Create creerà una nuova chiave e scaricherà il file JSON sul tuo computer locale.

    È necessario salvare il file JSON in un posto sicuro. Esso SI sarà utilizzato in seguito.

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

Concedere a Play Store API l'accesso al conto utente

Il nuovo conto utente creato non ha ancora accesso a Play Store API. Per concederglielo, vai al Console di Play Store.

1. Vai a Google Play Console
2. Seleziona il profilo del sviluppatore corretto
3. Clicca su Users and permissions
4. Clicca su Invite new users
5. Copia l'indirizzo email del servizio account
6. Vai a Account permissions e concedi i permessi minimi richiesti:
   • In App permissions, concedi accesso all'applicazione.
   • In Releases, abilita Create, edit, and roll out releases.
   • Se il tuo workflow utilizza Play App Signing, abilita il relativo permesso di firma.
   • Se sei incerto, utilizza Admin solo durante la configurazione, quindi riduci i permessi in seguito.
7. Clicca su Invite user
8. Conferma l'invito
9. Conferma di aver inviato l'utente

Salvataggio delle credenziali

Sei pronto a salvare le credenziali e eseguire la tua prima build. Puoi salvare le credenziali utilizzando 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 Azioni)

Se hai già completato Keystore, password del keystore, password della chiave del keystore, alias del keystore e Account Google Play, hai già tutto ciò che ti serve per CI/CD. Questa sezione copre solo come passare questi valori come segreti e variabili d'ambiente GitHub delle azioni.

1) Converti i file di credenziali in base64 a riga singola

# 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

Suggerimento

I segreti GitHub dovrebbero essere valori a riga singola. tr -d '\n' rimuove i ritorni a capo dall'output in base64.

2) Crea segreti del repository

In GitHub > Repository > Settings > Secrets and variables > Actionsaggiungi:

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

Nota

Se le password della chiave e dello store sono le stesse, puoi fornire solo una delle due KEYSTORE_KEY_PASSWORD o KEYSTORE_STORE_PASSWORD.

3) Utilizza le variabili di ambiente nel tuo GitHub workflow di 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 }}

Suggerimento

Con questo setup, il CI invia le credenziali attraverso le variabili di ambiente solo. Non è necessario commitare i file di firma o caricarli come artefatti del workflow.

Eseguire la costruzione

Congratulazioni! 🎉! È ora pronto a eseguire la sua prima costruzione.

Esegui:

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

E questo avvierà il processo di costruzione 🍾🥂

Invia la versione di rilascio di Play per la revisione

Di default, i rilasci di costruzione Android caricano su Google Play e possono rimanere inattivi fino a quando non finisci il rilascio nel Console di Play. Se il suo rilascio CI dovrebbe inviare la versione di rilascio di Play automaticamente, passa --submit-to-store-review con un rilascio di costruzione:

npx @capgo/cli@latest build request com.example.app \
  --platform android \
  --build-mode release \
  --submit-to-store-review \
  --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"

Richiede la stessa configurazione dell'account Google Play per l'upload normale (PLAY_CONFIG_JSON in CI o salvare le credenziali Android localmente). --store-release-name viene utilizzato come nome di rilascio di Google Play. --store-release-notes è il changelog di fallback di Play, e ogni --store-release-notes-locale "locale=notes" entry scrive un changelog di Play localizzato per quel locale. Capgo invia il rilascio di Play come completed; se è abilitata la pubblicazione gestita nel Console di Play, Google può ancora attendere la tua pubblicazione manuale dopo l'approvazione.

Continua da Android Builds

Se stai utilizzando Android Builds per pianificare l'automazione CI/CD, connettilo con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD, Capgo Costruzioni Native per il flusso di lavoro del prodotto in Capgo Costruzioni Native, Capgo Integrazioni per il flusso di lavoro del prodotto in Capgo Integrazioni, Integrazione CI/CD per il dettaglio di implementazione in Integrazione CI/CD, e GitHub Integrazione Azioni per il dettaglio di implementazione in GitHub Integrazione Azioni.