CLI Guida all'onboarding

Panoramica rapida

Capgo CLI fornisce un onboarding interattivo che imposta aggiornamenti in tempo reale per la tua app Capacitor. Potrai:

1. ✅ Registra la tua app in Capgo
2. 🔌 Installa e configura il plug-in di aggiornamento
3. 🚀 Distribuisci il tuo primo aggiornamento live
4. 📱 Prova l’aggiornamento sul tuo dispositivo

Tempo stimato: 10-20 minuti (varia in base alla velocità di Internet e al tempo di creazione)

Suggerimento

L’onboarding è completamente ripristinabile: esci in qualsiasi momento e continua più tardi da dove eri rimasto.

Avvio dell’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

CLI ti guiderà attraverso 13 passaggi interattivi:

Fase di configurazione (passaggi 1-6):

• Controlla il tuo ambiente di sviluppo (Xcode/Android Studio)
• Aggiungi la tua app a Capgo e crea un canale di produzione
• Installa il plugin @capgo/capacitor-updater
• Inserisci il codice richiesto nella tua app
• Facoltativamente abilitare la crittografia end-to-end
• Scegli una piattaforma per il test (iOS o Android)

Fase di test (passaggi 7-12):

• Crea la tua app ed eseguila su un dispositivo/simulatore
• Effettuare un cambio codice visibile (automatico o manuale)
• Carica il pacchetto aggiornato su Capgo
• Guarda l’aggiornamento live apparire sul tuo dispositivo in tempo reale

Completamento (passaggio 13):

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

Il processo di onboarding in 13 passaggi

Passaggio 1: verifica i prerequisiti

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

Che cosa è stato selezionato:

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

Risultati possibili:

✅ 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 desideri continuare. Si consiglia di installare almeno una piattaforma prima di procedere.

Passaggio 2: aggiungi la tua app

CLI ti consentirà di 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’ID della tua app è già in uso:

Il CLI suggerirà 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 ID app personalizzato.

Nota

Gli ID app devono seguire la notazione del dominio inverso (ad esempio, com.example.myapp)

Passaggio 3: crea il canale di produzione

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

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

Suggerimento

Non preoccuparti! Questo è solo per i test locali durante l’onboarding. Creare un canale di “produzione” non significa che i tuoi aggiornamenti verranno immediatamente trasmessi ai clienti. Hai il pieno controllo su quando vengono distribuiti gli aggiornamenti. Seleziona Sì a meno che tu non abbia requisiti di canale specifici.

Se selezioni Sì:

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

Un canale di produzione verrà creato 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 manualmente i canali in un secondo momento. In alternativa, puoi:

• Set the channel in your capacitor.config.ts file
• Utilizza il metodo JavaScript setChannel() per impostare dinamicamente il canale
• Configura i canali in un secondo momento dalla console web Capgo

Step 4: Install Updater Plugin

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

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

Version compatibility:

• Capacitor 5: installa @capgo/capacitor-updater v5
• Capacitor 6: installa @capgo/capacitor-updater v6
• Capacitor 7: installa @capgo/capacitor-updater v7
• Capacitor 8+: Installs latest version

Attenzione

Capgo supporta solo Capacitor v5 e versioni successive. Se utilizzi una versione precedente, dovrai prima eseguire l’aggiornamento.

Instant updates option:

After installation, you’ll be asked:

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

Suggerimento

Che cosa sono gli aggiornamenti istantanei? Con gli aggiornamenti istantanei abilitati, la tua app applica gli aggiornamenti immediatamente quando viene messa in background e riaperta. Funziona perfettamente perché Capgo può distribuire gli aggiornamenti in tutto il mondo in meno di 300 ms. Senza di essa (modalità standard), gli aggiornamenti vengono scaricati in background e applicati al successivo riavvio dell’app. Gli aggiornamenti istantanei sono ottimi per un’iterazione più rapida durante lo sviluppo e la correzione di bug critici in produzione.

Se selezioni Sì:

• Gli aggiornamenti verranno configurati per essere applicati immediatamente quando l’app viene messa in background e riaperta
• directUpdate: 'always' e autoSplashscreen: true verranno aggiunti alla tua configurazione
• Il tuo capacitor.config.ts verrà aggiornato automaticamente
• Gli Aggiornamenti Delta verranno abilitati automaticamente: verranno inviati solo i file modificati tra gli aggiornamenti anziché l’intero pacchetto, rendendo gli aggiornamenti molto più rapidi

Se selezioni No:

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

Step 5: Add Integration Code

CLI inserirà automaticamente il codice richiesto nel file dell’applicazione principale.

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

Cosa viene aggiunto:

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

CapacitorUpdater.notifyAppReady()

Project type detection:

• Nuxt.js: Creates plugins/capacitorUpdater.client.ts
• Altri framework: aggiunge al file di ingresso principale

Suggerimento

Se l’inserimento automatico fallisce, puoi aggiungere manualmente il codice al file dell’applicazione principale:

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

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

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

For other frameworks: Aggiungi al file della voce principale (ad esempio, main.ts, index.js, App.tsx):

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

CapacitorUpdater.notifyAppReady()

Inserisci questo codice dopo le importazioni e prima dell’inizializzazione dell’app. Per ulteriori dettagli, consulta la guida all’aggiunta di un’app.

Step 6: Setup Encryption (Optional)

La crittografia end-to-end aggiunge un ulteriore livello di sicurezza per i 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. Generate encryption keys
2. Proponi di sincronizzare la tua configurazione Capacitor

Step 7: Select Platform

Scegli con 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

Suggerimento

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

Passaggio 8: crea il tuo progetto

CLI creerà la 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 compilazione
3. Esegue npx cap sync {platform}

Se manca lo script di compilazione:

Ti verrà chiesto se desideri saltare la 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: apportare una modifica di prova

Ora è il momento di testare il sistema di aggiornamento di Capgo apportando 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

Modalità automatica: CLI modificherà automaticamente i tuoi file per aggiungere un banner di prova visibile o modificarlo.

Modalità manuale: Apporta le tue modifiche (ad esempio, modifica testo, colori o aggiungi elementi).

Gestione della versione:

❓ 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

Crea con modifiche:

❓ Build {appId} with changes before uploading?

Suggerimento

Se devi creare manualmente in un altro terminale, seleziona “No” e costruisci tu stesso, quindi continua.

Passaggio 11: carica il pacchetto

Carica il tuo app bundle aggiornato su Capgo.

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

Il CLI viene eseguito:

npx @capgo/cli@latest bundle upload

Suggerimento

Aggiornamenti delta con Aggiornamento diretto: Se hai abilitato gli aggiornamenti istantanei (Aggiornamento diretto) nel passaggio 4, CLI ti chiederà automaticamente se desideri abilitare gli aggiornamenti delta. Gli aggiornamenti delta inviano solo i file modificati tra le versioni anziché l’intero pacchetto. Poiché di solito solo pochi file cambiano tra gli aggiornamenti, ciò rende i download molto più veloci. Seleziona Sì per la migliore esperienza con gli aggiornamenti istantanei.

Richiesta di aggiornamenti delta (se l’aggiornamento diretto è abilitato):

💡 Direct Update (instant updates) is enabled in your config
   Delta updates send only changed files instead of the full bundle

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

Attenzione

Per monorepos, potrebbe essere necessario fornire percorsi aggiuntivi a package.json e node_modules.

Successo:

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

Passaggio 12: testare 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 registri:

❓ Monitor Capgo logs to verify the update worked?

Se selezioni Sì, vedrai i registri in tempo reale dal tuo dispositivo che mostrano il processo di aggiornamento.

Passaggio 13: completamento

Welcome onboard ✈️!

Congratulazioni! Hai configurato correttamente gli aggiornamenti in tempo reale Capgo per la tua app.

Cosa hai realizzato

After completing the onboarding, you have:

✅ App Registrata

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

✅Plugin installato

Il plug-in Capacitor Updater è installato e configurato

✅Codice Integrato

Il codice di integrazione viene aggiunto alla tua app

✅ Aggiornamento testato

La distribuzione è stata completata con successo e hai ricevuto un aggiornamento in tempo reale

Flusso di lavoro quotidiano

Per gli aggiornamenti successivi utilizzare:

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

Per ulteriori opzioni di distribuzione, vedere Distribuire un aggiornamento in tempo reale.

Ripresa dell’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?

Suggerimento

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

Risoluzione dei problemi

No Development Environment

Problema: Non viene rilevato né Xcode né Android SDK.

Soluzione:

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

ID app già utilizzato

Problem: Your app ID is already registered.

Soluzione: scegli una delle alternative suggerite o inserisci un ID app personalizzato nella notazione del dominio inverso.

Script di creazione mancante

Problema: nessuno script di compilazione trovato in package.json.

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

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

Auto-Injection Failed

Problema: CLI non può inserire automaticamente il codice di integrazione.

Soluzione: Aggiungi manualmente il codice al file principale:

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

CapacitorUpdater.notifyAppReady()

Capacitor Version Too Old

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

Soluzione: aggiorna Capacitor alla v5 o successiva:

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

Passaggi successivi

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

Distribuire gli aggiornamenti

Scopri come distribuire gli aggiornamenti dal dashboard Capgo

Tipi di aggiornamento

Riferimento a tutti i tipi di aggiornamento OTA: applica tempistiche, condizioni di ritardo, blocco della versione e consegna

Integrazione CI/CD

Automatizza le distribuzioni degli aggiornamenti con CI/CD

Channels

Gestisci più flussi di aggiornamento con i canali

Encryption

Secure your updates with end-to-end encryption

Aggiorna comportamento

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

Ottenere aiuto

If you encounter issues during onboarding:

• Consulta la Guida alla risoluzione dei problemi
• Join the Discord Community
• Consulta le FAQ
• Contact Support