Guida all'onboarding di CLI

Panoramica rapida

L'onboarding interattivo di Capgo CLI configura i live updates per la tua app Capacitor. Potrai:

1. ✅ Registrare la tua app in Capgo
2. 🔌 Installare e configurare il plugin updater
3. 🚀 Deployare il tuo primo live update
4. 📱 Testare l'update sul tuo dispositivo

Tempo stimato: 10-20 minuti (varia in base alla velocità di rete e ai tempi di build)

Tip

L'onboarding è completamente riprendibile: esci quando vuoi e riprendi più tardi da dove eri rimasto.

Iniziare l'onboarding

Esegui il comando di onboarding con la tua chiave API:

npx @capgo/cli@latest init [APIKEY]

Vedrai il messaggio di benvenuto:

Capgo onboarding 🛫

Cosa succede durante l'onboarding

L'onboarding CLI ti guiderà attraverso 13 passaggi interattivi:

Fase di configurazione (passaggi 1-6):

• Verifica il tuo ambiente di sviluppo (Xcode/Android Studio)
• Aggiungi la tua app a Capgo e crea un canale di produzione
• Installa il @capgo/capacitor-updater plugin
• Inietta il code richiesto nella tua app
• Abilita facoltativamente la crittografia end-to-end
• Scegli una piattaforma per i test (iOS o Android)

Fase di test (passaggi 7-12):

• Compila la tua app e eseguila su un dispositivo/simulatore
• Apporta una modifica code visibile (automatica o manuale)
• Carica il bundle aggiornato su Capgo
• Vedi il live update apparire sul tuo dispositivo in tempo reale

Completamento (Passo 13):

• La tua app è pronta per gli aggiornamenti live! 🎉

Il processo di onboarding in 13 passi

Passo 1: Verifica i prerequisiti

Il CLI verifica il tuo ambiente di sviluppo per assicurarsi che tu abbia installato gli strumenti necessari.

Cosa viene verificato:

• Xcode (solo macOS) - per lo sviluppo iOS
• SDK su Android - per lo sviluppo Android

Possibili esiti:

✅ Trovati entrambi gli ambienti:

✅ Xcode detected - iOS development ready
✅ Android SDK detected - Android development ready

⚠️ Nessun ambiente trovato:

⚠️ Xcode not found
⚠️ Android SDK not found
❌ No development environment detected

📱 To develop mobile apps with Capacitor, you need:
   • For iOS: Xcode (macOS only) - https://developer.apple.com/xcode/
   • For Android: Android Studio - https://developer.android.com/studio

Domande che potrebbero esserti poste:

Attenzione

Se non viene rilevato alcun ambiente di sviluppo, ti verrà chiesto se vuoi continuare. Si consiglia di installare almeno una piattaforma prima di procedere.

Passaggio 2: Aggiungi la tua app

CLI ti farà accedere a Capgo e aggiungerà la tua app al tuo account.

(spinner) Running: npm @capgo/cli@latest login ***
Login Done ✅

❓ Add {appId} in Capgo?

Se l'app ID è già in uso:

CLI suggerirà delle alternative:

❌ App ID "com.example.app" is already taken
💡 Here are some suggestions:
   1. com.example.app2
   2. com.example.app3
   3. com.example.app.new
   4. com.example.app.app

❓ What would you like to do?

Puoi scegliere un suggerimento o inserire un app ID personalizzato.

Nota

Gli app ID devono seguire la notazione reverse domain (es., com.example.myapp)

Passaggio 3: Crea il canale di produzione

I canali ti permettono di gestire diversi flussi di aggiornamento per la tua app.

❓ Create default channel production for {appId} in Capgo?

Tip

Non preoccuparti! Questo serve solo per i test locali durante l'onboarding. Creare un canale “production” non significa che gli aggiornamenti andranno live immediatamente per i clienti. Hai il pieno controllo su quando gli aggiornamenti vengono distribuiti. Seleziona Sì a meno che non hai requisiti specifici per i canali.

Se selezioni Sì:

(spinner) Running: npm @capgo/cli@latest channel add production {appId} --default
Channel add Done ✅  (or "Channel already added ✅")

Verrà creato un canale di produzione e impostato come predefinito. Questa è l'opzione consigliata per la maggior parte degli utenti.

Se selezioni No:

If you change your mind, run it for yourself with: "npm @capgo/cli@latest channel add production {appId} --default"

Dovrai creare e configurare i canali manualmente in seguito. In alternativa, puoi:

• Imposta il canale nel tuo capacitor.config.ts file
• Usa il metodo JavaScript setChannel() per impostare dinamicamente il canale
• Configura i canali in seguito dalla console web di Capgo

Passo 4: Installa il plugin Updater

Il CLI installerà il @capgo/capacitor-updater plugin compatibile con la tua versione Capacitor.

❓ Automatic Install "@capgo/capacitor-updater" dependency in {appId}?

Compatibilità versioni:

• Capacitor 5: Installa @capgo/capacitor-updater v5
• Capacitor 6: Installa @capgo/capacitor-updater v6
• Capacitor 7: Installa @capgo/capacitor-updater v7
• Capacitor 8+: Installa l'ultima versione

Attenzione

Capgo supporta solo Capacitor v5 o versioni successive. Se usi una versione precedente, devi prima aggiornarla.

Opzione instant updates:

Dopo l'installazione, ti verrà chiesto:

❓ Do you want to set instant updates in {appId}?
   Read more: https://capgo.app/docs/live-updates/update-behavior/#applying-updates-immediately

Tip

Cosa sono gli instant updates? Con gli instant updates attivi, la tua app applica gli aggiornamenti immediatamente quando viene messa in background e riaperta. Funziona senza intoppi perché Capgo può distribuire gli aggiornamenti in tutto il mondo in meno di 300ms. Senza questa funzione (modalità standard), gli aggiornamenti vengono scaricati in background e applicati al prossimo riavvio dell'app. Gli instant updates sono ideali per iterare più velocemente in fase di sviluppo e per bug fix critici in produzione.

Se selezioni Sì:

• Gli aggiornamenti saranno configurati per essere applicati immediatamente quando l'app viene messa in background e riaperta
• autoUpdate: 'always' e autoSplashscreen: true verrà aggiunto alla tua config
• @capacitor/splash-screen verrà installato se mancante, con launchAutoHide: false
• Il tuo capacitor.config.ts verrà aggiornato automaticamente
• Aggiornamenti delta rimangono attivi. L'applicazione istantanea (always, atInstall, onLaunch) dovrebbe continuare a usare npx @capgo/cli@latest bundle upload --delta così si scaricano solo i file modificati e l'utente non resta in attesa di uno zip completo

Se selezioni No:

• Gli aggiornamenti useranno il comportamento standard (download in background, applicazione al prossimo riavvio)
• Puoi sempre abilitare gli aggiornamenti istantanei modificando il tuo capacitor.config.ts

Passo 5: Aggiungi l'integrazione Code

CLI inietterà automaticamente il code necessario nel file principale della tua applicazione.

❓ Automatic Add "CapacitorUpdater.notifyAppReady()" code and import in {appId}?

Cosa viene aggiunto:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

Rilevamento del tipo di progetto:

• Nuxt.js: Crea plugins/capacitorUpdater.client.ts
• Altri framework: Aggiunge al tuo file di entry principale

Tip

Se l'iniezione automatica fallisce, puoi aggiungere manualmente code al file principale della tua applicazione:

Per Nuxt.js: Crea plugins/capacitorUpdater.client.ts:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

export default defineNuxtPlugin(() => {
  CapacitorUpdater.notifyAppReady()
})

Per altri framework: Aggiungi al file di ingresso principale (es. main.ts, index.js, App.tsx):

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

Posiziona questo code dopo i tuoi import e prima dell'inizializzazione dell'app. Per maggiori dettagli, consulta la Guida per aggiungere un'app.

Passo 6: Configura la crittografia (opzionale)

La crittografia end-to-end aggiunge un ulteriore livello di sicurezza ai tuoi aggiornamenti.

🔐 End-to-end encryption
   ✅ Use this for: Banking, healthcare, or apps with legal encryption requirements
   ⚠️  Note: Makes debugging harder - skip if you don't need it

❓ Enable end-to-end encryption for {appId} updates?

Nota

La crittografia è disponibile solo per Capacitor v6 e versioni successive.

Se abiliti la crittografia, CLI:

1. Generare le chiavi di crittografia
2. Offrire di sincronizzare la configurazione di Capacitor

Passaggio 7: Seleziona la piattaforma

Scegli su quale piattaforma testare durante l'onboarding.

📱 Platform selection for onboarding
   This is just for testing during onboarding - your app will work on all platforms

❓ Which platform do you want to test with during this onboarding?
   Options:
   - iOS
   - Android

Tip

Questo influisce solo sul processo di onboarding. La tua app finale supporterà tutte le piattaforme.

Passaggio 8: Build del progetto

CLI effettuerà la build della tua app e la sincronizzerà con Capacitor.

❓ Automatic build {appId} with "npm run build"?

Cosa succede:

1. Rileva il tipo di progetto
2. Esegue lo script di build
3. Esegue npx cap sync {platform}

Se manca lo script di build:

Ti verrà chiesto se vuoi saltare il build o aggiungere uno script di build al tuo package.json.

Passaggio 9: Esegui sul dispositivo

Testa la versione iniziale della tua app su un dispositivo o un simulatore.

❓ Run {appId} on {PLATFORM} device now to test the initial version?

Se selezioni Sì:

(spinner) Running: npx cap run {platform}
(device picker appears)
App started ✅
📱 Your app should now be running on your {platform} device with Capgo integrated
🔄 This is your baseline version - we'll create an update next

Passaggio 10: Apporta una modifica di test

Ora è il momento di testare il sistema di update di Capgo effettuando una modifica visibile.

🎯 Now let's test Capgo by making a visible change and deploying an update!

❓ How would you like to test the update?
   Options:
   - Auto: Let Capgo CLI make a visible change for you
   - Manual: I'll make changes myself

Auto mode: CLI modificherà automaticamente i tuoi file per aggiungere un banner di test visibile o una modifica.

Modalità manuale: Fai tu stesso le modifiche (ad es. cambi testo, colori o aggiungi elementi).

Gestione delle versioni:

❓ How do you want to handle the version for this update?
   Options:
   - Auto: Bump patch version ({currentVersion} → {nextVersion})
   - Manual: I'll provide the version number

Build con modifiche:

❓ Build {appId} with changes before uploading?

Tip

Se devi eseguire la build manualmente in un altro terminale, seleziona “No” ed esegui tu la build, poi continua.

Passaggio 11: Carica bundle

Carica il bundle aggiornato della tua app su Capgo.

❓ Upload the updated {appId} bundle (v{version}) to Capgo?

Il CLI esegue:

npx @capgo/cli@latest bundle upload

Tip

Delta update con aggiornamenti istantanei: Se hai abilitato gli instant updates al Passaggio 4, CLI ti chiederà automaticamente se vuoi attivare i delta update. I delta update inviano solo i file modificati tra una versione e l'altra invece dell'intero bundle. Dato che di solito cambiano solo pochi file, i download sono molto più veloci. Seleziona Sì per la migliore esperienza con gli aggiornamenti istantanei.

Prompt per gli aggiornamenti Delta (se la modalità instant apply è attiva):

💡 Instant updates are enabled in your config
   Delta updates send only changed files instead of the full bundle

❓ Enable delta updates for this upload? (Recommended with instant updates)

Attenzione

Per i monorepo, potresti dover fornire percorsi aggiuntivi al tuo package.json e node_modules.

Successo:

✅ Update v{version} uploaded successfully!
🎉 Your updated bundle is now available on Capgo

Passaggio 12: Testa l'aggiornamento sul dispositivo

È ora di vedere l'aggiornamento in azione!

🧪 Time to test the Capgo update system!
📱 Go to your device where the app is running

Per aggiornamenti istantanei:

🔄 IMPORTANT: Background your app (swipe up/press home button) and then reopen it
⏱️  The update should be downloaded and applied automatically

Per aggiornamenti standard:

📱 With standard updates, you will need to:
   1. Background the app (swipe up/press home button) to start download
   2. Wait a few seconds for download to complete
   3. Background and foreground again to see the update

Monitora i logs:

❓ Monitor Capgo logs to verify the update worked?

Se selezioni Sì, vedrai i logs live dal tuo dispositivo che mostrano il processo di aggiornamento.

Passo 13: Completamento

Welcome onboard ✈️!

Congratulazioni! Hai configurato con successo i live updates di Capgo per la tua app.

Cosa hai ottenuto

Dopo aver completato l'onboarding, hai:

✅ App registrata

La tua app è registrata in Capgo con un canale di produzione

✅ Plugin installato

Il plugin Capacitor Updater è installato e configurato

✅ Code integrato

L'integrazione code è stata aggiunta alla tua app

✅ Update testato

Hai distribuito con successo e ricevuto un live update

Workflow quotidiano

Per gli aggiornamenti successivi, usa:

npm run build
npx @capgo/cli@latest bundle upload --channel=production

Per altre opzioni di deployment, vedi Deploy di un Live Update.

Riprendere l'onboarding

Se esci dal processo di onboarding, puoi riprenderlo in qualsiasi momento:

npx @capgo/cli@latest init [APIKEY]

Vedrai:

You have already got to the step {stepNumber}/13 in the previous session
❓ Would you like to continue from where you left off?

Tip

I progressi vengono salvati localmente, quindi puoi uscire in sicurezza e riprendere il processo di onboarding.

Risoluzione problemi

Nessun ambiente di sviluppo

Problema: Né Xcode né Android SDK sono stati rilevati.

Soluzione:

• Per iOS: Installa Xcode (solo macOS)
• Per Android: Installa Android Studio

App ID già in uso

Problema: Il tuo app ID è già registrato.

Soluzione: Scegli una delle alternative suggerite o inserisci un app ID personalizzato in notazione di dominio inverso.

Script di build mancante

Problema: Nessuno script di build trovato in package.json.

Soluzione: Aggiungi uno script di build al tuo package.json:

{
  "scripts": {
    "build": "your-build-command"
  }
}

Iniezione automatica non riuscita

Problema: CLI non può iniettare automaticamente l'integrazione code.

Soluzione: Aggiungi manualmente code al tuo file principale:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

Versione di Capacitor troppo vecchia

Problema: La tua versione di Capacitor è inferiore alla v5.

Soluzione: Aggiorna Capacitor alla v5 o superiore:

• Aggiornamento a Capacitor 5
• Aggiornamento a Capacitor 6
• Aggiornamento a Capacitor 7

Prossimi passi

Ora che hai completato l'onboarding, esplora questi argomenti:

Checklist di setup iniziale

Configura canali, CI e delta upload una volta sola per stabilità a lungo termine

Distribuisci aggiornamenti

Scopri come distribuire aggiornamenti dal dashboard Capgo

Tipi di aggiornamento

Riferimento di tutti i tipi di aggiornamento OTA: tempistica di applicazione, condizioni di ritardo, blocco versioni e distribuzione

Integrazione CI/CD

Automatizza le distribuzioni degli aggiornamenti con CI/CD

Canali

Gestisci più stream di aggiornamenti con i canali

Crittografia

Proteggi i tuoi aggiornamenti con crittografia end-to-end

Comportamento degli aggiornamenti

Personalizza quando e come vengono applicati gli aggiornamenti (diretto, delta, ecc.)

Ottenere aiuto

Se incontri problemi durante l'onboarding:

• Consulta la Guida alla risoluzione dei problemi
• Unisciti al Comunità Discord
• Consulta l' FAQ
• Contatti Supporto

Continua dalla guida di onboarding di CLI

Se stai usando Guida all'onboarding di CLI per pianificare le operazioni della dashboard e di API, collegalo a Panoramica API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi API per i dettagli di implementazione delle chiavi API, Dispositivi per i dettagli di implementazione in Devices, e Bundle per il dettaglio di implementazione in Bundles.