CLI Guida di Registrazione

Panoramica rapida

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

1. ✅ Registra la tua app in Capgo
2. 🔌 Installa e configura il plugin di aggiornamento
3. 🚀 Distribuisci il tuo primo aggiornamento in tempo reale
4. 📱 Testa 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 ripristinabile - esce in qualsiasi momento e continua più tardi dal punto in cui ti sei fermato.

Avvia l'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

La CLI guiderà attraverso 13 passaggi interattivi:

Fase di configurazione (Passaggi 1-6):

• Verifica il tuo ambiente di sviluppo (Xcode/Android Studio)
• Aggiungi la tua app a Capgo e crea un canale di produzione
• Installa il @capgo/capacitor-updater plugin
• Inserisci il code richiesto nel tuo app
• Abilita optionalmente 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
• Fai un cambiamento visibile code (automatico o manuale)
• Carica il bundle aggiornato su Capgo
• Vedi l'aggiornamento live apparire sul tuo dispositivo in tempo reale

Completa (Passaggio 13):

• Il tuo app è pronto per gli aggiornamenti live! 🎉

Il processo di onboarding in 13 fasi

Passo 1: Verifica le condizioni preliminari

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

Cosa viene controllato:

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

Possibili esiti:

✅ Ambienti trovati entrambi:

✅ 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à nel 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 di app personalizzato.

Nota

Gli ID di 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 il testing locale durante l'acquisizione. La creazione di un canale 'produzione' non significa che le tue aggiornamenti andranno in live per i clienti immediatamente. 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à creato e impostato come predefinito un 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 i canali manualmente in un secondo momento. Alternativamente, puoi:

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

Passo 4: Installa Plugin 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? Con gli aggiornamenti istantanei abilitati, la tua app applica gli aggiornamenti immediatamente quando è in background e viene riaperta. Funziona senza problemi perché il 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 al riavvio successivo dell'app. Gli aggiornamenti istantanei sono ottimi per una maggiore velocità 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
• directUpdate: 'always' e autoSplashscreen: true saranno aggiunti alla tua configurazione
• 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

Step 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 per l'aggiunta di un'app Guida per l'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 le chiavi di crittografia
2. Offri la possibilità di sincronizzare la tua configurazione Capacitor

Passo 7: Seleziona piattaforma

Scegli 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

Ciò influenza solo il processo di acquisizione. 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 manca lo script di build:

Ti verrà chiesto se vuoi saltare la build o aggiungere uno script di build 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 prova

È ora 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 prova visibile o una modifica.

Modalità manuale: Fai le tue modifiche (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?

Suggerimento

Se hai bisogno di costruire manualmente in un'altra finestra del terminale, seleziona “No” e costruisci tu stesso, 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

Tip

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 che 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 gli aggiornamenti istantanei.

Prompt per gli aggiornamenti delta (se Direct Update è 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 a tuo package.json e node_modules.

Successo:

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

Passaggio 12: Test Update 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?

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

Passaggio 13: Completamento

Welcome onboard ✈️!

Congratulazioni! Hai avviato con successo Capgo gli aggiornamenti in tempo reale per la tua app.

Cosa hai ottenuto

Dopo aver completato l'assistenza all'utente, hai:

✅ App Registrata

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

✅ Plugin Installato

La Capacitor Updater plugin è installata e configurata

✅ 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 quotidiano

Per gli aggiornamenti successivi, utilizza:

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

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

Ripresa della Registrazione

Se esiti nel 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?

Suggerimento

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

Risoluzione dei Problemi

Nessun Ambiente di Sviluppo

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

Soluzione:

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

ID dell'app già utilizzato

Problema: Il tuo ID dell'app è già registrato.

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

Manca lo script di build

Problema: Non è stato trovato alcun script di build 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 una versione successiva:

• 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 dal pannello di controllo di Capgo

Tipi di Aggiornamento

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

Integrazione CI/CD

Automatizza i tuoi deployment di aggiornamento con CI/CD

Canali

Gestisci più flussi di aggiornamento con i canali

Crittografia

Sicurizza 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
• Recensisci il FAQ
• Contattaci Supporto