Costruzioni Android

Costruisci 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

• È necessario avere un account Google Developer attivo
• È necessario avere installato Android Studio
• Il tuo 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

Consigliato: onboarding automatizzato

Non è necessario 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 che segue è destinata a 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 alcune vantaggi a fare una costruzione manuale prima:

• Si prepareranno le credenziali per la successiva costruzione con Capgo
• Si creerà un record sul Console di Store Play

Costruire l'applicazione manualmente con Android Studio

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

1. Apri Android Studio

   Avvia 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

In questo momento, manca il file del keystore. Questo file viene utilizzato per firmare l'app, il che consente a Google di sapere che è stato costruito da te. Per generarne uno, 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 la percorso della Key Store

   Attenzione

   Questo DEVE ESSERE SALVATO - verrà utilizzato in seguito

3. Imposta la password della Key Store

   Nota

   Consiglio di utilizzare la stessa password per la Key Store e l'Alias della Key.

   Attenzione

   Questo DEVE ESSERE SALVATO - verrà utilizzato in seguito

4. Compilare il resto del modulo

   1. Mantieni l'Alias della Chiave 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

Completa la costruzione manuale

1. Assicurati che tutti i dettagli per il keystore siano stati inseriti correttamente e clicca su Next

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

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

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

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

Crea l'app sul Console di Google Play

1. Vai a Console di Google Play

2. Seleziona il profilo di 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 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, dovrò creare un gruppo di testing interno.

Nota

La prova interna è ancora il modo più veloce per testare a fumetti 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, la prova interna 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 scelto di partecipare per 14 giorni consecutivi prima della produzione. Vai a Clicca su

1. Google Play Console prova interna internal testing Clicca su Test and release -> Testing -> Internal testing

   

2. Clicca su Testers

3. Se il tuo account di sviluppatore è un account personale creato dopo il 13 novembre 2023, la prova interna 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 scelto di partecipare per 14 giorni consecutivi prima della produzione. Create email list

4. Nome la lista degli indirizzi 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

Carica l'app nella lista di testing interna

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 di rilascio della Console di gioco di Google

3. Console di gioco di Google crea nuovo rilascio Create new release

4. Console di gioco di Google carica Upload

5. __CAPGO_KEEP_0__

   Attenzione

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

6. Attendere che il file AAB venga caricato

7. Clicca su Next

8. Correggi gli errori

   Personalmente, in questo stadio 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 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 “downloadalo dal Play Store”

6. Installa l'app

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

   Configurazione di __CAPGO_KEEP_0__ Build Nativo (Android)

   Sezione intitolata “Configurazione di __CAPGO_KEEP_0__ Build Nativo (Android)”

Configuring Capgo Native Build (Android)

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

Requisito	Bandiera	Descrizione	Richiesto
File 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 della chiave e del 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 della chiave e del keystore coincidono, puoi fornire solo una.	Guarda la nota qui sotto
Account del 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 di esse --keystore-key-password o --keystore-store-password.

Chiave di sicurezza, password della chiave di sicurezza, password della chiave di sicurezza, alias della chiave di sicurezza

Se hai seguito le istruzioni di costruzione manuali, dovresti avere già generato la chiave di sicurezza. Se non hai seguito le istruzioni, per favore segui le istruzioni per generare la chiave di sicurezza.

Account di servizio Google Play

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

• Tu È necessario essere il proprietario dell'Account di sviluppatore per poter configurare l'account del servizio . Altrimenti non sarà possibile configurare l'account del servizioPer poter configurare l'account del servizio è necessario essere il proprietario dell'Account di sviluppatore
• . Altrimenti non sarà possibile configurare l'account del servizio

È necessario creare un nuovo progetto di Google Cloud (separato dal tuo account Google Play)

1. Iniziare Vai a

2. Console di Google Cloud

3. Selezionatore di progetti di Google Console

   Nota

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

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

4. Clicchiamo sul campo di ricerca e cerchiamo per service accounts e clicca su di esso

5. Clicchiamo sul 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, ma raccomando di riempirla 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 in seguito.

8. Clicca su 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. Lo 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.

Concessione di accesso al servizio di account Play Store API

L'account di servizio appena creato non ha ancora accesso al Play Store API. Per concederglielo, vai al Console di Google Play.

1. Vai a Console di Google Play
2. Seleziona il profilo del developer 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 permissionse concedi l'accesso all'app.
   • In Releases, abilita Create, edit, and roll out releases.
   • Se il tuo workflow utilizza l'applicazione di firma Play, 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

Salva le credenziali

Siete ora pronti a salvare le credenziali e eseguire la 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 Actions)

Se hai già completato Keystore, password del keystore, password della chiave del keystore, alias del keystore e account di servizio Google Play, hai già tutto ciò che ti serve per la configurazione CI/CD. Questa sezione copre solo come passare quei valori come segreti e variabili di ambiente di GitHub Actions.

1) Converti i file di credenziali in una riga base64 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

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

2) Crea segreti del repository

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

Nome del segreto	Valore
CAPGO_TOKEN	Il tuo token Capgo API
APP_ID	Il tuo ID dell'app Capgo (ad 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 di archiviazione
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 delle due KEYSTORE_KEY_PASSWORD o KEYSTORE_STORE_PASSWORD.

3) Utilizza le variabili di ambiente nel tuo GitHub Actions workflow

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

Esecuzione della costruzione

Congratulazioni! 🎉! Ora sei pronto a eseguire la tua prima costruzione.

Esegui:

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

E questo avvierà il processo di costruzione 🍾🥂

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 Native Builds per il flusso di lavoro del prodotto in Capgo Native Builds Capgo Integrazioni per il flusso di lavoro del prodotto in Capgo Integrazioni, Integrazione CI/CD per la dettagliata implementazione in Integrazione CI/CD, e GitHub Azioni Integrazione per la dettagliata implementazione in GitHub Azioni Integrazione.