Guida di Onboarding di CLI

Sezione intitolata “Riepilogo rapido”

The Capgo CLI provides an interactive onboarding that sets up live updates for your Capacitor app. You’ll:

1. ✅ Register your app in Capgo
2. 🔌 Installa e configura il plugin di aggiornamento
3. 🚀 Distribuisci il tuo primo aggiornamento live
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 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 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):

• Controlla 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
• Abilita opzionalmente la crittografia end-to-end
• Scegli una piattaforma per le prove (iOS o Android)

Fase di prova (Passaggi 7-12):

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

Completa (Passaggio 13):

• La tua app è pronta per gli aggiornamenti live! 🎉

Il processo di onboarding in 13 passaggi

Passo 1: Verifica i prerequisiti

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

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 che potresti essere posta:

Attenzione

Se non viene rilevato alcun ambiente di sviluppo, ti verrà chiesta 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?

Potrai scegliere una proposta o inserire un ID app personalizzato.

Nota

Il nome dell'app deve seguire la notazione del dominio inverso (ad esempio, com.example.myapp)

Passo 3: Crea un canale di produzione

Il canale consente di gestire diversi flussi di aggiornamento per l'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 per i clienti. Hai il controllo completo sul momento in cui gli aggiornamenti vengono distribuiti. Seleziona Sì a meno che non hai specifiche richieste per il canale.

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
• utilizzare 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

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

Avvertenza

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

Consigli

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é 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 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 e
• Sarà aggiunto al tuo config capacitor.config.ts La tua
• verrà aggiornata automaticamente Gli aggiornamenti delta

Sarà abilitato automaticamente - questo 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:

• Aggiornamenti che 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

Consiglio

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'applicazione. Per ulteriori dettagli, consulta la Guida per l'aggiunta di un'app.

Passaggio 6: Configurazione della crittografia (facoltativa)

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 di sincronizzare la configurazione del tuo Capacitor

Passaggio 7: Scegli la 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

Questo influisce solo sul processo di accesso. La tua app finale supporta tutte le piattaforme.

Step 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. Rileva 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 desideri saltare lo script di build o aggiungerne uno 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 prova

È 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 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 le modifiche:

❓ Build {appId} with changes before uploading?

Suggerimento

Se hai bisogno di costruire manualmente in un altro 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

Suggerimento

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

Gli aggiornamenti delta (se è abilitato un modello di applicazione istantaneo):

💡 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 progetti monorepo, 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

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 avuto successo nell'installare le Capgo aggiornamenti live per il tuo 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 all'app

✅ Aggiornamento Testato

Hai con successo distribuito e ricevuto un aggiornamento in tempo reale

Flusso di lavoro quotidiano

Per gli aggiornamenti successivi, utilizza:

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

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

Continuazione dell'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: Nessun rilevamento di Xcode o Android SDK è stato effettuato.

Soluzione:

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

ID 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 di 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ò 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

Esegui i passaggi successivi

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

Elenco di controllo di configurazione una volta sola

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

Distribuisci Aggiornamenti

Scopri come distribuire gli aggiornamenti dal pannello di controllo 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

Controlla il

• Verifica il Guida di Ricerca dei Problemi
• Unisciti alla Comunità Discord
• Rivista il FAQ
• Contattaci Sostegno

Continua con il Guida di Accompagnamento di CLI

Se stai utilizzando Guida di Accompagnamento di CLI 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.