Costruzione degli 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

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

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

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

La prima costruzione manuale

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

• Preparerete le credenziali per la successiva costruzione 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 costruito 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

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

   Attenzione

   Questo DA SALVARE - verrà utilizzato in seguito

4. Riempi il resto del modulo

   1. Mantieni il Key Alias 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 il keystore e clicca su Next

2. Scegliere il release Scegliere il build variant e clicca su Create

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

   1. Questo popup indica che il build è stato completato con successo.
   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 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'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, dovrò creare un gruppo di testing interno.

Nota

Il testing interno è ancora la via più veloce per testare 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. Nome della lista di indirizzo email

5. Aggiungi gli indirizzi email dei testatori

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 bottoni

3. Clicca su Create new release

4. Clicca su Upload

5. Selezionare 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. Attendere 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'applicazione nel gruppo di testing interno.

10. Conferma la pubblicazione

11. Sicura 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. Inviare il link al tuo telefono, aprilo 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 bottoni
   2. Clicca sul install bottoni
   3. Apri l'app e conferma che è stato scaricato correttamente

   Attenzione

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

Configurazione della costruzione nativa Capgo (Android)

Ora sei pronto a iniziare la configurazione della costruzione nativa Capgo. 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>	La password della chiave. Se le password della chiave e del keystore coincidono, puoi fornire solo una.	Guarda la nota sotto.
Password del keystore	--keystore-store-password <password>	La password del keystore. Se le password della chiave e del keystore coincidono, puoi fornire solo una.	Guarda la nota sotto.
Account del servizio Google Play	--play-config <path>	File JSON di account servizio 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 chiave e archivio sono identiche, fornisci solo una delle due. --keystore-key-password o --keystore-store-password.

Keystore, password del keystore, password 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, generatelo per favore.

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. Tenete presente le seguenti cose:

• Voi NECESSARIO essere il proprietario dell'Account del Developer. Altrimenti, non potrete configurare l'account di servizio.
• Deverete creare un nuovo progetto Cloud Google (separato dal vostro account Google Play)

Iniziare

1. Vai a Console Cloud di Google

2. Clicca sul selettore del progetto

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

   Nota

   Le schermate sottostanti 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. 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 Dovresti ora 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. 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. 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 al conto 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 del tuo account di sviluppatore
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 alla tua app.
   • In Releases, abilita Create, edit, and roll out releases.
   • Se il tuo workflow utilizza Play App Signing, abilita il permesso di firma correlato.
   • 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 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 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 devono 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 > Actions, aggiungi:

Nome segreto	Valore
CAPGO_TOKEN	Il tuo token Capgo API
APP_ID	ID dell'applicazione Capgo (esempio: com.example.app)
ANDROID_KEYSTORE_FILE	Contenuto di keystore_base64.txt
KEYSTORE_KEY_ALIAS	Alias del keystore da Alias del 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 della chiave e dello 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 workflow github 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.

Eseguire la costruzione

Congratulazioni! È pronto a eseguire il suo primo build.

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

Sul sistema Android, --submit-to-store-review predefinito su la produzione context: Pagina/Area: Pagina prodotti di aggiornamenti in tempo reale. Ruolo: Etichetta breve o elemento di navigazione. Chiave di messaggio `live_update_dynamic_label_production` (Etichetta dinamica di aggiornamento in tempo reale - Produzione). release_status: completed seguire con --android-track internal quando non si imposta un seguimento. Ciò può andare in live fino al 100% degli utenti. Passa alpha / beta(o PLAY_STORE_TRACK ) — o imposta --android-release-status / PLAY_STORE_RELEASE_STATUS quando hai bisogno di uno stato diverso da completed.

Ciò richiede la stessa configurazione del conto Google Play per l'upload normale (PLAY_CONFIG_JSON in CI o le credenziali Android salvate localmente). --store-release-name viene utilizzato come il Google Play version_name. --store-release-notes è il changelog di fallback Play, e ogni --store-release-notes-locale "locale=notes" inserisce un changelog Play localizzato per quel locale. Capgo invia la rilascio di Play come completed a meno che non si sovrapponga --android-release-status; 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 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.