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 in Capgo
2. 🔌 Installare e configurare il plugin di aggiornamento
3. 🚀 Distribuire il tuo primo aggiornamento in tempo reale
4. 📱 Testa l'aggiornamento sul tuo dispositivo

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

Suggerimento

L'onboarding è completamente riprendibile - esci 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 la Registrazione

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

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

✅ Trovati entrambi gli ambienti:

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

⚠️ Non 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 fatto:

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

Il CLI ti loggerà nel 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:

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

Nota

Gli ID 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 controllo completo sulle date di distribuzione degli aggiornamenti. 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"

Avrai bisogno di 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 dalla console web __CAPGO_KEEP_0__
• 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à 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 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 l'aggiornamento istantaneo abilitato, la tua app applica gli aggiornamenti immediatamente quando è in background e viene riaperta. Funziona in modo senza problemi 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 istantanei sono ottimi per un'iterazione più veloce durante lo sviluppo e le correzioni critiche di bug in produzione.

Se selezioni Sì:

• Gli aggiornamenti saranno configurati per applicarsi immediatamente quando l'app è in background e viene riaperta
• directUpdate: '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 istantanei in seguito 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 tipo 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 Tip.

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

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. Offre la sincronizzazione della configurazione del Capacitor

Passo 7: Seleziona piattaforma

Scegli la piattaforma da 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

Suggerimento

Questo influisce solo sul processo di avvio. La tua app finale supporta 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 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

Verifica 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 l'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: 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'altra finestra di comando, 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 Direct Update: Se hai abilitato gli aggiornamenti istantanei (Direct Update) 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 invece del bundle completo. 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.

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

Passo 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

Monitorare 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 nell'installare le Capgo aggiornamenti live per il tuo app.

Cosa hai raggiunto

Dopo aver completato l'assistenza all'utente, 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 eseguito con successo la distribuzione e 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 avvio

Se esiti dal processo di avvio, 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 (disponibile solo su macOS)
• Per Android: Installa Android Studio

ID App già utilizzato

Problema: Il tuo ID app è già registrato.

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

Manca lo Script di Costruzione

Problema: Non è stato trovato lo 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 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

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

Distribuzione Aggiornamenti

Impara a distribuire gli aggiornamenti dalla dashboard di Capgo

Tipi Aggiornamenti

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

Integrazione CI/CD

Automatizza le tue distribuzioni di aggiornamenti con CI/CD

Canali

Gestisci più flussi di aggiornamenti 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.)

Aiuto

Se incontri problemi durante l'accesso:

• Controlla il Guida di risoluzione dei problemi
• Unisciti alla Community Discord
• Rivista il Domande Frequenti
• Contattaci Supporto