Inizia

Inizia con Capgo Cloud Build e crea la tua prima build nativa iOS o Android in pochi minuti.

Cosa ti Serve

Prima di iniziare, assicurati di avere:

• Un'app Capacitor che si costruisce con successo localmente
• Node.js 20 o superiore installato
• Un account Capgo con una sottoscrizione attiva
• La tua app già registrata in Capgo (esegui bunx @capgo/cli@latest app add se non è così)
• Credenziali di costruzione configurate (certificati, archivi delle chiavi) - vedi di seguito

Prima della Prima Costruzione

⚠️ Configura le Credenziali Prima

Richiesto prima di costruire: Devi configurare le tue credenziali di costruzione (certificati per iOS, keystores per Android).

Configura Credenziali →

Avvio Rapido

1. Configura Credenziali di Costruzione

   Prima di poter costruire, devi salvare le tue credenziali localmente:

   Per iOS:

   bunx @capgo/cli@latest build credentials save \
     --platform ios \
     --certificate ./cert.p12 \
     --p12-password "password" \
     --provisioning-profile ./profile.mobileprovision \
     --apple-key ./AuthKey.p8 \
     --apple-key-id "KEY123" \
     --apple-issuer-id "issuer-uuid" \
     --apple-team-id "team-id"

   Per Android:

   bunx @capgo/cli@latest build credentials save \
     --platform android \
     --keystore ./release.keystore \
     --keystore-alias "my-key" \
     --keystore-key-password "key-pass" \
     --keystore-store-password "store-pass"

   Vedi il guida completa per le credenziali per i dettagli.

2. Verifica la costruzione locale

   In primo luogo, assicurati che la tua app si costruisca localmente senza errori:

   # Build your web assets
   bun run build
   
   # Sync with Capacitor
   bunx cap sync
   
   # Test local build (optional but recommended)
   bunx cap open ios    # For iOS
   bunx cap open android # For Android

3. Autenticati con Capgo

   Imposta la tua chiave Capgo API (se non è già configurata):

   bunx @capgo/cli@latest login

   Imposta la variabile di ambiente:

   export CAPGO_TOKEN=your_api_key_here

4. Esegui la tua prima compilazione

   Inizia con una compilazione di debug per Android (più veloce per testare):

   bunx @capgo/cli@latest build com.example.app \
     --platform android \
     --build-mode debug

   Vedrai i log in tempo reale mentre la tua compilazione procede:

   ✔ Creating build job...
   ✔ Uploading project (15.2 MB)...
   ✔ Build started
   
   📝 Build logs:
   → Installing dependencies...
   → Running Gradle build...
   → Signing APK...
   ✔ Build succeeded in 3m 42s

5. Controlla lo stato della compilazione

   Il CLI effettuerà una richiesta periodica e visualizzerà lo stato della compilazione. Una volta completata, vedrai:

   • Tempo di compilazione
   • Stato di successo/fallimento
   • L'app è stata inviata a App Store/Play Store (se configurati i credenziali)

Capire il processo di costruzione

Quando esegui il comando di costruzione, ecco cosa accade:

flowchart LR
    A[Your Machine] -->|1. Zip Project| B[Local Temp]
    B -->|2. Upload| C[Capgo Cloud]
    C -->|3. Build| D[Mac Mini Silicon M4 Build Server]
    D -->|4. Logs Stream| A
    D -->|5. Cleanup| E[Auto Delete]

1. Preparazione locale - Il tuo progetto viene compresso (escluso node_modules e file dot)
2. Caricamento - Il file compresso viene caricato nel cloud storage sicuro (Cloudflare R2)
3. Esecuzione della costruzione - La tua app si costruisce su infrastrutture dedicate
4. Log Streaming - I log in tempo reale scorrono nel tuo terminale tramite Eventi Server-Sent
5. Pulizia Automatica - Gli artefatti di costruzione vengono eliminati (Android: istantaneo, iOS: 24 ore)

Infrastruttura di Costruzione

L'esecuzione di costruzione si esegue su Mac Mini Silicon M4 dedicate:

• CPU M4 a 10 core (4 core di prestazione, 6 core di efficienza)
• GPU a 10 core
• Motor di rete a 16 core
• 16 GB di RAM
• macOS Tahoe 26.2

L'immagine di costruzione supporta Xcode 26.2, Android Studio 2025 e .NET 9/.NET 10 SDK carichi di lavoro per pipeline di costruzione nativa.

Il tuo primo build di produzione

Una volta verificato che il processo funziona, crea un build di produzione:

Android

bunx @capgo/cli@latest build com.example.app \
  --platform android \
  --build-mode release

Avrai bisogno di configurare i credenziali di firma prima. Vedi Configurazione di costruzione di Android.

iOS

bunx @capgo/cli@latest build com.example.app \
  --platform ios \
  --build-mode release

Le costruzioni iOS richiedono certificati di firma e profili di provisioning. Vedi Configurazione di costruzione iOS.

Cosa si costruisce

Capgo Costruisci solo l'upload dei file minimi necessari per compilare la tua app nativa. La tua fonte completa code non lascia mai la tua macchina.

Cosa si carica

Incluso	Descrizione
ios/ o android/	La cartella della piattaforma nativa che stai costruendo
package.json, package-lock.json	Manifesto di dipendenza
capacitor.config.*	Capacitor configurazione protetta
resources/	Icone dell'app, schermate di benvenuto
Plugin nativo code	Solo il ios/ o android/ sottocartella di ogni plugin Capacitor

Cosa NON viene caricato

Escluso	Perché
node_modules/ (la maggior parte di esso)	Solo il plugin nativo code viene incluso, non le dipendenze JS
src/	La tua fonte web code rimane locale
dist/, www/, build/ (livello radice)	Già sincronizzato nel folder nativo tramite cap sync
.git/	Storia dei controlli di versione
.gradle/, .idea/, .swiftpm/	Cache di compilazione e impostazioni dell'IDE
.envSegreti	Nessuna carica

Nota

I tuoi asset web costruiti (JS, CSS, HTML) sono caricati - ma come parte della cartella nativa. Quando esegui bunx cap sync, il tuo build web viene copiato in ios/App/App/public/ o android/app/src/main/assets/public/. Ecco perché è necessario eseguire cap sync prima di costruire.

Le Tue Responsabilità

Prima di eseguire bunx @capgo/cli@latest build:

1. Costruisci i tuoi asset web - Esegui bun run build (o il comando di compilazione del tuo framework)
2. Sincronizza con nativo - Esegui bunx cap sync per copiare gli asset web nel progetto nativo
3. Comitisci le dipendenze - Assicurati che tutti i plugin nativi siano in package.json

Cosa Capgo Build Gestisce

• Compilazione nativa iOS (Xcode, Fastlane)
• Compilazione nativa Android (Gradle)
• Code firma con le tue credenziali
• Sottomissione della store (se configurato)

Tempo di costruzione e Costi

Il tempo di costruzione viene misurato dal momento di inizio alla fine:

• Android: Di solito 3-5 minuti
• iOS: Di solito 5-10 minuti
• Infrastruttura: Mac Mini Silicon M4 che eseguono macOS Tahoe 26.2

Paga solo per il tempo di costruzione effettivamente utilizzato. Nessuna tariffa nascosta.

Utilizzo comune

Integrazione CI/CD

Aggiungi al tuo GitHub Actions workflow:

- uses: oven-sh/setup-bun@v2
  with:
    bun-version: latest

- name: Build native app
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
  run: |
    bun run build
    bunx cap sync
    bunx @capgo/cli@latest build ${{ secrets.APP_ID }} \
      --platform both \
      --build-mode release

Sviluppo locale

Testa le build localmente prima di commettere:

# Quick debug build for testing
bun run build && bunx cap sync
bunx @capgo/cli@latest build com.example.app \
  --platform android \
  --build-mode debug

Build multi-piattaforma

Esegui due comandi per creare build per entrambe le piattaforme:

# iOS build
bunx @capgo/cli@latest build com.example.app \
  --platform ios \
  --build-mode release

# Android build
bunx @capgo/cli@latest build com.example.app \
  --platform android \
  --build-mode release

In CI/CD, puoi eseguire questi comandi in job paralleli per build più veloci.

Passaggi successivi

Ora che hai creato il tuo primo build:

• Configura build per iOS - Configura certificati e profili
• Configura build per Android - Configura keystore e Play Store
• Risoluzione dei Problemi - Problemi comuni e soluzioni
• CLI Riferimento - Documentazione completa della riga di comando

Aiuto?

• Controlla il guida di risoluzione dei problemi
• Unisciti alla nostra comunità Discord
• Supporto via email a supporto@capgo.app