Costruzione Android

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

Questo che imparerai

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

Prerequisiti

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

Nota

I 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 del servizio Google Play) per voi — questo è il percorso consigliato:

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

Il walkthrough manuale di seguito è solo per coloro che preferiscono configurare le credenziali da soli o desiderano capire esattamente cosa Capgo fa sotto la cappa.

Il primo build manuale

Prima di poter iniziare a pensare a costruire l'app con Capgo, dovremmo prima configurarla e fare un primo build Android a mano. Ci sono alcune vantaggi nel fare un build manuale per primo:

• Preparerete le credenziali per il successivo build di Capgo
• Crea un record sul Console di Store Play

Costruisci l'app manualmente con Android Studio

Prima di poter iniziare a costruire l'app con Capgo, dobbiamo costruire l'app 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

Attualmente, manca il file del keystore. Questo file viene utilizzato per firmare l'app, il che consente a Google di sapere che è stato creato da te. Per generarne uno, 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. 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 per l'Alias della chiave.

   Attenzione

   Questo DA SALVARE - verrà utilizzato in seguito

4. Riempi il resto del modulo

   1. Mantieni l'Alias della chiave come è (key0)
   2. Compilare i dettagli del certificato. Ho compilato con dettagli falsi, ma dovresti compilare con i tuoi dettagli.

   

5. Clicca su OK

Concludere la costruzione manuale

1. Assicurati di aver compilato correttamente tutti i dettagli per la chiave di archiviazione e clicca su Next

2. Seleziona il release build variant e clicca su Create

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

   1. Questo popup indica che la costruzione è andata a buon fine.
   2. Clicca sul locate tasto - ciò aprirà l'esploratore dei file e dovresti vedere la costruzione lì.

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

Creazione dell'app sul Console di Store Play

1. Vai a Console di Giocatori di Google

2. Seleziona il profilo di sviluppatore corretto

3. Clicca su Create app

4. Scegli il nome dell'applicazione e la lingua

5. Seleziona la categoria dell'applicazione 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, dovrò creare un gruppo di testing interno.

Nota

La testing interno è ancora la via 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 testing interna non non riplace la richiesta di testing chiuso per l'accesso alla produzione. Dovrai ancora 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 di indirizzi email

5. Aggiungi gli indirizzi email dei testatori

6. Premi Enter e clicca su Save

7. Seleziona il pulsante Create group

8. Assicurati che la nuova lista sia selezionata e seleziona il pulsante 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. Seleziona il Releases Pulsante

3. Clicca su 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 lo stesso keystore di quello che utilizzerai per la Capgo costruzione, la costruzione nativa Capgo fallirà.

6. Aspetta che il file AAB venga caricato

7. Clicca su Next

8. Correggi gli errori

   Personalmente, in questa fase 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 Questo pubblicherà l'app nella sezione di testing interna.

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. Inviare il link al tuo telefono, aprilo 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 è stato scaricato con successo

   Attenzione

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

Configurazione della costruzione nativa Capgo (Android)

Ora sei pronto a iniziare la configurazione della costruzione nativa Capgo. Congratulazioni!

Requisito	Flag	Descrizione	Richiesto
File del keystore	--keystore <path>	Percorso al 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>	La password della chiave deve corrispondere a quella del keystore.	Guarda la nota sotto.
Password del keystore	--keystore-store-password <password>	La password del keystore deve corrispondere a quella della chiave.	Guarda la nota sotto.
Account del servizio Google Play	--play-config <path>	File JSON di servizio account per caricamenti 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 Istruzioni di costruzione manualeAvete già generato il keystore. Se non avete seguito le istruzioni, per favore seguiteli per generare il keystore.

Account di servizio Google Play

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

• Voi context Avete bisogno contextdi essere il
• context

proprietario dell'Account del Developer

1. context Console di Google Cloud

2. Clicca sul selettore del progetto

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

   Nota

   Le schermate di seguito sono esemplificative - 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. Clicca sul campo di ricerca e cerca service accounts e clicca su di esso

5. Clicca su Create service account

6. Clicca sul pulsante di creazione del servizio account Done

   1. Riempi il modulo per il servizio account e clicca su Capgo Native Build Service Account
   2. Consiglio di impostare il nome a capgo-native-build-service-acc
   3. Consiglio di impostare l'ID del servizio account a Allows Capgo Native Build to build and submit the app to the Play Store

   

7. Riempi il modulo per il servizio account in Google Console e clicca sul pulsante di creazione del servizio account. Clicca sul servizio account appena creato. Dovresti ora vedere il servizio account appena creato nella lista. Clicca su di esso.

   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 posto sicuro. Esso 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 all'account di servizio

Il servizio account appena creato non ha ancora accesso al servizio API di Play Store. Per concederglielo, accedi al Console di Play Store.

1. Vai a Console di Google Play
2. Seleziona il profilo di 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 concede i permessi minimi richiesti:
   • In App permissions, concede 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 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

Salvataggio delle credenziali

Sei ora pronto a salvare le credenziali e eseguire il primo 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 di Google PlayPer la configurazione CI/CD hai già tutto ciò di cui hai bisogno. Questa sezione copre solo come passare questi valori come segreti e variabili di ambiente di GitHub Actions.

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 di GitHub dovrebbero essere valori a riga singola. tr -d '\n' rimuove i salti di riga dall'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 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	Keystore store password
PLAY_CONFIG_JSON	Contenuto di play_config_base64.txt

Nota

Se le password per la chiave e lo store sono le stesse, puoi fornire solo una delle KEYSTORE_KEY_PASSWORD o KEYSTORE_STORE_PASSWORD.

3) Use env vars in your GitHub Actions workflow

Sezione intitolata “3) Utilizza le variabili di ambiente nel tuo github workflow di Actions”

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

Esegui 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 costruzione

Congratulazioni! È 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 release di Play per la revisione

Di default, le costruzioni di rilascio Android caricano su Google Play e possono rimanere inattive fino a quando non finisci la release nel Console di Play. Se la tua release CI dovrebbe inviare la release di Play automaticamente, passa --submit-to-store-review con una costruzione di rilascio:

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 sul produzione seguire con release_status: completed quando non si imposta un track. Ciò può andare in live a 100% degli utenti. Passa --android-track internal (o alpha / beta) — o imposta PLAY_STORE_TRACK in CI — per mantenere la versione completata su un track non di produzione. --android-release-status / PLAY_STORE_RELEASE_STATUS quando hai bisogno di uno stato diverso da completed.

Questa richiede la stessa configurazione del conto Google Play per l'upload normale (PLAY_CONFIG_JSON in CI o credenziali Android salvate localmente). --store-release-name viene utilizzato come il servizio Google Play version_name. --store-release-notes è il changelog di fallback Play, e ogni --store-release-notes-locale "locale=notes" entry scrive un changelog Play localizzato per quel locale. Capgo invia la rilascio di Play come completed se non sovrascrivi --android-release-status; 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 Costruzione di Android per pianificare l'automazione CI/CD, connettilo con Capgo automazione CI/CD per il flusso di lavoro del prodotto in Capgo automazione CI/CD, Capgo Costruzioni native per il flusso di lavoro del prodotto in Capgo Costruzioni native, Capgo Integrazioni for the product workflow in Capgo Integrations, per il flusso di lavoro del prodotto in __CAPGO_KEEP_0__ Integrazioni, Integrazione CI/CD GitHub Actions Integration for the implementation detail in GitHub Actions Integration.