CLI Guida di Onboarding

Panoramica rapida

Il Capgo CLI fornisce un'esperienza di onboarding interattiva che configura gli aggiornamenti in tempo reale per il tuo Capacitor app. Sarai:

1. ✅ Registra il tuo 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 al tempo di compilazione)

Tip

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 API chiave:

npx @capgo/cli@latest init [APIKEY]

Vedrai il messaggio di benvenuto:

Capgo onboarding 🛫

Cosa Succede Durante L'Onboarding

La CLI ti 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
• Installare il @capgo/capacitor-updater plugin
• Inserisci il code richiesto nel tuo app
• Facoltativamente abilita la crittografia end-to-end
• Scegli una piattaforma per le prove (iOS o Android)

Fase di testing (Passaggi 7-12):

• Costruisci il tuo app e eseguilo su un dispositivo/simulatore
• Apporta un cambiamento visibile code (automatico o manuale)
• Carica l'aggiornato bundle su Capgo
• Vedi l'aggiornamento in tempo reale apparire sul tuo dispositivo

Completa (Passo 13):

• Il tuo app è pronta per gli aggiornamenti in tempo reale! 🎉

Il processo di avvio di 13 passaggi

Passo 1: Verifica le condizioni preliminari

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

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 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 farà accedere a Capgo e aggiungerà il tuo 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 app personalizzato.

Nota

Gli ID app devono seguire la notazione di dominio inverso (ad esempio, com.example.myapp)

Step 3: Creare Canale di Produzione

I canali ti consentono di gestire diversi flussi di aggiornamento per il tuo app.

❓ Create default channel production for {appId} in Capgo?

Avviso

Non preoccuparti! Questo è solo per test locale durante l'accesso. Creare un canale "di produzione" non significa che le tue aggiornamenti andranno in live per i clienti immediatamente. Hai il pieno controllo su quando 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à creato e impostato come canale predefinito. 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”

plugin compatibile con la tua versione di CLI. @capgo/capacitor-updater plugin compatible with your Capacitor version.

❓ 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 v5 e successive. 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

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é 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 sarà aggiunto 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

Passo 5: Aggiungi Integrazione Code

Il CLI inietterà automaticamente i code richiesti nella tua 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: Creare 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()

Inserisci questo code dopo le tue importazioni e prima dell'inizializzazione dell'app. Per ulteriori dettagli, consulta la guida dell'App Guida all'App: Step 6: Configura la crittografia (Facoltativo).

Sottosezione intitolata “Step 6: Configura la crittografia (Facoltativo)”

Copia nella clipboard

🔐 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. Offrirà di sincronizzare la configurazione del tuo Capacitor

Step 7: Seleziona piattaforma

Scegliere 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ò influisce solo sul processo di acquisizione. L'app finale supporta tutte le piattaforme.

Passo 8: Costruisci il tuo progetto

Il CLI costruirà il tuo app e sincronizzerà con Capacitor.

❓ Automatic build {appId} with "npm run build"?

Cosa succede:

1. Rileva il tipo di progetto
2. Esegue lo script di costruzione
3. Esegue npx cap sync {platform}

Se lo script di costruzione manca:

Ti verrà chiesto se vuoi 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 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 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 di comando, 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: 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 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.

Prompt degli aggiornamenti delta (se un modello di applicazione istantanea è abilitato):

💡 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 al tuo package.json e node_modules.

Successo:

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

Passo 12: Test Update sul Dispositivo

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 Capgo gli aggiornamenti in tempo reale per la tua app.

Cosa hai ottenuto

Dopo aver completato l'onboarding, hai:

Dovuto App Registrata

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

Dovuto Plugin Installato

È installato e configurato il plugin di aggiornamento Capacitor

Dovuto Code Integrato

L'integrazione code è stata aggiunta alla tua app

Dovuto Aggiornamento Testato

Hai con successo distribuito e ricevuto un aggiornamento live

Ciclo 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 Distribuisci un aggiornamento in tempo reale.

Ripresa della configurazione iniziale

Se esiti dal processo di configurazione iniziale, 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 tutta sicurezza.

Risoluzione dei problemi

Nessun ambiente di sviluppo

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

Soluzione:

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

ID App già preso

Problema: Il tuo ID app è già registrato.

Soluzione: Scegli una delle 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ò iniettare automaticamente l'integrazione code.

Soluzione: Aggiungi code manualmente al tuo file principale:

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

CapacitorUpdater.notifyAppReady()

Capacitor Version Troppo Vecchio

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:

Deploy Aggiornamenti

Scopri come distribuire gli aggiornamenti dalla dashboard 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 tue distribuzioni di aggiornamento con CI/CD

Canali

Gestisci più flussi di aggiornamento con i canali

Crittografia

Assicura la sicurezza degli aggiornamenti con crittografia end-to-end

Comportamento dell'Aggiornamento

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

Ottenere Aiuto

Se incontri problemi durante l'acquisizione:

• Controlla il Guida di Risoluzione dei Problemi
• Unisciti alla Community Discord
• Rivista il FAQ
• Contatta Supporto

Continua da CLI Guida di Acquisizione

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