Vai al contenuto

Risoluzione problemi

Ecco alcuni problemi comuni che potresti incontrare durante l'uso di Capgo e come risolverli.

🚀 Hai bisogno di un esperto?

Bloccato su un problema complesso? Il nostro team di esperti è a tua disposizione! Ricevi supporto personalizzato, revisioni code e soluzioni su misura per le tue esigenze specifiche.

Se l'upload del bundle fallisce, verifica di nuovo:

  • L'ID della tua app in capacitor.config.ts corrisponde alla tua app nella dashboard Capgo
  • Stai eseguendo il comando di upload dalla radice del tuo progetto Capacitor
  • I tuoi asset web sono stati buildati e sono aggiornati

Il Capgo CLI offre alcune flag aggiuntive per risolvere i problemi comuni di upload:

  • --tus: Utilizza il protocollo tus per upload resumable per upload più affidabili di bundle di grandi dimensioni o su connessioni di rete instabili. Se il tuo bundle supera i 10 MB o sei su una connessione instabile, valuta l'uso di --tus:

    Finestra del terminale
    npx @capgo/cli@latest bundle upload --tus
  • --package-json e --node-modules: Indica a Capgo dove trovare la tua root package.json e node_modules se la tua app utilizza una struttura non standard come un monorepo o un workspace npm. Passa il percorso alla root package.json e il --node_modules path:

    Finestra del terminale
    npx @capgo/cli@latest bundle upload --package-json=path/to/package.json --node_modules=path/to/node_modules

    Capgo ha bisogno di queste informazioni per bundlare correttamente le dipendenze della tua app.

Puoi combinare queste flag con altre opzioni come --channel se necessario. Consulta la documentazione di Capgo CLI per i dettagli completi sulle opzioni di upload disponibili.

Se hai ancora problemi con gli upload, contatta Supporto Capgo per ulteriore assistenza.

Se stai riscontrando problemi con Live Update, il comando di debug Capgo è uno strumento utile per la risoluzione dei problemi. Per utilizzarlo:

  1. Esegui il seguente comando nella directory del progetto:

    Finestra del terminale
    npx @capgo/cli@latest app debug
  2. Avvia l'app su un dispositivo o un emulatore ed esegui l'azione che dovrebbe attivare un aggiornamento (ad esempio, riapri l'app dopo aver caricato un nuovo bundle).

  3. Monitora l'output del comando di debug. Registrerà informazioni sul processo di aggiornamento, tra cui:

    • Quando l'app verifica gli aggiornamenti
    • Se viene trovato un aggiornamento e di quale versione si tratta
    • Avanzamento del download e dell'installazione dell'aggiornamento
    • Qualsiasi errore che si verifica durante il processo di aggiornamento
  4. Usa i log di debug per identificare dove si verifica il problema. Ad esempio:

    • Se non viene trovato alcun aggiornamento, verifica che il bundle sia stato caricato correttamente e che l'app sia configurata per utilizzare il canale corretto.
    • Se l'update viene scaricato ma non installato, assicurati di aver chiamato CapacitorUpdater.notifyAppReady() e che l'app sia stata chiusa completamente e riaperta.
    • Se vedi un messaggio di errore, cerca quell'errore specifico nella documentazione di Capgo o contatta il supporto per assistenza.

Il comando debug è particolarmente utile per individuare problemi nel processo di download e installazione dell'aggiornamento. Se i log mostrano che la versione di aggiornamento prevista è stata trovata ma non applicata, concentra il troubleshooting sulle fasi successive al download.

Oltre al comando debug di Capgo, i log nativi su Android, iOS ed Electron possono fornire informazioni preziose per il troubleshooting, soprattutto per i problemi sul lato nativo del processo di aggiornamento.

Per accedere ai log di Android:

  1. Collega il dispositivo o avvia l'emulatore
  2. Apri Android Studio e seleziona “View > Tool Windows > Logcat”
  3. Nella finestra Logcat, filtra i log per mostrare solo il processo della tua app selezionandolo dal menu a discesa in alto
  4. Cerca eventuali righe che contengono Capgo per trovare i log di SDK

In alternativa, puoi usare la adb logcat comando e usare grep per Capgo filtrare i log.

Il Capgo SDK logga gli eventi chiave durante il processo di aggiornamento, come:

  • When an update check is initiated
  • Se viene trovato un aggiornamento e di quale versione si tratta
  • Quando inizia e termina il download dell'aggiornamento
  • Quando viene avviata l'installazione dell'aggiornamento
  • Eventuali errori che si verificano durante le fasi di aggiornamento nativo

I problemi comuni su Android che potresti trovare nei log includono:

  • Problemi di connettività di rete che impediscono il download dell'aggiornamento
  • Errori di permessi file durante il salvataggio o la lettura del bundle di aggiornamento
  • Out of storage space for the update bundle
  • L'app non si riavvia dopo l'installazione dell'aggiornamento

Per accedere ai log iOS:

  1. Collega il dispositivo o avvia il simulatore
  2. Apri Xcode e vai su “Finestra > Dispositivi e simulatori”
  3. Seleziona il dispositivo e fai clic su “Apri console”
  4. Nell'output della console, cerca le righe che includono Capgo per trovare i log di SDK

Puoi anche usare il log stream comando nel terminale e cerca con grep Capgo filtrare i log.

Come per Android, Capgo SDK registrerà gli eventi principali lato iOS:

  • Avvio e risultato del controllo degli aggiornamenti
  • Avvio, avanzamento e completamento del download
  • Attivazione e risultato dell'installazione
  • Eventuali errori durante il processo di aggiornamento nativo

I problemi specifici di iOS che potresti individuare nei log includono:

  • Problemi con il certificato SSL durante il download dell'aggiornamento
  • App Transport Security che blocca il download dell'aggiornamento
  • Spazio di archiviazione insufficiente per il bundle di aggiornamento
  • Impossibile estrarre o applicare correttamente il bundle di aggiornamento

Per le app Electron, controlla l'output sia del main process che del renderer process:

  1. Avvia l'app Electron dal terminale con il tuo comando di lancio abituale (ad esempio bun run electron:dev oppure bun run electron:serve) e tieni d'occhio l'output del terminale per avvio, controlli degli update ed errori di rete.
  2. Apri i DevTools nella finestra del renderer (View → Toggle Developer Tools) e ispeziona i log della console e le richieste di rete fallite mentre riproduci il flusso di update.
  3. For packaged apps, check OS log tools for crashes or startup failures:
    • macOS: apri Console.app e filtra per il nome della tua app
    • Windows: apri Event Viewer → Log di Windows → Applicazione
    • Linux: usa il visualizzatore di log del desktop o journalctl per il processo della tua app

Durante il debug degli aggiornamenti, confronta i messaggi dei log di main-process e renderer-process per distinguere i problemi di bootstrap di Electron dai problemi del ciclo di vita degli aggiornamenti Capgo.

Su tutte le piattaforme, i log nativi offrono una visione a livello inferiore del processo di aggiornamento, con maggiori dettagli sull'implementazione nativa. Sono particolarmente utili per identificare problemi che si verificano al di fuori dello strato JavaScript di Capgo.

Quando si risolvono problemi complessi di live update, è una buona idea catturare sia i log di debug di Capgo sia i log nativi per avere un quadro completo di ciò che sta accadendo. Insieme, i due log offrono la migliore possibilità di identificare e risolvere il problema.

Se hai caricato un bundle ma non vedi le modifiche sul dispositivo:

  • Assicurati di aver chiamato CapacitorUpdater.notifyAppReady() nella tua app code come mostrato nella quickstart
  • Verifica che il dispositivo sia connesso a Internet e che i log di debug di Capgo mostrino che l'aggiornamento è stato scaricato
  • Chiudi e riapri completamente l'app, poiché gli aggiornamenti vengono applicati solo al nuovo avvio
  • Cerca eventuali errori nei log nativi che potrebbero indicare un problema nell'applicazione dell'aggiornamento

Consulta la guida alla distribuzione degli aggiornamenti live per maggiori dettagli sul processo di aggiornamento. Se hai ancora problemi, usa il npx @capgo/cli@latest app debug comando e log nativi per avere maggiore visibilità su ciò che sta accadendo.

Se i tuoi log mostrano errori di backend come disable_auto_update_to_major, semver_error, o cannot_update_via_private_channel, usa la guida dedicata:

Spiega cosa significa ciascun code comune, perché si verifica e come risolverlo.

Se hai problemi con l'installazione di Capgo SDK, assicurati che:

  • La tua app utilizzi una versione supportata di Capacitor (4.0 o superiore)
  • Hai seguito la quickstart passo dopo passo, incluso il sync della tua app dopo aver installato SDK

Per problemi con il trigger degli upload Capgo dalla tua pipeline CI/CD:

  • Ricontrolla che il token di autenticazione Capgo sia configurato correttamente
  • Assicurati di eseguire il comando di upload dopo il build dei tuoi asset web
  • Controlla che il comando di upload usi il nome del canale corretto per il tuo ambiente di destinazione

Guarda il Integrazione CI/CD documentazione per ulteriori suggerimenti di troubleshooting. Puoi anche usare il npx @capgo/cli@latest app debug comando per verificare se gli aggiornamenti attivati da CI/CD vengono ricevuti dall'app.

Se stai usando Risoluzione problemi per pianificare lo storage e la gestione dei file, collegalo a @capgo/capacitor-data-storage-sqlite per i dettagli di implementazione in @capgo/capacitor-data-storage-sqlite, Utilizzo di @capgo/capacitor-data-storage-sqlite per la funzionalità nativa in Utilizzo di @capgo/capacitor-data-storage-sqlite, @capgo/capacitor-file per i dettagli di implementazione in @capgo/capacitor-file, Utilizzo di @capgo/capacitor-file per la funzionalità nativa in Usare @capgo/capacitor-file, e @capgo/capacitor-uploader per i dettagli implementativi in @capgo/capacitor-uploader.