Costruzione 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 Build Nativo
• Imparerai a configurare le credenziali per Capgo Build Nativo

Prerequisites

• 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

Utilizzerò l'app seguente per il tutorial: https://github.com/Cap-go/capgo-tutorial-di-costruzione-nativa-per-app-di-Android

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

The manual walkthrough below is only for those who prefer to set up credentials themselves, or want to understand exactly what Capgo does under the hood.

Il primo build manuale

Before we can start thinking about building the app with Capgo, we should first set it up, and do a first Android build by hand. There are some advantages to doing a manual build first:

• Preparerete le credenziali per la successiva Capgo costruzione
• Crerai un record sul Console di Store Play

Costruire l'applicazione manualmente con Android Studio

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

1. Apre Android Studio

   Esegui bunx cap open android Apri il progetto di Android Studio.

2. Clicca su Build -> Generate Signed App Bundles / APKs

3. Scegli Android App Bundle Esegui clic su Next

Crea un Keystore

Attualmente, manchi del file keystore. Questo file viene utilizzato per firmare il tuo'app, il che consente a Google di sapere che è stato tu a creare l'app. Per generarla, utilizzeremo il metodo GUI fornito da Android Studio. Esiste anche una modalità 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 Keystore e l'Alias della chiave.

   Attenzione

   Questo DEVE ESSERE SALVATO - verrà utilizzato in seguito

4. Compila il resto del modulo

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

   

5. Click su OK

Ultimo passaggio della compilazione manuale

1. Assicurati che tutti i dettagli per la chiave di registro siano stati inseriti correttamente e clicca su Next

2. Scegli il release build variant e clicca su Create

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

   1. Questa finestra di popup indica che la compilazione è riuscita.
   2. Clicca sul locate tasto - ciò 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 Store Play

1. Vai a Console di Giocatori di Google

2. Seleziona il profilo di sviluppatore corretto

3. Clicca sul Create app

4. Scegli il nome dell'app e la lingua

5. Scegli 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 test interni

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

Nota

La prova interna è ancora la via più veloce per testare la tua build distribuita con 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 subentra 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. Nomi la lista di indirizzi email

5. Aggiungi gli indirizzi email dei testatori

6. Premi Enter e clicca su Save

7. Clicca su Create group

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

Caricamento dell'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

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 la stessa chiave di sicurezza del keystore 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'applicazione nel gruppo di testing interno.

10. Conferma la pubblicazione

11. Sicurezza che l'applicazione sia pubblicata

12. Assicurati di ottenere 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. Inviare il link al tuo telefono, aprirlo nel browser e cliccare 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 bottone
   2. Clicca sul install bottone
   3. Apri l'app e conferma che si è scaricata correttamente

   Attenzione

   Se non vedi l'app nella Play Store, assicurati di aver selezionato l'account corretto nella Play Store.

Configurazione della costruzione nativa Capgo (Android)

Ecco, 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.	Yes
Alias del keystore	--keystore-alias <alias>	Nome dell'alias della chiave all'interno della chiave	Yes
Parola di chiave del keystore	--keystore-key-password <password>	Parola per la chiave. Se le password della chiave e dello store corrispondono, puoi fornire solo una.	Guarda la nota sotto
Account servizio Google Play	--keystore-store-password <password>	File di servizio account JSON per gli upload su Play Store.	Guarda la nota sotto
Account di servizio di Google Play	--play-config <path>	File di account servizio JSON per caricamenti su Play Store.	Si

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

Sottotitolo

Se le password chiave e di archiviazione sono identiche, fornisci solo una di esse. --keystore-key-password or --keystore-store-password.

Keystore, password del keystore, password della chiave del keystore, alias del keystore

Se hai seguito i passaggi Istruzioni di costruzione manualeHai già generato il keystore. Se non hai seguito le istruzioni, generalo seguendo le indicazioni.

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. Per favore, tenga presente le seguenti cose:

• Tu NEED NECESSARIO proprietario dell'account del DeveloperAltrimenti, non potrai configurare l'account di servizio.
• Avrai bisogno di creare un nuovo progetto Google Cloud (separato dal tuo account Google Play)

Iniziamo.

1. Iniziare. Google Cloud Console

2. Seleziona il progetto cliccando

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

   Nota

   I screenshot che seguono sono illustrativi - utilizza un nome appropriato per il tuo progetto.

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

4. Premere il pulsante di ricerca e cercare service accounts e cliccare su di esso

5. Premere il pulsante Create service account

6. Compilare il modulo per il servizio e cliccare su Done

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

   

7. Cliccare sul servizio account appena creato Ora dovresti vedere il servizio account appena creato nella lista. Cliccare su di esso.

   Nota

   Copia anche questa email, avrai bisogno di essa più tardi.

8. Clicca sul Keys Pulsante

9. Clicca su Add Key Clicca su Create new key

10. Clicca su JSON Clicca su 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 al servizio account l'accesso al servizio di Store Play API

La nuova account di servizio non ha ancora accesso al Play Store API. Per concederglielo, vai al Console di Play Store.

1. Vai a Console di Google Play
2. Seleziona il profilo del tuo sviluppatore 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 concedere i permessi minimi richiesti:
   • In App permissions, concedere l'accesso alla tua app.
   • In Releases, abilitare 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

Sii 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

Impostazione CI/CD (GitHub Azioni)

Sottosezione intitolata “Configurazione CI/CD (__CAPGO_KEEP_0__ Azioni)” Keystore, password del keystore, password della chiave del keystore, alias del keystore e account di servizio di Google Play, hai già tutto ciò che ti serve per CI/CD. Questa sezione copre solo come passare quei valori come segreti e variabili d'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

Consiglio

I segreti GitHub dovrebbero essere valori a riga singola. tr -d '\n' elimina 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 Capgo API token
APP_ID	La tua Capgo ID dell'app (esempio: com.example.app)
ANDROID_KEYSTORE_FILE	Contenuto di keystore_base64.txt
KEYSTORE_KEY_ALIAS	Alias della chiave di sicurezza dal Cestello, password del cestello, password della chiave del cestello, alias del cestello
KEYSTORE_KEY_PASSWORD	Password della chiave della sicurezza
KEYSTORE_STORE_PASSWORD	Password della sicurezza del magazzino
PLAY_CONFIG_JSON	Contenuto di play_config_base64.txt

Nota

Se le chiavi e le password del magazzino sono le stesse, puoi fornire solo una delle KEYSTORE_KEY_PASSWORD o KEYSTORE_STORE_PASSWORD.

3) Use env vars in your 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 }}

Consiglio

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.

Eseguire la costruzione

Congratulazioni! È pronto a eseguire il suo primo build.

Esegui:

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

Inizia il processo di costruzione 🍾🥂

Ecco come avviare il processo di costruzione.

By default, Android release builds upload to Google Play and can remain inactive until you finish the release in Play Console. If your CI release should submit the Play release automatically, pass --submit-to-store-review con una build 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 rilevamento con release_status: completed se non si imposta un tracciamento. Ciò può andare in live fino al 100% degli utenti. Passa --android-track internal (or alpha / beta) — o impostare PLAY_STORE_TRACK in CI — per mantenere la versione completata su un percorso non di produzione. Utilizza --android-release-status / PLAY_STORE_RELEASE_STATUS Copiarlo nell'area di trasferimento completed.

Questa richiede la stessa configurazione dell'account Google Play come la normale via di caricamento (PLAY_CONFIG_JSON in CI o salvati credenziali Android localmente). --store-release-name viene utilizzato come 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 il rilascio di Play come completed a meno che non si superi --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 Costruzioni Android per pianificare l'automazione CI/CD, connettilo con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD, Capgo Costruzioni Nativa per il flusso di lavoro del prodotto in Capgo Costruzioni Nativa Capgo Integrazioni per il workflow del prodotto nelle Capgo Integrazioni, Integrazione CI/CD per i dettagli di implementazione nella integrazione CI/CD, e GitHub Actions Integration per i dettagli di implementazione in GitHub Integrazione delle azioni.