Guida di Onboarding di CLI

Panoramica rapida

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

1. ✅ Registra la tua 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)

Consiglio

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

Iniziare l'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 ti 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 i code richiesti nel tuo app
• Opzionalmente abilita 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
• Fai una modifica visibile (code) (automatica o manuale)
• Incarica l'aggiornamento del bundle su Capgo
• Vedi l'aggiornamento live apparire sul tuo dispositivo in tempo reale

Completa (Passaggio 13):

• L'app è pronta per gli aggiornamenti live! 🎉

Procedura di onboarding in 13 passaggi

Passo 1: Verifica i prerequisiti

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

Ciò che viene 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 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 l'ID della tua 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 personalizzato per la tua app.

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

• Impostare 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 la versione più recente

Attenzione

Capgo supporta solo Capacitor a partire dalla versione v5. 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 iterazione più veloce 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 verranno aggiunti alla tua configurazione
• La tua capacitor.config.ts verrà aggiornata automaticamente
• Gli aggiornamenti delta context: Pagina/area: Pagina prodotti/prezzi aziendale. Ruolo: Etichetta UI breve o elemento di navigazione. Visualizzato in: pagina enterprise.astro. Chiave messaggio `enterprise_delta_updates` (Aggiornamenti delta aziendali).

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:

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

Passo 5: Aggiungi integrazione Code

La 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()

Determinazione 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 informazioni, consulta il Guida per l'aggiunta di un'app.

Passaggio 6: Configurazione della crittografia (facoltativa)

La crittografia a fine-alla-crittografia 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: Scegli la piattaforma

Scegli la piattaforma con cui testare durante l'onboarding.

📱 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 onboarding. La tua app finale supporterà tutte le piattaforme.

Passo 8: Costruisci il tuo progetto

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

E' 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: CLI modificherà automaticamente i tuoi file per aggiungere un banner di test visibile o una modifica.

Modalità manuale: Tu 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?

Consiglio

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

Fase 11: Carica Bundle

Carica il tuo bundle di app aggiornato su Capgo.

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

CLI esegue:

npx @capgo/cli@latest bundle upload

Consiglio

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)

Attento

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

Ecco 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

Segui 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'applicazione

✅ Aggiornamento Testato

Hai completato con successo la distribuzione 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 distribuzione, vedi Distribuzione di un Aggiornamento Live.

Ripresa dell'Onboarding

If you exit the onboarding process, you can resume anytime:

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 (solo 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 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 superiore:

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

Eseguire 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

Automate gli aggiornamenti dei deployment 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.)

Aiuto

Se incontri problemi durante l'onboarding:

• Controlla il Guida di Ricerca dei Problemi
• Unisciti alla Comunità Discord
• Recensisci il FAQ
• Contattaci Sostegno

Keep going from CLI Onboarding Guide

Se stai utilizzando CLI Onboarding Guide to plan dashboard and API operations, connect it with Panoramica API per i dettagli di implementazione in Panoramica API 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.