Log
Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.
Log e Log Insights
Sezione intitolata “Log e Log Insights”La scheda App Log si apre Analisi dei log di default. Usa Insights per dare priorità a categorie, versioni e dispositivi per periodi di 1, 3, 7 o 30 giorni. Passa alla Log sottoscheda quando ti servono gli eventi del dispositivo, i filtri e i timestamp descritti di seguito.
Capire i log dell'applicazione
Sezione intitolata “Comprendere i log dell’applicazione”La sottopagine Logs grezzi fornisce una cronologia dettagliata degli eventi di aggiornamento e informazioni diagnostiche per la tua applicazione. È utile per confermare le prove a livello di dispositivo dietro un Insight, risolvere i problemi di un percorso di aggiornamento e capire come i dispositivi interagiscono con Capgo. Apri un'app, scegli Log, poi scegli la Log sottopagine.

L'interfaccia Logs grezzi include:
- Sottopulsante Logs — il controllo di navigazione per le righe di log individuali.
- Pulsante Ricarica — aggiorna l'elenco dei log con i dati più recenti.
- Filtri per intervallo di tempo e azione — restringe il flusso di eventi per tempo e azione.
Ogni riga mostra:
- Timestamp (UTC)
- ID dispositivo
- Azione code (cosa è successo)
- Nome versione (bundle o
builtin)
Clicca su una riga per aprire la pagina di dettaglio del dispositivo con la sua cronologia completa.
Filtro per intervallo di date
Sezione intitolata “Filtraggio per intervallo di date”Puoi filtrare i log per un periodo specifico usando il selettore di date:

- Preset rapidi - Seleziona intervalli di tempo comuni: ultime 1h, 3h, 6h o 12h
- Ora di inizio - Imposta un'ora di inizio personalizzata per l'intervallo
- Ora di fine - Set a custom end time for the range
- Calendario - Seleziona date specifiche usando la vista calendario
Fai clic su “Seleziona” per applicare l'intervallo di date scelto, oppure su “Annulla” per chiudere il selettore.
Filtro per tipo di azione
Sezione intitolata “Filtraggio per tipo di azione”Il menu a tendina Actions consente di filtrare i log per tipi di evento specifici:

I filtri di azione disponibili includono:
- Heartbeat del dispositivo - Controlli periodici di salute dai dispositivi
- Cancellazione versione richiesta - Quando una versione del bundle viene cancellata
- Reset alla versione predefinita - Quando un dispositivo torna al bundle integrato
- Versione installata con successo - Installazione bundle riuscita
- Nuova versione inviata al dispositivo - Quando Capgo invia un aggiornamento a un dispositivo
- Installazione versione non riuscita - Quando l'installazione del bundle fallisce
Usa la casella di ricerca in alto per trovare rapidamente tipi di azione specifici. Puoi selezionare più azioni per mostrare i log che corrispondono a uno qualsiasi dei tipi selezionati.
Esempio di log (dati fittizi)
Sezione intitolata “Esempio di log (dati fittizi)”| Ora (UTC) | ID dispositivo | Azione | Versione | Cosa ti dice |
|---|---|---|---|---|
| 2025-01-14 10:00:01 | A1B2C3 | get | 2.4.1 | Il device ha chiesto a Capgo se è disponibile un aggiornamento |
| 2025-01-14 10:00:03 | A1B2C3 | download_manifest_start | 2.4.1 | Download delta avviato; SDK sta per scaricare i file delta modificati |
| 2025-01-14 10:00:07 | A1B2C3 | download_40 | 2.4.1 | Download del bundle completato al 40% |
| 2025-01-14 10:00:12 | A1B2C3 | download_zip_complete | 2.4.1 | Download dello zip terminato |
| 2025-01-14 10:00:13 | A1B2C3 | set | 2.4.1 | Bundle installato e impostato come prossimo da eseguire |
| 2025-01-14 10:05:00 | B9C8D7 | disableAutoUpdateToMajor | 1.9.0 | La policy del canale ha bloccato un salto a 2.x |
| 2025-01-14 10:05:05 | B9C8D7 | rateLimited | integrata | Limite di richieste raggiunto per il dispositivo; SDK attende il riavvio |
Esempi di scenari di log
Sezione intitolata “Scenari di esempio nei log”Per aiutarti a interpretare i log, ecco alcune sequenze che mostrano i percorsi di aggiornamento reali dei dispositivi:
Flusso di aggiornamento riuscito
Sezione intitolata “Flusso di aggiornamento riuscito”Ecco come appare un aggiornamento andato a buon fine nei tuoi log:
| Ora | ID dispositivo | Azione | Versione | Cosa significa |
|---|---|---|---|---|
| 10:00:01 | a1b2c3d4 | get | 1.2.0 | Dispositivo controllato per aggiornamenti, ricevute info versione 1.2.0 |
| 10:00:02 | a1b2c3d4 | download_10 | 1.2.0 | Download avviato, completato al 10% |
| 10:00:03 | a1b2c3d4 | download_50 | 1.2.0 | Download al 50% |
| 10:00:05 | a1b2c3d4 | download_complete | 1.2.0 | Download completato con successo |
| 10:00:06 | a1b2c3d4 | set | 1.2.0 | Bundle installato e attivato |
Dispositivo già aggiornato
Sezione intitolata “Dispositivo già aggiornato”Quando un dispositivo effettua il controllo ma ha già l'ultima versione:
| Ora | ID dispositivo | Azione | Versione | Cosa significa |
|---|---|---|---|---|
| 14:30:00 | e5f6g7h8 | noNew | 1.2.0 | Il dispositivo è già all'ultima versione, nessun aggiornamento necessario |
Aggiornamento fallito con rollback
Sezione intitolata “Aggiornamento non riuscito con rollback”Quando un aggiornamento fallisce e il dispositivo esegue il rollback:
| Ora | ID dispositivo | Azione | Versione | Cosa significa |
|---|---|---|---|---|
| 11:15:00 | i9j0k1l2 | get | 1.3.0 | Il dispositivo ha ricevuto le info dell'update |
| 11:15:02 | i9j0k1l2 | download_complete | 1.3.0 | Download completato |
| 11:15:03 | i9j0k1l2 | set | 1.3.0 | Bundle impostato |
| 11:15:10 | i9j0k1l2 | update_fail | 1.3.0 | L'app è andata in crash o notifyAppReady() non è stata chiamata - rollback avviato |
| 11:15:11 | i9j0k1l2 | reset | integrata | Il dispositivo è tornato alla versione integrata |
Azione richiesta: Verifica che la tua app chiami notifyAppReady() dopo l'inizializzazione riuscita. Vedi la documentazione del plugin per i dettagli.
Errore di download
Sezione intitolata “Errore di download”Quando i problemi di rete impediscono il download:
| Ora | ID dispositivo | Azione | Versione | Cosa significa |
|---|---|---|---|---|
| 09:45:00 | m3n4o5p6 | get | 1.2.0 | Il dispositivo ha ricevuto le info dell'update |
| 09:45:01 | m3n4o5p6 | download_30 | 1.2.0 | Download avviato ma... |
| 09:45:15 | m3n4o5p6 | download_fail | 1.2.0 | Download fallito (timeout di rete, connessione persa, ecc.) |
Azione richiesta: Il dispositivo riproverà automaticamente al prossimo avvio dell'app. Nessuna azione necessaria, a meno che non accada spesso.
Limite del piano raggiunto
Sezione intitolata “Limite del piano raggiunto”Quando il tuo account raggiunge il limite di dispositivi:
| Ora | ID dispositivo | Azione | Versione | Cosa significa |
|---|---|---|---|---|
| 16:00:00 | q7r8s9t0 | needPlanUpgrade | - | Questo dispositivo non riceverà aggiornamenti finché non esegui l'upgrade o il ciclo di fatturazione non si azzera |
Azione richiesta: Esegui l'upgrade del piano o attendi il prossimo ciclo di fatturazione.
Configurazione del canale che blocca gli aggiornamenti
Sezione intitolata “Configurazione del canale che blocca gli update”Quando le impostazioni del canale impediscono un update:
| Ora | ID dispositivo | Azione | Versione | Cosa significa |
|---|---|---|---|---|
| 12:00:00 | u1v2w3x4 | disableAutoUpdateToMajor | 2.0.0 | Il dispositivo su v1.x non può auto-aggiornarsi a v2.x (salto di major version bloccato) |
| 12:05:00 | y5z6a7b8 | disableEmulator | 1.2.0 | Emulatore rilevato e il canale blocca gli emulatori |
| 12:10:00 | c9d0e1f2 | disableDevBuild | 1.2.0 | Dev build rilevata e il canale blocca le dev build |
Azione richiesta: Si tratta di protezioni intenzionali. Se vuoi consentire questi update, modifica il tuo impostazioni canale.
Codici log (Capgo backend enum)
Sezione intitolata “Codici log (Capgo backend enum)”Questi codici provengono dall' stats_action enum usato dalla dashboard API (capgo/src/types/supabase.types.ts). Se vedi un nuovo code nella UI, è stato emesso da SDK o dal backend e validato in base a questa lista.
Happy path & ciclo di vita
| Code(s) | Significato |
|---|---|
get | Il dispositivo ha richiesto a Capgo il bundle associato al suo canale |
download_manifest_start, download_manifest_complete | Download delta iniziato / terminato (per bundle caricati con file delta) |
download_zip_start, download_zip_complete | Download archivio Zip iniziato / terminato |
download_10 … download_90 | Milestone del download |
download_0 | Indicatore 0% per il primo evento di avanzamento |
download_complete | Bundle scaricato interamente |
set | Bundle pronto per il prossimo avvio |
reset | Dispositivo tornato al bundle integrato |
delete | Bundle rimosso dallo storage locale |
uninstall | Rilevata disinstallazione app |
app_moved_to_foreground, app_moved_to_background | Eventi lifecycle app registrati da SDK |
ping | Health check/heartbeat dal dispositivo |
setChannel, getChannel | Channel sovrascritto o recuperato tramite chiamata SDK |
Nuovo quick fix per policy-block / throttle
Sezione intitolata “Nuovo quick fix per policy-block / throttle”| Code | Perché succede | Cosa fare ora |
|---|---|---|
invalidIp | Capgo ha rilevato traffico che sembra provenire da bot (IP di Google/infrastruttura cloud). | Ignora se riguarda utenti reali; riprova da dispositivi reali e reti normali, o controlla dopo un po'. |
needPlanUpgrade | Organization reached plan/device limit. | Aggiorna il piano nella dashboard o attendi il prossimo ciclo di fatturazione. |
semver_error | La versione dell'app nativa nella config manca o non è un semver valido (x.y.z). | Imposta plugins.CapacitorUpdater.version a un semver valido, quindi verificalo nella tester SemVer e rifai la build dell'app. |
disablePlatformIos | iOS è disabilitato nella policy del canale. | Se è successo per errore, abilita iOS in quel canale e ripubblica il routing. Se invece blocchi iOS di proposito in questo track, lascialo disabilitato e sposta le build iOS su un canale separato. |
disablePlatformAndroid | Android è disabilitato nella policy del canale. | Se è successo per errore, abilita Android in quel canale e ripubblica il routing. Se invece blocchi Android di proposito in questo track, lascialo disabilitato e sposta le build Android su un canale separato. |
disableAutoUpdate | La modalità auto-update del canale blocca questo tipo di update. | Modifica la policy di auto-update del canale (major/minor/patch/metadata/none) per consentire il rollout desiderato. |
disableAutoUpdateUnderNative | Il canale è impostato per bloccare gli update precedenti alla baseline del dispositivo. | Pubblica una versione pari o superiore alla baseline nativa, oppure disabilita la protezione sulle versioni native precedenti. |
disableAutoUpdateMetadata | Il canale richiede min_update_version metadata e l'app è più vecchia. | Imposta min_update_version per il bundle o la release target da una versione nativa più recente. |
disableAutoUpdateToMajor | Il canale blocca i salti di versione major. | Mantieni le versioni major nella stessa strategia del canale, oppure consenti i salti major per questa track. |
disableAutoUpdateToMinor | Il canale blocca i salti di versione minor. | Mantieni le versioni minor nella stessa strategia del canale, oppure consenti i salti minor per questa track. |
disableAutoUpdateToPatch | Il canale impedisce i salti di patch-level in questo flusso. | Allinea il ritmo dei tuoi rilasci o abilita i patch jump nella policy del canale per questo track. |
disableEmulator | Gli aggiornamenti da emulatore non sono consentiti per questo canale. | Se è stato un errore, abilita gli aggiornamenti da emulatore in un canale di test dove validi gli emulatori. Se è intenzionale, mantieni questo canale bloccato per gli emulatori e usa un altro canale per le build da emulatore. |
disableDevBuild | Le build dev sono bloccate per questo canale. | Se è stato un errore, abilita gli aggiornamenti dev o sposta questo dispositivo su un canale abilitato per dev. Se è intenzionale, mantieni questo canale limitato alle sole build di release. |
disableProdBuild | Una build del dispositivo in modalità production chiamata /updates, mentre il tuo canale l'ha bloccata. | Se è stato un errore, consenti gli aggiornamenti di produzione in quel channel e ripubblica. Se è intenzionale, mantieni la restrizione e invia i build di produzione al channel/build corretto. |
cannotGetBundle | Capgo non è riuscito a creare un URL di download valido per il bundle selezionato. | Ricarica il bundle (con --delta se vuoi i file delta) e controlla le impostazioni del bundle R2/pubblico. |
cannotUpdateViaPrivateChannel | L'app ha tentato di passare a un channel privato che non consente l'auto-assegnazione. | Abilita allow_device_self_set sul channel o passa a un channel pubblico/consentito. |
channelMisconfigured | Regola di auto-aggiornamento del canale: dati obbligatori mancanti (version_number senza min_update_version). | Completa la configurazione mancante per quella regola o passa a una modalità di auto-update più semplice. |
missingBundle | Il bundle non ha un payload scaricabile (mancante external_url/r2_path e nessun file delta). | Ricostruisci/ri-carica la versione e verifica che il bundle contenga file reali. |
NoChannelOrOverride | Nessun canale corrisponde a questo dispositivo (nessun default cloud + nessun fallback config + nessun override). | Imposta un canale predefinito nel dashboard o mantieni un test defaultChannel in quella build. |
rateLimited | Troppe chiamate update/canale in poco tempo (spesso render-loop setChannel/getChannel). | Smetti di chiamare nel render. Chiama solo su azione utente. Usa defaultChannel nella capacitor.config. |
keyMismatch | The app and bundle encryption key IDs differ (device_key_id vs bundle_key_id). | Nella console, confronta gli ID delle chiavi del dispositivo e del bundle. Se differiscono, pubblica con la stessa chiave e la versione corrispondente di CLI/plugin; la codifica della chiave può variare tra le versioni. |
disableDevice | Un telefono/tablet reale è stato bloccato perché questo channel è configurato per bloccare i dispositivi reali. | Se è un errore, attiva gli aggiornamenti su dispositivo reale in quel channel. Se è intenzionale, tienilo bloccato e indirizza i dispositivi reali a un altro channel. |
disablePlatformElectron | Electron è bloccato in questo channel. | Se è un errore, abilita Electron in questo channel e ripubblica il routing. Se è intenzionale, tienilo bloccato e indirizza gli utenti Electron su un channel dedicato. |
customIdBlocked | È stato inviato un ID dispositivo personalizzato, ma questa app non accetta ID personalizzati. | Disattiva l'invio di ID personalizzati o abilita gli ID personalizzati solo se il tuo workflow lo richiede. |
blocked_by_server_url | L'app ha server.url configurato, quindi Capacitor serve l'URL remoto invece dei file locali. | Rimuovi/svuota server.url per le build di produzione e mantenere i payload degli update locali. |
backend_refusal | L'updater è v4, che il backend non accetta più. | Aggiorna il plugin/CLI a v5+ (preferisci v8), con Capacitor v5+, quindi ricostruisci e ripubblica i metadati del bundle. |
| Blocchi di configurazione o policy |
| Code(s) | Perché l'update è stato bloccato |
|---|---|
disableAutoUpdate, disableAutoUpdateToMajor, disableAutoUpdateToMinor, disableAutoUpdateToPatch, disableAutoUpdateMetadata, disableAutoUpdateUnderNative | La strategia del channel lo vieta salto semver |
disablePlatformIos, disablePlatformAndroid | La piattaforma è disabilitata sul channel |
disableDevBuild, disableEmulator | Build di dev o emulatori non consentiti |
disableProdBuild, disableDevice, disablePlatformElectron | Build di produzione, dispositivi reali o Electron sono bloccati per questo channel. |
customIdBlocked | I device ID personalizzati non sono accettati per questa app. |
cannotUpdateViaPrivateChannel, NoChannelOrOverride, channelMisconfigured | Selezione o override del channel fallito |
missingBundle, cannotGetBundle | Il canale punta a un bundle che Capgo non può fornire |
needPlanUpgrade | L'org ha raggiunto il limite di piano/dispositivi |
Errori di download, integrità o installazione
| Code(s) | Significato |
|---|---|
download_fail | Download del bundle non riuscito (errore di rete o di risposta) |
download_manifest_file_fail, download_manifest_checksum_fail, download_manifest_brotli_fail | Impossibile recuperare o validare un file delta |
checksum_fail, checksum_required | Controllo di integrità non riuscito o checksum mancante |
unzip_fail, directory_path_fail, canonical_path_fail, windows_path_fail | Validazione del file system o di unzip non riuscita |
decrypt_fail | Decrittazione non riuscita (bundle crittografato) |
update_fail | Bundle installato ma l'app non ha mai fatto la chiamata notifyAppReady(); rollback attivato |
download_zip_* senza eventi successivi set | Download completato ma fase di installazione mai terminata |
Eventi runtime / piattaforma
Sezione intitolata “Eventi runtime / piattaforma”| Code(s) | Significato |
|---|---|
app_crash, app_crash_native | Eventi di crash dai layer JavaScript o runtime nativi. I metadati includono spesso stack, sorgente e informazioni sulla versione attiva. |
app_anr | Android ha segnalato un Application Not Responding. |
app_killed_low_memory, app_killed_excessive_resource_usage | Terminazione del processo dell'app a causa di limiti di memoria o risorse. |
app_initialization_failure, app_memory_warning | Avvio interrotto o pressione di memoria rilevata prima dell'esecuzione normale. |
webview_javascript_error, webview_unhandled_rejection, webview_resource_error, webview_security_policy_violation, webview_unclean_restart, webview_render_process_gone, webview_content_process_terminated | Ciclo di vita della WebView ed errori JS/rendering. Installa Sentry sia nel layer JS che in quello nativo per catturare stack trace, contesto di sessione/dispositivo e URL/stato per correzioni più rapide. |
os_version_changed, native_app_version_changed | Versione OS o app nativa modificata; utile a distinguere gli effetti del rollout a livello di piattaforma dal comportamento del web bundle. |
➡️ Serve una guida più dettagliata per code? Consulta Riferimento completo ai log Code e guida alla debug.
Ottenere maggiori dettagli su un log
Sezione intitolata “Ottenere maggiori dettagli su un log”Se fai clic su una voce di log specifica, di solito verrai reindirizzato alla pagina del dispositivo. Questo ti consente di visualizzare l'intero storico per quel dispositivo specifico, il che può essere molto utile per diagnosticare problemi specifici del dispositivo o per comprenderne il percorso di aggiornamento.
Continua da Logs
Sezione intitolata “Continua dai log”Se stai usando Log per pianificare le operazioni della dashboard e di API, collegalo a Panoramica API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi API per i dettagli di implementazione delle chiavi API, Dispositivi per i dettagli di implementazione in Devices, e Bundle per il dettaglio di implementazione in Bundles.