Costruzioni Android

Crea e invia app Android su Google Play Store utilizzando l'infrastruttura dedicata di Capgo.

Cosa imparerai

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

Requisiti preliminari

• You devi avere un account Google Developer attivo
• Devi avere Android Studio installato
• La tua app deve poter costruire con successo con Android Studio

Nota

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

La prima costruzione manuale

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

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

Costruire 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. 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

Creare una chiave di sicurezza

Attualmente, manca il file del keystore. Questo file viene utilizzato per firmare il tuo'app, il che consente a Google di sapere che è stato costruito da te.

1. Per generarlo, utilizzeremo il metodo GUI fornito da Android Studio. Create new

2. Clicca su

   Inserisci percorso del Key Store in Android Studio

   Attenzione Attenzione Questo

3. DEVE ESSERE SALVATO - verrà utilizzato in seguito

   Nota

   Raccomando di utilizzare la stessa password per il Key Store e per l'Alias della chiave.

   Attenzione

   Questo DEVE ESSERE SALVATO - verrà utilizzato in seguito

4. Compila il resto del modulo

   1. Mantieni l'Alias della chiave come è (key0)
   2. Compila i dettagli del certificato. Ho riempito i campi con dati falsi, ma dovresti riempirli con i tuoi dati.

   

5. Cliccare su OK

Concludere la compilazione manuale

1. Assicurarsi che tutti i dettagli per la chiave di sicurezza siano stati compilati correttamente e cliccare su Next

2. Selezionare il release varianta di build e cliccare su Create

3. Dopo che la compilazione riesce, dovresti vedere lo schermo seguente

   1. Questo popup indica che la compilazione è riuscita.
   2. Clicca sul locate tasto - questo aprirà l'esploratore dei file e dovresti vedere la compilazione lì.

4. Assicurati di poter vedere la compilazione nell'esploratore dei file

Creazione dell'app sul Console di Google Play

1. Vai a Console di Google Play

2. Seleziona il profilo di sviluppatore corretto

3. Clicca sul 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 aver letto i termini e le condizioni prima di accettarli.

7. Clicca su Create

Creazione del gruppo di testing interno

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

Nota

Il testing interno è ancora la via più veloce per testare la tua build Play-distribuita 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 sostituisce il requisito di testing chiuso per l'accesso alla produzione. Avrai ancora bisogno di un test chiuso con almeno 12 tester che hanno optato per la partecipazione 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 di email

5. Aggiungi gli indirizzi email dei tester

6. Premi Enter e clicca su Save

7. Clicca su Create group

8. Assicurati che la nuova lista sia selezionata 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 bottoni di rilascio di Console di Giocatore Google

3. bottoni 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 costruzione, la costruzione nativa Capgo fallirà.

6. Attendere che il file AAB venga caricato

7. Clicca su Next

8. Correggi gli errori

   Personalmente, in questa fase vedo questo errore

   

   Ciò accade 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'app 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 utilizzando Android Studio, clicca sul uninstall bottoni
   2. Clicca sul install bottoni
   3. Apri l'app e conferma che si è scaricata con successo

   Attenzione

   Se non vedi l'applicazione nel Play Store, assicurati di aver selezionato l'account corretto nel Play Store.

Configurazione di Capgo Build Nativo (Android)

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

Requisito	Flag	Descrizione	Richiesto
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 per la chiave. Se le password chiave/keystore coincidono, puoi fornire solo una.	Guarda la nota qui sotto
Password del keystore	--keystore-store-password <password>	Password per il keystore. Se le password chiave/keystore coincidono, puoi fornire solo una.	Guarda la nota qui sotto
Account servizio Google Play	--play-config <path>	File JSON del servizio account per gli upload su Play Store.	Sì

bunx @capgo/cli 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. Copiare negli appuntiNota

Account di servizio Google Play

La generazione dell'account di servizio Google Play è un processo manuale e complesso. Tuttavia, è necessario per caricare il tuo'applicazione su Google Play. Tieni presente le seguenti cose:

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

Iniziare

1. Andare a Google Cloud Console

2. Clicca sul selettore del progetto

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

   Nota

   Le schermate sottostanti sono illustrate - utilizza un nome appropriato per il tuo progetto.

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

4. Clicchiamo sul campo di ricerca e cerchiamo service accounts e cliccaci sopra

5. Clicchiamo su Create service account

6. Compiliamo il modulo per il servizio account e cliccaci sopra Done

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

   

7. Clicchiamo sul servizio account appena creato Ora dovreste vedere il servizio account appena creato nella lista. Cliccaci sopra.

   Nota

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

8. Clicca sul Keys tab

9. Clicca su Add Key e Create new key

10. Clicca su JSON e 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 luogo sicuro. Sarà SI 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 all'account di servizio

L'account del servizio appena creato non ha ancora accesso al negozio Play API. Per concederglielo, accedi al Console del negozio Play.

1. Vai a Console del negozio Google Play
2. Seleziona l'account del sviluppatore corretto
3. Clicca su Users and permissions
4. Clicca su Invite new users
5. Copia l'indirizzo email dell'account del servizio
6. Vai a 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 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 che l'utente è stato invitato

Salvataggio delle credenziali

Sei ora pronto a salvare le credenziali e eseguire la tua prima build. Puoi salvare le credenziali utilizzando il seguente comando:

bunx @capgo/cli 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 di servizio di Google Play, you already have everything needed for CI/CD. This section only covers how to pass those values as GitHub Actions secrets and environment variables.

Questa sezione copre solo come passare questi valori come segreti __CAPGO_KEEP_0__ Actions e variabili di ambiente.

# 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

GitHub secrets should be single-line values. tr -d '\n' __CAPGO_KEEP_0__ segreti dovrebbero essere valori a riga singola.

2) Crea segreti del repository

Inserisci: GitHub > Repository > Settings > Secrets and variables > ActionsNome segreto

Valore	Il tuo __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ token
CAPGO_TOKEN	Your Capgo API token
APP_ID	Your Capgo app ID (example: com.example.app)
ANDROID_KEYSTORE_FILE	Alias della chiave del keystore da keystore_base64.txt
KEYSTORE_KEY_ALIAS	Keystore, password del keystore, password della chiave del keystore, alias della chiave del keystore Password della chiave del keystore
KEYSTORE_KEY_PASSWORD	2) Crea segreti del repository
KEYSTORE_STORE_PASSWORD	Impostazione della password del keystore
PLAY_CONFIG_JSON	Contenuto di play_config_base64.txt

Nota

Se le password della chiave e del keystore sono le stesse, puoi fornire solo una di 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 ${{ 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 questa configurazione, il CI invia le credenziali attraverso le variabili di ambiente solo. Non è necessario commitare i file di firma o caricarli come artefatti di workflow.

Esecuzione della costruzione

Congratulazioni 🎉! Siete ora pronti per eseguire la prima costruzione.

Esegui:

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

E questo avvierà il processo di costruzione 🍾🥂