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. 📱 Verifica l'aggiornamento sul tuo dispositivo

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

Suggerimento

L'onboarding è completamente riprendibile - esce in qualsiasi momento e continua più tardi da dove hai lasciato.

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

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 il code richiesto nel tuo app
• Aggiungi optionalmente la crittografia end-to-end
• Scegli una piattaforma per il testing (iOS o Android)

Fase di Test (Passaggi 7-12):

• Costruisci l'app e eseguila su un dispositivo/simulatore
• Apporta una modifica visibile (code automatica o manuale)
• Carica l'aggiornamento del bundle su Capgo
• Vedi l'aggiornamento in tempo reale apparire sul tuo dispositivo

Completamento (Passaggio 13):

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

Il Processo di Onboarding in 13 Passaggi

Passo 1: Verifica le Precondizioni

CLI controlla il tuo ambiente di sviluppo per assicurarsi che tu abbia le necessarie strumentazioni installate.

Cosa è stato verificato:

• 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, verrà chiesto se si desidera continuare. È consigliabile installare almeno una piattaforma prima di procedere.

Passo 2: Aggiungi la tua App

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 l'ID dell'app è già stato preso:

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 dell'app personalizzato.

Nota

I identificativi dell'applicazione 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 il testing locale durante l'acquisizione. La creazione di un 'canale di produzione' non significa che gli aggiornamenti saranno pubblicati immediatamente ai clienti. Hai il pieno controllo sul momento in cui gli aggiornamenti vengono distribuiti. Seleziona Sì a meno che non hai specifiche richieste 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à creata e impostata come predefinita una canale di produzione. 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. 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 __CAPGO_KEEP_0__ console web
• Configure channels later from the Capgo web console

Sezione intitolata “Passo 4: Installa Plugin di Aggiornamento”

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

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

Compatibilità di 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 v5. 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? With le aggiornamenti abilitati in tempo reale, la tua app applica gli aggiornamenti immediatamente quando è in background e viene riaperta. Funziona in modo fluido perché Capgo può distribuire gli aggiornamenti in tutto il mondo in meno di 300ms. Senza di esso (modalità standard), gli aggiornamenti scaricano in background e si applicano alla prossima riavvio dell'app. Gli aggiornamenti in tempo reale sono ottimi per un'iterazione più veloce durante lo sviluppo e le correzioni critiche 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 verranno aggiunti alla tua configurazione
• La tua capacitor.config.ts verrà aggiornata automaticamente
• Gli aggiornamenti delta verranno 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)
• Potrai sempre abilitare gli aggiornamenti in tempo reale in un secondo momento modificando la tua configurazione 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

Se l'iniezione automatica fallisce

Se l'iniezione automatica fallisce, puoi aggiungere manualmente il __CAPGO_KEEP_0__ al tuo file di applicazione principale:, you can add the code manually to your main application file:

Crea Copia nel portapenne plugins/capacitorUpdater.client.ts:

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

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

Aggiungi al tuo file di ingresso principale (ad esempio, Copia nel portapenne main.ts, index.js, App.tsx):

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

CapacitorUpdater.notifyAppReady()

Place this code after your imports and before your app initialization. For more details, see the Copi nel portapenne.

Aggiungi al tuo file di ingresso principale (ad esempio,

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 le chiavi di crittografia
2. Offre di sincronizzare la configurazione del tuo Capacitor

Passaggio 7: Seleziona piattaforma

Scegli la piattaforma con cui testare durante l'accesso.

📱 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

Consiglio

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

Passaggio 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 costruzione manca:

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

Passo 9: Esegui su dispositivo

Testa la versione iniziale dell'app sul tuo 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 modificare.

Modalità manuale: Tu fai le modifiche da te (ad esempio, cambiare testo, colori o aggiungere 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'altra finestra del terminale, seleziona “No” e costruisci da solo, poi continua.

Passo 11: Carica Bundle

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

Prompt per aggiornamenti Delta (se abilitato il modo di applicazione istantanea):

💡 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.

Risultato:

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

Passaggio 12: Testa l'aggiornamento sul dispositivo

È arrivato 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

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 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.

Passaggio 13: Completamento

Welcome onboard ✈️!

Congratulazioni! Hai avuto successo nel configurare Capgo gli aggiornamenti in tempo reale per il tuo 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

✅ Aggiornamento Testato

Hai avuto successo nella distribuzione e hai ricevuto un aggiornamento live

Flusso di lavoro quotidiano

Per aggiornamenti successivi, utilizza:

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

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

Ripresa della procedura di 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?

Suggerimento

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

Risoluzione dei problemi

Nessun ambiente di sviluppo

Problema: Nessuno dei seguenti è stato trovato: Xcode o Android SDK.

Soluzione:

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

ID App già preso

Problema: Il tuo ID app è già registrato.

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

Manca lo Script di Costruzione

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ò automaticamente iniettare 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 una versione superiore:

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

Passaggi successivi

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

Elenco di configurazione una volta

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

Distribuzione Aggiornamenti

Impara a distribuire gli aggiornamenti dalla dashboard di Capgo

Tipi di Aggiornamento

Riferimento a 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

Proteggere le tue aggiornamenti con crittografia end-to-end

Comportamento dell'aggiornamento

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

Ottenere Aiuto

In caso di problemi durante l'accesso:

• Controlla il Guida di Risoluzione dei Problemi
• Unisciti ai Comunità di Discord
• Rivista il FAQ
• Contattaci Supporto

Continua da CLI Guida di Onboarding

Se stai utilizzando CLI Guida di Onboarding per pianificare il dashboard e le operazioni di API , 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 in Dispositivi, e Bundle per i dettagli di implementazione in Bundle.