Troubleshooting

Ecco alcune problematiche comuni che potresti incontrare mentre utilizzi Capgo e come risolverle.

🚀 Hai Bisogno di Aiuto Esperto?

Sei bloccato con un problema complesso? Il nostro team esperto è qui per aiutarti! Ricevi supporto personalizzato, code recensioni e soluzioni personalizzate adattate alle tue esigenze specifiche.

Supporto Professionale

Fallimenti di caricamento

Se il caricamento del tuo bundle fallisce, controlla:

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

Opzioni di caricamento avanzate

Il Capgo CLI fornisce alcune bandiere aggiuntive per aiutare con le comuni problematiche di caricamento:

• --tus: Utilizza il protocollo di caricamento resumabile tus per caricamenti più affidabili di grandi pacchetti o su connessioni di rete scarse. Se il tuo pacchetto supera i 10MB o sei su una connessione scarna, considera l'uso di --tus:

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

• --package-json e --node-modules: Insegna al Capgo dove trovare la radice package.json e node_modules se il tuo app utilizza una struttura non standard come un repository unico o un ambiente di lavoro npm. Passa la strada alla radice package.json e il --node_modules path:

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

  Capgo richiede questa informazione per compilare correttamente le dipendenze del tuo app.

Puoi combinare questi flag con altre opzioni come --channel come necessario. Vedi i Capgo CLI documenti per avere informazioni dettagliate sulle opzioni di caricamento disponibili.

Se hai ancora problemi con i caricamenti, contatta Capgo supporto per ulteriore assistenza.

Aggiornamenti di debug

Se stai incontrando problemi con gli aggiornamenti in tempo reale, il comando di debug Capgo è uno strumento utile per risolvere i problemi. Per utilizzarlo:

1. Eseguire il seguente comando nel tuo directory di progetto:

   npx @capgo/cli@latest app debug

2. Lancia l'app sul tuo dispositivo o emulatore e esegui l'azione che dovrebbe attivare l'aggiornamento (ad esempio, riaprire l'app dopo aver caricato un nuovo bundle).

3. Guarda l'output del comando di debug. Sarà registrato l'informazione sull'aggiornamento, comprese:

   • Quando l'app controlla gli aggiornamenti
   • Se viene trovato un aggiornamento e di quale versione si tratta
   • Progresso di download e installazione per l'aggiornamento
   • Qualsiasi errore che si verifica durante il processo di aggiornamento

4. Usa i registri di debug per identificare dove si verifica il problema. Ad esempio:

   • Se non viene trovata alcuna aggiornamento, controlla nuovamente che il tuo pacchetto sia stato caricato con successo e che l'app sia configurata per utilizzare il canale corretto.
   • Se l'aggiornamento scarica ma non si installa, assicurati di aver chiamato CapacitorUpdater.notifyAppReady() e che l'app sia stata chiusa e riaperta completamente.
   • Se vedi un messaggio di errore, cerca la specifica voce di errore nei documenti Capgo o contatta il supporto per aiuto.

Il comando di debug è particolarmente utile per identificare problemi con il download e l'installazione dell'aggiornamento. Se i registri mostrano la versione di aggiornamento prevista trovata ma non applicata, concentra la tua ricerca di errori sui passaggi dopo il download.

Debugging con registri nativi

Inoltre ai registri di debug del Capgo, i registri nativi di Android, iOS e Electron possono fornire informazioni di troubleshooting preziose, soprattutto per problemi sul lato nativo del processo di aggiornamento.

Registri di Android

Per accedere ai registri di Android:

1. Connetti il tuo dispositivo o avvia il tuo emulatore
2. Apri Android Studio e seleziona "Visualizza > Finestre degli strumenti > Logcat"
3. Nella finestra Logcat, filtra i log per mostrare solo i processi del tuo app selezionando il tuo app dal menu a discesa in alto
4. Cerca righe che includono Capgo per trovare i log SDK

Alternativamente, puoi utilizzare il adb logcat e cerca con grep per Capgo per filtrare i log.

I log Capgo SDK registreranno gli eventi chiave durante il processo di aggiornamento, ad esempio:

• Quando viene avviato il controllo delle aggiornamenti
• Se viene trovato un aggiornamento e di quale versione si tratta
• Quando inizia e si completa il download dell'aggiornamento
• When l'installazione dell'aggiornamento viene attivata
• Qualsiasi errore che si verifica durante i passaggi di aggiornamento nativi

Illoggetto comune specifico di Android che potresti vedere nei log comprende:

• Illoggetto di connettività di rete che impedisce il download dell'aggiornamento
• Illoggetto di errori di autorizzazione dei file quando si salva o si legge il bundle di aggiornamento
• L'assenza di spazio di archiviazione per il bundle di aggiornamento
• L'insuccesso nel riavviare l'app dopo l'installazione dell'aggiornamento

Log di iOS

Per accedere ai log di iOS:

1. Collega il tuo dispositivo o avvia il tuo simulatore
2. Apri Xcode e vai a “Finestra > Dispositivi e simulatori”
3. Scegli il tuo dispositivo e clicca su “Apri Console”
4. Nel output della console, cerca righe che includono Capgo per trovare i SDK log

Puoi anche utilizzare il log stream comando nella finestra dei comandi e grep per Capgo per filtrare i log.

Simile all'Android, il Capgo SDK registrerà gli eventi chiave iOS-side:

• Iniziazione e risultato della verifica dell'aggiornamento
• Inizio, progresso e completamento del download
• Attivazione e risultato dell'installazione
• Qualsiasi errore durante il processo di aggiornamento nativo

Problemi iOS-specifici che potresti identificare nei log includono:

• Problemi con il certificato SSL durante il download dell'aggiornamento
• La sicurezza dei trasporti dell'app blocca il download dell'aggiornamento
• Spazio di archiviazione insufficiente per il pacchetto di aggiornamento
• Fallimento nell'estrazione o nell'applicazione corretta del pacchetto di aggiornamento

Log di Electron

Per le app di Electron, controlla sia l'output del processo principale che del processo renderer:

1. Eseguisci l'app di Electron dal tuo terminale utilizzando il comando di avvio normale (ad esempio bun run electron:dev o bun run electron:serve) e osserva l'output del terminale per startup, controlli di aggiornamento e errori di rete.
2. Apre gli strumenti di sviluppatore nella finestra del renderer (Visualizza → Alternare strumenti di sviluppatore) e ispeziona i log del console e le richieste di rete fallite mentre si riproduce il flusso di aggiornamento.
3. Per le app pacchettizzate, controlla gli strumenti di log del sistema per crash o fallimenti di avvio:
   • macOS: apri Console.app e filtra sul nome del tuo app
   • Windows: apri Visualizza Event Viewer → Windows Logs → Application
   • Linux: utilizza il tuo visualizzatore dei log desktop o journalctl per il processo dell'applicazione

Quando si debuggano gli aggiornamenti, confronta i messaggi da entrambi i log del processo principale e del processo renderer per separare le questioni di avvio di Electron dalle questioni del ciclo di vita degli aggiornamenti Capgo.

Across piattaforme, i log nativi forniscono una visione a livello inferiore del processo di aggiornamento, con maggiori dettagli sulla implementazione nativa. Sono particolarmente utili per l'identificazione di problemi che si verificano al di fuori della Capgo layer JavaScript.

Quando si risolve un problema di aggiornamento in tempo reale complesso, è una buona idea catturare sia i Capgo log di debug che i log nativi per una visione completa di cosa sta succedendo. I due log insieme daranno la migliore possibilità di identificare e risolvere il problema.

Aggiornamenti non applicati

Se hai caricato un bundle ma non vedi i cambiamenti sul tuo dispositivo:

• Assicurati di aver chiamato CapacitorUpdater.notifyAppReady() nel tuo app code come mostrato nel quickstart
• Controlla che il tuo dispositivo sia connesso a Internet e i Capgo log di debug mostrino che l'aggiornamento è stato scaricato
• Prova a chiudere completamente e riaprire l'app, poiché gli aggiornamenti vengono applicati solo alla prima avviatura
• Cerca eventuali errori nei log nativi che potrebbero indicare un problema nell'applicazione dell'aggiornamento

Riferiti a aggiornamenti in tempo reale guida per ulteriori informazioni sul processo di aggiornamento. Se sei ancora bloccato, utilizza il npx @capgo/cli@latest app debug comando e i log nativi per ottenere una maggiore visibilità su cosa sta accadendo.

Codici di errore di aggiornamento comuni

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

• Problemi di Aggiornamento Comuni

Spiega cosa significa ogni code comune, perché accade e come risolvere il problema.

SDK Installazione

If hai difficoltà nell'installare il Capgo SDK, assicurati:

• La tua app utilizza una versione supportata di Capacitor (4.0 o successiva)
• Hai seguito i passaggi del quickstart nella giusta sequenza, compresa la sincronizzazione dell'app dopo l'installazione del SDK

Integrazione CI/CD

Per problemi con l'invio degli Capgo upload dal tuo pipeline CI/CD:

• Controlla che il tuo token di autenticazione Capgo sia configurato correttamente
• Assicurati di eseguire il comando di upload dopo che i tuoi asset web sono stati generati
• Verifica che il comando di upload utilizzi il nome del canale corretto per il tuo ambiente di destinazione

Vedi il Integrazione CI/CD per ulteriori consigli di risoluzione dei problemi. Puoi anche utilizzare il npx @capgo/cli@latest app debug comando per verificare se gli aggiornamenti attivati da CI/CD stanno raggiungendo l'app.

Continua da Troubleshooting

Se stai utilizzando Troubleshooting per pianificare lo storage e il trattamento dei file, connettilo con @capgo/capacitor-data-storage-sqlite per i dettagli di implementazione in @capgo/capacitor-data-storage-sqlite, Utilizzando @capgo/capacitor-data-storage-sqlite per la capacità nativa in Utilizzando @capgo/capacitor-data-storage-sqlite, @capgo/capacitor-file per il dettaglio di implementazione in @capgo/capacitor-file, Utilizzando @capgo/capacitor-file per la capacità nativa in Utilizzando @capgo/capacitor-file, e @capgo/capacitor-uploader per il dettaglio di implementazione in @capgo/capacitor-uploader.