Log

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

La sottoscheda Logs 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 problemi in un percorso di aggiornamento e capire come i dispositivi interagiscono con Capgo. Apri un'app, seleziona Log, quindi scegli la Log sottoscheda.

Scheda Raw Logs

L'interfaccia Raw Logs include:

1. Sottoscheda Logs — il controllo di navigazione per le singole righe di log.
2. Pulsante Reload — aggiorna la lista dei log con gli ultimi dati.
3. Filtri per intervallo di tempo e azione — filtra lo stream degli eventi per tempo e azione.

Ogni riga mostra:

• Timestamp (UTC)
• ID dispositivo
• Azione code (cosa è successo)
• Nome versione (bundle o builtin)

Click a row to jump to the device detail page for its full history.

Filtro per intervallo di date

Puoi filtrare i log per un periodo specifico usando il date picker:

Filtro per intervallo di date

1. Preset rapidi - Seleziona intervalli comuni: ultime 1h, 3h, 6h o 12h
2. Ora di inizio - Imposta un orario di inizio personalizzato
3. Ora di fine - Imposta un orario di fine personalizzato
4. Calendario - Seleziona date specifiche tramite la vista calendario

Clicca su “Select” per applicare l'intervallo scelto, o su “Cancel” per chiudere il picker.

Filtro per tipo di azione

Il menu a discesa Actions ti permette di filtrare i log per tipo di evento:

Filtro Actions

I filtri per azione disponibili sono:

• Heartbeat del dispositivo - Check periodici dello stato dei dispositivi
• Richiesta di eliminazione versione - Quando una versione del bundle viene eliminata
• Reset alla versione predefinita - Quando un dispositivo torna al bundle integrato
• Versione installata con successo - Installazione del bundle riuscita
• Nuova versione inviata al dispositivo - Quando Capgo invia un aggiornamento a un dispositivo
• Installazione della versione fallita - Quando l'installazione del bundle fallisce

Usa la barra di ricerca in alto per trovare rapidamente tipi di azione specifici. Puoi selezionare più azioni per mostrare i log corrispondenti a uno qualsiasi dei tipi scelti.

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	Channel policy blocked a jump to 2.x
2025-01-14 10:05:05	B9C8D7	rateLimited	integrata	Limite di richieste raggiunto dal dispositivo; SDK attende il riavvio

Esempi di scenari di log

Per aiutarti a interpretare i log, ecco alcuni esempi che mostrano i percorsi reali di aggiornamento dei dispositivi:

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

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

When an update fails and the device rolls back:

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

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

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 effettuerai l'upgrade o non scadrà il ciclo di fatturazione

Azione richiesta: Passa a un piano superiore o attendi il prossimo ciclo di fatturazione.

Configurazione del canale che blocca gli aggiornamenti

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ò 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	Build di sviluppo rilevata e il canale blocca le build dev

Azione richiesta: Si tratta di protezioni intenzionali. Se vuoi consentire questi update, modifica il tuo impostazioni canale.

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

Code	Perché accade	Cosa fare ora
invalidIp	Capgo ha rilevato traffico sospetto (IP di Google o infrastrutture cloud).	Ignora se riguarda utenti reali; riprova da dispositivi fisici e reti normali, o controlla più tardi.
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 è mancante o non è un semver valido (x.y.z).	Imposta plugins.CapacitorUpdater.version usa un semver valido, quindi verifica nella Tester SemVer e ricostruisci l'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 major version.	Mantieni le major version nella stessa strategia del canale, oppure permetti i salti per questo track.
disableAutoUpdateToMinor	Il canale blocca i salti di minor version.	Mantieni le minor version nella stessa strategia del canale, oppure permetti i salti per questo track.
disableAutoUpdateToPatch	Il canale blocca i salti di patch-level per questo flusso.	Allinea la cadenza dei rilasci o abilita i salti di patch nella policy del canale per questo track.
disableEmulator	Gli aggiornamenti per emulator non sono consentiti per questo canale.	Se è un errore, abilita gli aggiornamenti per emulator in un canale di test per la validazione. Se è intenzionale, mantieni questo canale bloccato per gli emulator e usa un altro canale per le build degli emulator.
disableDevBuild	Le build di dev sono bloccate per questo canale.	Se è un errore, abilita gli aggiornamenti di dev o sposta il dispositivo su un canale abilitato per dev. Se è intenzionale, mantieni questo canale limitato solo alle build di release.
disableProdBuild	Una build del dispositivo in modalità production chiamata /updates, mentre il tuo canale l'ha bloccata.	Se è stato un errore, abilita gli update in produzione su quel channel e ripubblica. Se è intenzionale, mantieni la restrizione e invia i build di produzione al channel corretto.
cannotGetBundle	Capgo non è riuscito a generare un URL di download valido per il bundle selezionato.	Carica nuovamente il bundle (con --delta se desideri i file delta) e controlla le impostazioni di R2/public bundle.
cannotUpdateViaPrivateChannel	L'app ha tentato di passare a un channel privato che non permette l'auto-assegnazione.	Abilita allow_device_self_set sul channel o passa a un channel pubblico/consentito.
channelMisconfigured	La regola di auto-update del channel manca di dati necessari (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 (mancano external_url/r2_path e i file delta).	Ricrea/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 di default nella dashboard o mantieni un test defaultChannel in quella build.
rateLimited	Troppe chiamate a update/channel in breve tempo (spesso in un render-loop) setChannel/getChannel).	Smetti di chiamarle nel render. Chiamale solo su azione dell'utente. Usa defaultChannel nella capacitor.config.
keyMismatch	Gli ID della chiave di cifratura dell'app e del bundle differiscono (device_key_id vs bundle_key_id).	Nella console, confronta gli ID delle chiavi di dispositivo e bundle. Se differiscono, pubblica con la stessa chiave e la versione CLI/plugin corrispondente; la codifica della chiave può variare tra le versioni.
disableDevice	Un telefono/tablet reale è stato bloccato perché questo canale è impostato per bloccare i dispositivi reali.	Se accidentale, abilita gli update per dispositivi reali in quel canale. Se intenzionale, mantieni il blocco e instrada i dispositivi reali su un altro canale.
disablePlatformElectron	Electron è bloccato in questo canale.	Se è un errore, abilita Electron in questo canale e ripubblica il routing. Se è intenzionale, mantienilo bloccato e reindirizza gli utenti Electron a un canale dedicato.
customIdBlocked	È stato inviato un device ID personalizzato, ma questa app non accetta ID custom.	Disabilita l'invio di ID personalizzati o abilita gli ID custom solo se richiesto dal tuo workflow.
blocked_by_server_url	L'app ha server.url configurato, quindi Capacitor serve l'URL remoto invece dei file locali.	Rimuovi/pulisci server.url per le build di produzione e mantieni i payload degli update locali.
backend_refusal	L'updater è v4, che non è più accettato dal backend.	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ò servire
needPlanUpgrade	L'organizzazione ha raggiunto il limite del piano/dispositivo

Errori di download / integrità / installazione

Code(s)	Significato
download_fail	Download del bundle fallito (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 integrità fallito o checksum mancante
unzip_fail, directory_path_fail, canonical_path_fail, windows_path_fail	Validazione del file system o dell'unzip fallita
decrypt_fail	Decrittazione fallita (bundle criptato)
update_fail	Bundle installato ma l'app non è stata chiamata notifyAppReady(); rollback attivato
download_zip_* senza successivi set	Download completato ma la fase di installazione non è mai terminata

Eventi Runtime / piattaforma

Code(s)	Significato
app_crash, app_crash_native	Eventi di crash dai layer JavaScript o native. I metadati includono spesso stack, sorgente e info 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 per limiti di memoria o risorse.
app_initialization_failure, app_memory_warning	L'avvio è stato interrotto o è stata rilevata pressione sulla memoria prima del runtime 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 WebView ed errori JS/rendering. Installa Sentry sia nei layer JS che native per catturare stack trace, contesto sessione/device e URL/stato per fix più rapidi.
os_version_changed, native_app_version_changed	Versione OS o app nativa cambiata; aiuta a distinguere gli effetti del rollout a livello di piattaforma dal comportamento del web bundle.

➡️ Ti serve una guida code più approfondita? Vedi Riferimento completo ai log Code e guida al debugging.

Ottenere maggiori dettagli su un log

Se clicchi su una specifica voce di log, verrai solitamente indirizzato alla pagina del dispositivo. Questo ti permette di vedere la cronologia completa di quel dispositivo, utile per diagnosticare problemi specifici o analizzare il suo percorso di aggiornamento.

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.