CLI Guida di onboarding

Panoramica rapida

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

1. ✅ Registrare la tua app su Capgo
2. 🔌 Installare e configurare il plugin di aggiornamento
3. 🚀 Distribuire il tuo primo aggiornamento in tempo reale
4. 📱 Testare l'aggiornamento sul tuo dispositivo

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

Tip

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

Avvio dell'Onboarding

Esegui il comando di onboarding con la tua API chiave:

npx @capgo/cli@latest init [APIKEY]

Vedrai il messaggio di benvenuto:

Capgo onboarding 🛫

Cosa Succede Durante l'Onboarding

The CLI vi 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 il code richiesto nel tuo app
• Facoltativamente abilita la crittografia end-to-end
• Scegli una piattaforma per le prove (iOS o Android)

Fase di testing (Passaggi 7-12):

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

Completo (Passo 13):

• Il tuo app è pronto per gli aggiornamenti in tempo reale! 🎉

Il processo di avvio di 13 passaggi

Passo 1: Verifica le condizioni preliminari

Il CLI controlla il tuo ambiente di sviluppo per assicurarsi di avere le necessarie strumentazioni installate.

Ciò che viene verificato:

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

Possibili esiti:

✅ Sono stati trovati entrambi gli ambienti:

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

⚠️ Non è stato trovato alcun ambiente:

⚠️ 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?

Puoi scegliere una proposta o inserire 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 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 la prova locale durante l'accesso. La creazione di un canale "di produzione" non significa che gli aggiornamenti saranno pubblicati immediatamente ai clienti. Hai il controllo completo sul momento in cui gli aggiornamenti vengono distribuiti. Seleziona Sì a meno che non hai specifiche esigenze per i canali.

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 i canali manualmente in un secondo momento. Alternativamente, puoi:

• Imposta il canale nel tuo capacitor.config.ts file
• Utilizza il metodo JavaScript per impostare dinamicamente il canale setChannel() Configura i canali in un secondo momento dal portale web __CAPGO_KEEP_0__
• Configure channels later from the Capgo web console

Sezione intitolata “Passo 4: Installa Plugin di Aggiornamento”

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

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

Compatibilità della versione:

• 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 a partire dalla versione 5. Se stai utilizzando una versione più vecchia, dovrai aggiornare 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

Suggerimento

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 saranno aggiunte alla tua configurazione autoSplashscreen: true sarà aggiornata automaticamente
• Il tuo capacitor.config.ts sarà aggiornato automaticamente
• Aggiornamenti Delta saranno abilitati automaticamente - ciò invia solo i file che sono stati modificati tra gli aggiornamenti al posto del bundle completo, rendendo gli aggiornamenti molto più veloci

Se selezioni No:

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

Passo 5: Aggiungi Integrazione Code

Il 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 del tipo di progetto:

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

Suggerimento

Se la 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: Aggiungi al tuo file di ingresso principale (ad esempio 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'app. Per ulteriori dettagli, consulta la Guida all'aggiunta di 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 Capacitor

Passo 7: Seleziona piattaforma

Scegliere la piattaforma da utilizzare durante l'acquisizione.

📱 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

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

Passo 8: Costruisci il tuo progetto.

Il CLI costruirà la tua app e la 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}

Se lo script di build manca:

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

Passo 9: Esegui su dispositivo

Testa la versione iniziale dell'applicazione 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

Modalità automatica: Il CLI modificherà automaticamente i tuoi file per aggiungere un banner di test visibile o cambiare.

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

Costruisci con modifiche:

❓ Build {appId} with changes before uploading?

Suggerimento

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

Passo 11: Carica Bundle

Carica il tuo bundle di app aggiornato su Capgo.

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

Il CLI esegue:

npx @capgo/cli@latest bundle upload

Suggerimento

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 pacchetto. Poiché di solito cambiano solo pochi file tra gli aggiornamenti, ciò rende i download molto più veloci. Seleziona Sì per l'esperienza migliore con gli aggiornamenti istantanei.

Prompt degli aggiornamenti delta (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 al tuo package.json e node_modules.

Successo:

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

Passo 12: Test Update sul Dispositivo

Il momento 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

For 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 log:

❓ Monitor Capgo logs to verify the update worked?

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

Passo 13: Completamento

Welcome onboard ✈️!

Congratulazioni! Hai avviato con successo Capgo gli aggiornamenti live per il tuo app.

Ciò che hai raggiunto

Dopo aver completato l'onboarding, hai:

✅ App Registrata

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

✅ Plugin Installato

Il plugin di aggiornamento Capacitor è installato e configurato

✅ Code Integrato

L'integrazione code è stata aggiunta alla tua app

✅ Aggiornamento Testato

Hai eseguito con successo il deployment e ricevuto un aggiornamento live

Flusso di Lavoro Giornaliero

Per aggiornamenti successivi, utilizza:

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

Per ulteriori opzioni di distribuzione, vedi Distribuisci un Aggiornamento in Tempo Reale.

Ripresa della Registrazione

Se esiti dal processo di registrazione, 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 è salvato localmente, quindi puoi uscire e riprendere il processo di onboarding in qualsiasi momento.

Troubleshooting

No Development Environment

Problema: Nessuna versione di Xcode né di Android SDK è stata rilevata.

Soluzione:

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

L'ID dell'app è già stato preso

Problema: L'ID dell'app è già registrato.

Soluzione: Scegliere una delle alternative suggerite o inserire un ID dell'app personalizzato in notazione dominio inverso.

Manca lo script di build

Problema: Non è stato trovato alcun script di costruzione 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 code manualmente 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

Passaggi successivi

Now that you’ve completed onboarding, explore these topics:

Distribuisci Aggiornamenti

Scopri come distribuire gli aggiornamenti dalla dashboard 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 tue distribuzioni di aggiornamento con CI/CD

Canali

Gestisci più flussi di aggiornamento con i canali

Crittografia

Assicura la sicurezza degli aggiornamenti con crittografia end-to-end

Comportamento dell'Aggiornamento

Personalizza quando e come vengono applicate le aggiornamenti (diretto, delta, ecc.)

Aiuto

In caso di problemi durante l'accesso:

• Controlla il Guida di Risorsa per la Risoluzione dei Problemi
• Unisciti alla Comunità Discord
• Recensisci il FAQ
• Contattare Supporto

Continua da CLI Guida di Onboarding

Se stai utilizzando CLI Guida di Onboarding per pianificare il dashboard e le API operazioni, connettilo con API Panoramica 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 Buste per i dettagli di implementazione nelle Buste.