Risoluzione problemi

Ecco alcuni problemi comuni che potresti riscontrare usando Capgo e come risolverli.

🚀 Ti serve aiuto da un esperto?

Bloccato su un problema complesso? Il nostro team di esperti è qui per aiutarti! Ottieni supporto personalizzato, revisioni code e soluzioni su misura per le tue esigenze.

Ottieni supporto professionale

Errori durante l'upload

Se l'upload del bundle fallisce, ricontrolla:

• Che l'app ID in capacitor.config.ts corrisponda alla tua app nella dashboard Capgo
• che stai eseguendo il comando di upload dalla root del tuo progetto Capacitor
• che i tuoi web assets siano buildati e aggiornati

Opzioni di upload avanzate

La Capgo CLI offre alcuni flag aggiuntivi per risolvere i comuni problemi di upload:

• --tus: Utilizza il il tuo protocollo di upload resumable per upload più affidabili di bundle pesanti o con connessioni instabili. Se il bundle supera i 10MB o la connessione è scarsa, considera l'uso di --tus:

  npx @capgo/cli@latest bundle upload --tus

• --package-json e --node-modules: indica a Capgo dove trovare la root package.json e node_modules se la tua app usa una struttura non standard come un monorepo o un workspace npm. Passa il percorso della root package.json e nella --node_modules path:

  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 creare correttamente il bundle delle dipendenze della tua app.

Puoi combinare questi flag con altre opzioni come --channel secondo necessità. Consulta la documentazione di Capgo CLI per tutti i dettagli sulle opzioni di upload disponibili.

Se riscontri ancora problemi con gli upload, contatta supporto Capgo per ulteriore assistenza.

Debug degli Update

Se riscontri problemi con i live update, il comando debug di Capgo è uno strumento utile per il troubleshooting. Per usarlo:

1. Esegui il seguente comando nella directory del tuo progetto:

   npx @capgo/cli@latest app debug

2. Avvia l'app su un dispositivo o emulatore ed esegui l'azione che dovrebbe attivare l'aggiornamento (es. riaprire l'app dopo aver caricato un nuovo bundle).

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

   • Quando l'app controlla se ci sono aggiornamenti
   • Se viene trovato un aggiornamento e di quale versione si tratta
   • Progresso del download e dell'installazione dell'aggiornamento
   • Eventuali errori 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 usare il canale giusto.
   • Se l'aggiornamento viene scaricato ma non installato, assicurati di aver chiamato CapacitorUpdater.notifyAppReady() e che l'app sia stata completamente chiusa e riaperta.
   • Se visualizzi un messaggio di errore, cerca quell'errore specifico nella documentazione di Capgo o contatta il supporto per ricevere assistenza.

Il comando debug è utilissimo per identificare problemi nel processo di download e installazione dell'update. Se i log indicano che la versione corretta è stata trovata ma non applicata, concentra il troubleshooting sui passaggi successivi al download.

Debugging con i log nativi

Oltre al comando debug di Capgo, i log nativi di Android, iOS ed Electron possono fornire informazioni preziose, specialmente per problemi lato nativo durante il processo di update.

Log di Android

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 visualizzare solo il processo della tua app selezionandolo dal menu a tendina in alto
4. Cerca eventuali righe che includono Capgo per trovare i log di SDK

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

Il SDK di Capgo loggherà gli eventi chiave durante il processo di update, come:

• Quando viene avviata la verifica dell'update
• Se viene trovato un update e di quale versione si tratta
• Quando l'update download inizia e termina
• Quando viene triggerata l'installazione dell'update
• Eventuali errori durante i passaggi di native update

I problemi comuni specifici per Android che potresti vedere nei log includono:

• Problemi di connettività di rete che impediscono l'update download
• Errori di permessi dei file durante il salvataggio o la lettura dell'update bundle
• Spazio di archiviazione insufficiente per il bundle di update
• Impossibilità di riavviare l'app dopo l'installazione dell'update

Log iOS

Per accedere ai log di iOS:

1. Collega il tuo dispositivo o avvia il simulatore
2. Apri Xcode e vai su “Window > Devices and Simulators”
3. Seleziona il tuo dispositivo e clicca su “Open 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 usa grep per Capgo per filtrare i log.

Simile ad Android, il Capgo SDK loggherà i principali eventi lato iOS:

• Inizio e risultato del controllo update
• Inizio, progresso e completamento del download
• Trigger e risultato dell'installazione
• Eventuali errori durante il processo di update nativo

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

• Problemi di certificato SSL durante il download dell'update
• App Transport Security che blocca il download dell'update
• Spazio di archiviazione insufficiente per l'update bundle
• Errore nell'estrazione o nell'applicazione dell'update bundle

Log di Electron

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

1. Avvia l'app Electron dal terminale usando il tuo comando di lancio abituale (ad esempio bun run electron:dev o bun run electron:serve) e monitora 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. Per le app pacchettizzate, controlla i log del sistema operativo per crash o errori di avvio:
   • macOS: apri Console.app e filtra per il nome della tua app
   • Windows: apri Visualizzatore eventi → Log di Windows → Applicazione
   • Linux: usa il visualizzatore log del desktop o journalctl per il processo della tua app

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

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

Quando risolvi un problema complesso con live update, è consigliabile catturare sia i log di debug di Capgo che i log nativi per avere un quadro completo della situazione. L'analisi combinata dei due log ti darà le migliori possibilità di identificare e risolvere il problema.

Update non applicati

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'update è stato scaricato
• Prova a chiudere e riaprire completamente l'app, poiché gli update vengono applicati solo all'avvio
• Controlla eventuali errori nei log nativi che potrebbero indicare un problema nell'applicazione dell'update

Consulta la deploying Live Update guide per maggiori dettagli sul processo di update. Se sei ancora bloccato, usa il npx @capgo/cli@latest app debug comando e i log nativi per avere maggiore visibilità su cosa sta succedendo.

Codici di errore comuni degli update

Se i log mostrano errori del backend come disable_auto_update_to_major, semver_error, o cannot_update_via_private_channel, consulta la guida dedicata:

• Problemi comuni di aggiornamento

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

Installazione di SDK

Se riscontri problemi nell'installazione del SDK di Capgo, assicurati che:

• La tua app utilizzi una versione supportata di Capacitor (4.0 o successiva)
• Hai seguito la guida rapida passaggi in ordine, incluso il sync dell'app dopo l'installazione di SDK

Integrazione CI/CD

Per problemi con l'upload di Capgo tramite la tua pipeline CI/CD:

• Verifica che il token di autenticazione Capgo sia configurato correttamente
• Assicurati di eseguire il comando di upload dopo il build degli asset web
• Controlla che il comando di upload usi il nome del channel corretto per l'ambiente target

Vedi la Integrazione CI/CD docs per altri consigli di troubleshooting. Puoi anche usare il npx @capgo/cli@latest app debug comando per confermare se gli update via CI/CD vengono ricevuti dall'app.

Torna a Troubleshooting

Se stai usando Risoluzione problemi per pianificare storage e gestione dei file, collegalo con @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 Uso di @capgo/capacitor-data-storage-sqlite @capgo/capacitor-file per i dettagli di implementazione in @capgo/capacitor-file, Uso di @capgo/capacitor-file per la funzionalità nativa in Using @capgo/capacitor-file, e @capgo/capacitor-uploader per i dettagli di implementazione in @capgo/capacitor-uploader.