CLI Guida di Onboarding

Panoramica rapida

Il Capgo CLI offre un'esperienza di onboarding interattiva che configura gli aggiornamenti in tempo reale per la tua Capacitor app.

1. ✅ Registra il tuo app in Capgo
2. 🔌 Installa e configura il plugin di aggiornamento
3. 🚀 Distribuisci il tuo primo live update
4. 📱 Testa l'aggiornamento sul tuo dispositivo

Tempo stimato: 10-20 minuti (varia in base alla tua velocità di rete e tempo di compilazione)

Tip

L'onboarding è completamente riprendibile - esce quando vuoi e continua più tardi dal punto in cui ti sei fermato.

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

Il CLI guiderà attraverso 13 passaggi interattivi:

Fase di configurazione (Passaggi 1-6):

• Verifica il tuo ambiente di sviluppo (Xcode/Android Studio)
• Aggiungi il tuo app a Capgo e crea un canale di produzione
• Installa il @capgo/capacitor-updater plugin
• Inietta i code richiesti nel tuo app
• Opzionalmente abilita la crittografia end-to-end
• Scegli una piattaforma per il testing (iOS o Android)

Fase di testing (Passaggi 7-12):

• Costruisci il tuo app e eseguilo su un dispositivo/simulatore
• Effettua un cambiamento code visibile (automatico o manuale)
• Carica il bundle aggiornato su Capgo
• Vedi il live update apparire sul tuo dispositivo in tempo reale

Completo (Passo 13):

• La tua app è pronta per le aggiornamenti in tempo reale!

Il processo di onboarding in 13 passaggi

Passo 1: Verifica le condizioni preliminari

Il CLI controlla il tuo ambiente di sviluppo per assicurarsi di avere gli strumenti necessari installati.

Cosa è stato verificato:

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

Possibili esiti:

✅ Entrambi gli ambienti trovati:

✅ 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 a cui potresti essere chieste:

Attenzione

Se non viene rilevato alcun ambiente di sviluppo, ti verrà chiesto se desideri continuare. È consigliabile installare almeno una piattaforma prima di procedere.

Passo 2: Aggiungi la tua App

Il CLI ti loggerà su Capgo e aggiungerà la tua app al tuo account.

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

❓ Add {appId} in Capgo?

Se il tuo ID app è già stato preso:

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?

Seleziona una proposta o inserisci un ID app personalizzato.

Nota

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

Passo 3: Crea canale di produzione

i canali consentono di gestire diversi flussi di aggiornamento per il tuo app.

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

Consiglio

Non preoccuparti! Questo è solo per test locali durante l'onboarding. La creazione di un canale "di produzione" non significa che gli aggiornamenti saranno pubblicati immediatamente ai clienti. Hai il controllo completo sulle date di distribuzione degli aggiornamenti. Seleziona Sì a meno che non hai specifiche richieste per il canale.

Selezionare 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. Questo è l'opzione consigliata per la maggior parte degli utenti.

Selezionare 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 un secondo momento. Alternativamente, puoi:

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

Sezione intitolata “Passo 4: Installa Plugin di Aggiornamento”

plugin compatibile con la tua versione di CLI @capgo/capacitor-updater compatibile con la tua versione di Capacitor.

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

Compatibilità della versione:

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

Attenzione

Capgo supporta solo Capacitor v5 e successive versioni. Se stai utilizzando una versione più vecchia, dovrai aggiornarla prima.

Opzione di aggiornamento istantaneo:

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 aggiornamenti istantanei? Con gli aggiornamenti istantanei abilitati, la tua app applica gli aggiornamenti immediatamente quando è in background e viene riaperta. Funziona in modo trasparente perché Capgo può distribuire gli aggiornamenti in tutto il mondo in meno di 300ms. Senza di esso (modalità standard), gli aggiornamenti si scaricano in background e si applicano alla prossima riavvio dell'app. Gli aggiornamenti istantanei sono ottimi per una maggiore iterazione durante lo sviluppo e per i bug critici in produzione.

Se selezioni Sì:

• Gli aggiornamenti saranno configurati per applicarsi immediatamente quando l'app è in background e viene riaperta
• autoUpdate: 'always' e autoSplashscreen: true verrà aggiunto alla tua configurazione
• @capacitor/splash-screen verrà installato se mancante, con launchAutoHide: false
• il tuo capacitor.config.ts verrà aggiornato automaticamente
• Aggiornamenti delta Resta abilitato. Applica subito (always, atInstall, onLaunchverrà aggiornato automaticamente se presente npx @capgo/cli@latest bundle upload --delta Solo i file modificati vengono scaricati e l'utente non è lasciato in attesa di un file zip completo

Selezionare No:

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

Passo 5: Aggiungi integrazione Code

La CLI inietterà automaticamente i code richiesti nel tuo file di applicazione principale.

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

Cosa viene aggiunto:

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

CapacitorUpdater.notifyAppReady()

Rilevamento tipo progetto:

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

Consiglio

Se l'iniezione automatica fallisce, puoi aggiungere manualmente il code al tuo file di applicazione principale:

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

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

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

Per altri framework: Add to your main entry file (e.g., main.ts, index.js, App.tsx):

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

CapacitorUpdater.notifyAppReady()

Colloca questo code dopo le tue importazioni e prima dell'inizializzazione dell'applicazione. Per ulteriori dettagli, consulta la guida Aggiungi un'app.

Passo 6: Configura la crittografia (facoltativo)

La crittografia end-to-end aggiunge un ulteriore layer di sicurezza per le tue 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, il CLI farà:

1. Genera chiavi di crittografia
2. Offrirà di sincronizzare la configurazione del tuo Capacitor

Passo 7: Scegli la piattaforma

Sezione intitolata “Passo 7: Scegli la piattaforma”

📱 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

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

Passo 8: Costruisci il tuo progetto

Il CLI costruirà il tuo app e sincronizzerà con Capacitor.

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

Cosa succede:

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

If lo scripto di build manca:

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

Passo 9: Esegui su dispositivo

Testa la versione iniziale della tua app su un dispositivo o 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

Passo 10: Fai una Modifica di Test

Ora è il momento di testare il sistema di aggiornamento di Capgo facendo 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: La CLI modificherà automaticamente i tuoi file per aggiungere un banner di test visibile o modificare.

Modalità manuale: Tu fai le modifiche da solo (ad esempio, cambia il testo, i 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

Costruisci con modifiche:

❓ Build {appId} with changes before uploading?

Tip

Se hai bisogno di costruire manualmente in un'altra finestra di terminale, seleziona “No” e costruisci da solo, poi continua.

Passo 11: Carica Bundle

Carica il bundle dell'app aggiornato in Capgo.

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

CLI in esecuzione:

npx @capgo/cli@latest bundle upload

Tip

Aggiornamenti delta con aggiornamenti istantanei: Se hai abilitato gli aggiornamenti istantanei nel Passo 4, il CLI chiederà automaticamente se desideri abilitare gli aggiornamenti delta. Gli aggiornamenti delta inviano solo i file che sono stati modificati tra le versioni anziché l'intero bundle. Poiché di solito cambiano solo pochi file tra gli aggiornamenti, ciò rende i download molto più veloci. Seleziona Sì per l'esperienza migliore con aggiornamenti istantanei.

Delta aggiornamenti promemoria (se un modello di applicazione istantanea è abilitato):

💡 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 monorepos, potresti dover fornire percorsi aggiuntivi ai tuoi 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

Monitorare i log:

❓ Monitor Capgo logs to verify the update worked?

Se selezioni SìVedrai i log in tempo reale del tuo dispositivo che mostrano il processo di aggiornamento.

Passo 13: Completamento

Welcome onboard ✈️!

Congratulazioni! Hai avuto successo nell'installare Capgo aggiornamenti in tempo reale per la tua app.

Cosa hai ottenuto

Dopo aver completato l'accesso, 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

✅ Aggiornamento testato

Hai avuto successo nella distribuzione e hai ricevuto un live update

Flusso di lavoro quotidiano

Per le successive aggiornamenti, utilizza:

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

Per ulteriori opzioni di distribuzione, vedi Distribuisci un Live Update.

Riprendere l'Onboarding

Se esiti dal processo di onboarding, puoi riprendere 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

Il progresso viene salvato localmente, quindi puoi uscire e riprendere il processo di onboarding in tutta sicurezza.

Troubleshooting

Sezione intitolata “Risoluzione dei problemi”

Problem: Nessun ambiente Xcode né Android SDK è stato rilevato.

Soluzione:

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

ID App già registrato

Problema: Il tuo ID app è già registrato.

Soluzione: Scegliere uno degli alternative suggerite o inserire un ID di app personalizzato in notazione dominio inverso.

Manca lo Script di Costruzione

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

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

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

Fallito l'Iniezione Automatica

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()

Capacitor Versione Troppo Vecchia

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

Soluzione: Aggiorna Capacitor a v5 o superiore:

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

Next Steps

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

Elenco di configurazione una volta per tutte

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

Distribuisci Aggiornamenti

Impara a distribuire gli aggiornamenti dalla dashboard di Capgo

Tipi di Aggiornamento

Riferimento di tutti i tipi di aggiornamento OTA: applicazione di timing, condizioni di ritardo, blocco di versione e consegna

Integrazione CI/CD

Automatizza le distribuzioni degli aggiornamenti con CI/CD

Canali

Gestisci più flussi di aggiornamento con i canali

Crittografia

Proteggere gli aggiornamenti con crittografia end-to-end

Comportamento dell'aggiornamento

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

Ottenere Aiuto

Se incontri problemi durante l'onboarding:

• Controlla il Guida di Risoluzione dei Problemi
• Unisciti al Comunità Discord
• Valuta il FAQ
• Contattaci Sostegno

Continua con il Guida di Avvio di CLI

Se stai utilizzando per pianificare il dashboard e le operazioni di CLI per pianificare il dashboard e le operazioni API, connettilo Panoramica di API Per i dettagli di implementazione in API Panoramica. Introduzione per i dettagli di implementazione in Introduzione, API Chiavi per i dettagli di implementazione in API Chiavi, Dispositivi per i dettagli di implementazione nei dispositivi, e Bundles per i dettagli di implementazione nei Bundle.