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 di base

• Dovete avere un account Google Developer attivo
• Dovete avere installato Android Studio
• La vostra app deve riuscire a compilarsi 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 dovete fare nulla di tutto ciò a mano. L'onboarding di Capgo crea e configura i vostri credenziali di firma Android (keystore + account servizio Google) per voi — questo è il percorso consigliato:

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

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

La prima costruzione manuale

Prima di poter iniziare a pensare alla costruzione dell'applicazione con Capgo, dovremmo prima configurarla e fare una prima costruzione Android a mano. Ci sono alcuni 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. Aprite Android Studio

   Eseguite 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 generarla, utilizzeremo il metodo GUI fornito da Android Studio. Esiste anche un modo per farlo con la riga di comando, ma non lo copriremo in questo tutorial.

1. Clicca su Create new

2. Compila il 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 per l'alias del Key.

   Attenzione

   Questo __CAPGO_KEEP_0__ - verrà utilizzato in seguito

4. Riempire il resto del modulo

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

   

5. Clicca su OK

Ultimazione della costruzione manuale

1. Assicurati di aver riempito correttamente tutti i dettagli per il keystore e clicca su Next

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

3. Dopo il successo della compilazione, dovresti vedere lo schermo seguente

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

4. Assicurati di poter vedere la build nell'esploratore di file

Creare 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 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ò effettivamente l'app per tutti su Play Store, avrò bisogno di creare un gruppo di testing interno.

Nota

La prova interna è ancora la via più veloce per testare il tuo build distribuito 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. Nome la lista email Create email list

4. Nomi la lista email

5. Inserisci gli indirizzi email dei tester

6. Premi Enter e clicca su Save

7. Clicca su Create group

8. Assicurati che sia selezionata la nuova lista e clicca su Save

Carica 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 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 caricamento Upload

5. Console di gioco di Google selezione del file AAB

   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 il caricamento del file AAB

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 Pubblicherà l'applicazione nel gruppo di testing 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 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 “downloadalo su 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

   Attenzione

   Se non vedi l'app nel Store di Play, assicurati di aver selezionato la conta corretta nel Store di Play.

Configurazione di Capgo Build Nativo (Android)

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

Requisito	Flag	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 dello store corrispondono, puoi fornire solo una.	Guarda la nota qui sotto
Password dello store del keystore	--keystore-store-password <password>	Password per il keystore. Se le password della chiave e dello store corrispondono, puoi fornire solo una.	Guarda la nota qui sotto
Account del servizio Google Play	--play-config <path>	File JSON dell'account del servizio per gli upload 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 chiavi e le password del magazzino 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 PlaySezione intitolata “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. Ricorda le seguenti cose:

HAI BISOGNO

• or Keystore, keystore password, keystore key password, keystore alias per essere il proprietario dell'Account del Developer . Altrimenti, non potrai configurare l'account del servizio.Avrai bisogno di creare un nuovo progetto di Google Cloud (separato dal tuo account Google Play)
• Iniziare

Vai a

1. Console di Google Cloud Clicca sul selettore del progetto

2. Selettore del progetto di Console di Google

3. Nota

   Nota

   Sono disponibili delle schermate di esempio - scegli un nome adatto al tuo progetto.

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

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

5. Clicca su Create service account

6. Compilare il modulo per il conto utente e cliccare su Done

   1. Raccomando di impostare il nome a Capgo Native Build Service Account
   2. Per l'ID del conto utente, 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. Cliccare sul conto utente appena creato Dovresti ora vedere il conto utente appena creato nella lista. Cliccare su di esso.

   Nota

   Copiare anche questa email, ne avrai bisogno in seguito.

8. Cliccare 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 posto sicuro. SARÀ utilizzato in seguito. Scarica il file JSON Il file JSON dovrebbe essere stato scaricato automaticamente. Puoi cliccare su

11. per chiudere la finestra. close Chiave di download del Console di Google

Sezione intitolata “Concedere al servizio di account l'accesso al Play Store API”

The newly created service account does not yet have access to the Play Store API. To grant it, head to the Play Store Console.

1. Console di Google Play Seleziona il profilo del developer corretto
2. Console di Google Play seleziona profilo del developer corretto
3. Clicca su Users and permissions
4. Clicca su Invite new users
5. Copia l'indirizzo email dell'account di servizio
6. Vai a Account permissions e concedi le autorizzazioni minime richieste:
   • In App permissionsconcedi l'accesso alla tua app.
   • In Releasesabilita Create, edit, and roll out releases.
   • If il tuo workflow utilizza Play App Signing, abilita il relativo permesso di firma.
   • If sei incerto, utilizza Admin solamente 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

Salvare le credenziali

Siete ora pronti a salvare le credenziali e eseguire la prima build.

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

CI/CD setup (GitHub Actions)

Sezione intitolata “Configurazione CI/CD (__CAPGO_KEEP_0__ Actions)” Se hai già completato Keystore, password del keystore, password della chiave del keystore, alias del keystore e, you already have everything needed for CI/CD. This section only covers how to pass those values as GitHub Actions secrets and environment variables.

Se hai già completato tutto ciò che serve per la configurazione CI/CD. Questa sezione copre solo come passare quei valori come segreti e variabili di ambiente di __CAPGO_KEEP_0__ Actions.

# 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 dall'output base64.

2) Crea segreti del repository

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

Nome del segreto	Valore
CAPGO_TOKEN	Il tuo Capgo API token
APP_ID	Il tuo Capgo ID dell'applicazione (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
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 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 di workflow.

Esecuzione della build

Congratulazioni! 🎉! Ora sei pronto a eseguire il tuo primo build.

Esegui:

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

E questo inizierà il processo di costruzione 🍾🥂

Sottopone la versione di gioco per la revisione

Di default, le versioni di rilascio Android caricano su Google Play e possono rimanere inattive fino a quando non finisci il rilascio nel Console di gioco. Se il tuo rilascio CI dovrebbe sottoporre automaticamente la versione di gioco per la revisione, passa --submit-to-store-review con una versione di rilascio:

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"

Ciò richiede la stessa configurazione del servizio Google Play come il percorso di caricamento normale (PLAY_CONFIG_JSON in CI o salvate 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" L'ingresso scrive un changelog localizzato per Play per quel locale. Capgo invia la versione di rilascio di Play come completed; se la pubblicazione gestita è abilitata 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 Native Builds per il flusso di lavoro del prodotto in Capgo Native Builds, Capgo Integrations per il workflow del prodotto in Capgo Integrations, Integrazione CI/CD per i dettagli di implementazione in Integrazione CI/CD, e GitHub Azioni di integrazione per i dettagli di implementazione in GitHub Azioni di integrazione.