Debug

Capire i log cloud

Se ricevi un rifiuto cloud code e ti servono procedure di risoluzione più dettagliate, consulta Problemi comuni di aggiornamento.

I log di Capgo possono includere i metadati dell'evento. Nella dashboard, filtra per l'azione in snake_case code e clicca sulla cella dei metadati per copiare l'intero payload JSON. I metadati sono utilissimi per crash ed eventi WebView, poiché possono includere il messaggio di errore, l'URL sorgente, riga e colonna, lo stato del processo, la pressione di memoria o la causa specifica della piattaforma. I log più vecchi potrebbero ancora mostrare alias legacy in camelCase tra parentesi.

Ogni titolo di sezione corrisponde all'azione code mostrata nella tabella dei log della console, così puoi collegarti direttamente alla sezione.

Limiti del piano e risposte standard

Rifiuti del backend relativi a fatturazione, throttling o stati non di errore.

InvalidIp

Cosa significa

Capgo ha rilevato traffico che sembra provenire da Google o da infrastrutture cloud. Gli update con meno di quattro ore di vita vengono ignorati, così il traffico bot non viene conteggiato come dispositivi fatturabili.

Cosa fare

Ignora questo errore per gli utenti reali. Riprova da reti normali e dispositivi reali, oppure attendi e ricontrolla più tardi.

provider_infrastructure_request_blocked

Cosa significa

La tua app è configurata per bloccare le richieste provenienti dai range di IP noti dei datacenter di Google e Apple. La protezione si applica ai controlli degli update, alle statistiche e alle richieste channel-self; pertanto, probe ospitate in cloud e runner del provider potrebbero ricevere questa risposta anche se la configurazione dell'app è valida.

Cosa fare

Riprova da un dispositivo fisico su una rete utente standard. Se il traffico proveniente dal provider è intenzionale, disabilita temporaneamente Blocca le richieste all'infrastruttura del provider nella scheda Informazioni dell'app, quindi riabilitala dopo il test. Le nuove app hanno questa impostazione attiva di default; le app esistenti mantengono l'impostazione precedente fino a modifica.

needPlanUpgrade

Cosa significa

La tua organizzazione ha raggiunto il limite del piano o dei dispositivi. Il dispositivo non riceverà aggiornamenti finché non effettuerai l'upgrade o non inizierà il prossimo ciclo di fatturazione.

Cosa fare

Fai l'upgrade del piano nella dashboard o attendi il prossimo ciclo di fatturazione.

noNew

Cosa significa

Il dispositivo ha già l'ultimo bundle disponibile per il suo canale. È uno stato normale, non un errore.

rateLimited

Cosa significa

Il dispositivo ha inviato troppe richieste di update o di canale in un breve lasso di tempo.

Cosa fare

Evita di chiamare le API di update all'interno dei render loop. Chiama setChannel / getChannel solo in risposta ad azioni dell'utente e imposta defaultChannel nella capacitor.config.

Formato versione

Rifiuti del backend causati da metadati della versione nativa non validi.

semver_error

Cosa significa

La versione dell'app nativa nel config è mancante o non è un semver valido (x.y.z).

Cosa fare

Imposta plugins.CapacitorUpdater.version per un semver valido, verifica in tester SemVer, quindi ricostruisci e reinstalla l'app nativa.

Targeting di piattaforma e build

Rifiuti dal backend quando la policy del canale blocca una piattaforma, un tipo di build o una classe di dispositivi.

disablePlatformIos

Cosa significa

Il dispositivo esegue iOS, ma gli aggiornamenti iOS sono disabilitati per questo canale.

Cosa fare

Abilita iOS nel canale se si tratta di un errore, oppure instrada le build iOS verso un canale dedicato se il blocco è intenzionale.

disablePlatformAndroid

Cosa significa

Il dispositivo esegue Android, ma gli aggiornamenti Android sono disabilitati per questo canale.

Cosa fare

Abilita Android nel canale se è stato un errore, oppure instrada i build Android verso un canale dedicato se il blocco è intenzionale.

disablePlatformElectron

Cosa significa

Il dispositivo esegue Electron, ma gli aggiornamenti Electron sono disabilitati per questo canale.

Cosa fare

Abilita Electron nel canale se è stato un errore, oppure instrada i build Electron verso un canale dedicato se il blocco è intenzionale.

disableDevBuild

Cosa significa

Il dispositivo è un dev build, ma i dev build sono bloccati per questo canale.

Cosa fare

Permetti i dev build in un canale di test, oppure mantieni questo canale solo per il rilascio e sposta i dispositivi dev altrove.

disableProdBuild

Cosa significa

Build di produzione chiamata /updates, ma gli aggiornamenti di produzione sono bloccati per questo canale.

Cosa fare

Abilita gli aggiornamenti di produzione nel canale se è stato un errore, oppure instrada le build di produzione verso il canale corretto.

disableDevice

Cosa significa

Un dispositivo fisico è stato bloccato perché questo canale blocca i dispositivi reali.

Cosa fare

Abilita gli aggiornamenti sui dispositivi reali se è stato un errore, oppure mantieni la restrizione e instrada i dispositivi reali su un altro canale.

disableEmulator

Cosa significa

Il dispositivo è un emulatore, ma gli aggiornamenti per gli emulatori sono disabilitati per questo channel.

Cosa fare

Abilita gli aggiornamenti sull'emulatore in un canale di test, oppure mantieni questo canale bloccato per l'emulatore e usane un altro per la validazione.

Regole di compatibilità auto-update

Rifiuti dal backend quando le regole semver o i metadati bloccano il bundle di destinazione.

disableAutoUpdate

Cosa significa

L'auto-update è disabilitato dalla policy di compatibilità del channel. I metadati includono auto_update con una regola corrispondente come major, minor, patch, metadata, o none.

Cosa fare

Modifica la policy di auto-update del canale per consentire il rollout previsto.

disableAutoUpdateUnderNative

Cosa significa

Il canale contiene un bundle più vecchio della baseline del dispositivo e blocca l'invio di update sotto la versione native.

Cosa fare

Pubblica un bundle uguale o superiore alla baseline native, oppure disabilita la protezione under-native nel canale.

disableAutoUpdateMetadata

Cosa significa

Il canale richiede min_update_version, ma la versione native del dispositivo è inferiore a tale soglia.

Cosa fare

Imposta min_update_version sul bundle o sulla release di una versione native più recente.

disableAutoUpdateToMajor

Cosa significa

Il canale blocca i salti di versione major, ad esempio 1.x.x a 2.x.x.

Cosa fare

Allinea la strategia del canale al tuo piano di rollout major, o permetti i salti major per questo track. Vedi Problemi comuni di aggiornamento.

disableAutoUpdateToMinor

Cosa significa

Il canale blocca i salti di versione minor rispetto alla baseline native del dispositivo (version_build), per esempio 1.2.3 a 1.3.0.

Cosa fare

Allinea la strategia dei canali al tuo piano di rollout, oppure permetti salti di versione minori per questo track.

disableAutoUpdateToPatch

Cosa significa

Il canale blocca i cambiamenti a livello di patch mantenendo lo stesso MAJOR.MINOR.PATCH prefisso; sono consentiti solo i cambiamenti del suffisso.

Cosa fare

Allinea la cadenza dei rilasci alla policy del canale, o permetti salti di patch per questo track.

Configurazione del canale

Rifiuti del backend causati da una configurazione del canale mancante o incompatibile.

cannotUpdateViaPrivateChannel

Cosa significa

Il dispositivo ha tentato di associarsi a un canale privato che non permette l'auto-assegnazione (allow_device_self_set è false) e il canale non è pubblico.

Cosa fare

Abilita allow_device_self_set sul canale o sposta il dispositivo su un canale pubblico o consentito.

channelMisconfigured

Cosa significa

Il canale utilizza disable_auto_update: "version_number" ma il bundle min_update_version è null, quindi Capgo non può decidere quali dispositivi debbano aggiornarsi.

Cosa fare

Completa la configurazione mancante per quella regola o passa a una modalità di auto-update più semplice.

NoChannelOrOverride

Cosa significa

Nessun canale predefinito è configurato e il dispositivo non ha un override del canale.

Cosa fare

Imposta un canale predefinito nella dashboard o configura defaultChannel nella build.

Consegna e crittografia del bundle

Rifiuti del backend quando Capgo non riesce a servire o decriptare il bundle.

cannotGetBundle

Cosa significa

Capgo non è riuscito a generare un URL di download firmato valido e non era disponibile un manifest di fallback.

Cosa fare

Ricarica il bundle, rigenera i manifest e verifica le impostazioni di R2 o del bundle pubblico.

missingBundle

Cosa significa

Il bundle assegnato al canale non contiene contenuti scaricabili: nessun external_url, nessun r2_path, non una versione integrata, e nessuna voce nel manifest.

Cosa fare

Ricrea e carica nuovamente la versione, quindi conferma che il bundle contenga file reali.

keyMismatch

Cosa significa

La chiave pubblica di crittografia del dispositivo non corrisponde a quella usata per il bundle. I metadati possono includere device_key_id, bundle_key_id, e version.

Cosa fare

Confronta gli ID delle chiavi di dispositivo e del bundle nella console. Pubblica con la stessa chiave e versioni CLI/plugin corrispondenti.

Configurazione app e client legacy

Rifiuti dal backend causati dalla configurazione dell'app o da versioni dell'updater non supportate.

customIdBlocked

Cosa significa

L'app ha inviato un ID dispositivo personalizzato, ma questa app non accetta ID custom, quindi l'ID viene ignorato.

Cosa fare

Smetti di inviare ID personalizzati, oppure attivali solo quando il tuo workflow lo richiede.

blocked_by_server_url

Cosa significa

server.url è impostato nella configurazione di Capacitor, quindi la WebView carica un URL remoto invece dei file del bundle locale. Gli Capgo live updates richiedono file locali e server.url è sconsigliato in produzione.

Cosa fare

Rimuovi o svuota server.url per i build di produzione e mantenere i payload di code locali. Questo code può apparire come un rifiuto del backend o come uno stato del dispositivo.

backend_refusal

Cosa significa

Il plugin updater è la v4, che il backend non accetta più.

Cosa fare

Aggiorna il plugin e CLI alla v5+ (preferibilmente v8) con Capacitor v5+, ricostruisci e pubblica nuovamente i metadati del bundle.

Ciclo di vita dell'update

Eventi lato device per il normale flusso di update, attivazione e rollback.

ping

Cosa significa

Azione di test interna usata per verificare la pipeline delle stats.

get

Cosa significa

Capgo ha inviato le informazioni di download per una nuova versione al device.

set

Cosa significa

Un bundle è stato attivato sul dispositivo.

set_fail

Cosa significa

L'attivazione di un bundle sul dispositivo è fallita.

Cosa fare

Controlla i log nativi con npx @capgo/cli@latest app debug e verifica l'integrità del bundle, i percorsi e il notifyAppReady flow.

reset

Cosa significa

Il dispositivo è tornato al bundle predefinito.

delete

Cosa significa

Un bundle è stato eliminato sul dispositivo.

Errori di download e installazione

Eventi lato dispositivo per il progresso del download, la validazione dell'archivio e gli errori di installazione.

download_0

Cosa significa

La sequenza di download è iniziata allo 0% di progresso.

download_10

Cosa significa

Un nuovo bundle è stato scaricato — progresso al 10%.

download_20

Cosa significa

Un nuovo bundle è stato scaricato — progresso al 20%.

download_30

Cosa significa

Un nuovo bundle è stato scaricato — progresso al 30%.

download_40

Cosa significa

Un nuovo bundle è stato scaricato — progresso al 40%.

download_50

Cosa significa

Un nuovo bundle è stato scaricato — progresso al 50%.

download_60

Cosa significa

Un nuovo bundle è stato scaricato — progresso al 60%.

download_70

Cosa significa

Un nuovo bundle è stato scaricato — progresso al 70%.

download_80

Cosa significa

Un nuovo bundle è stato scaricato — progresso all'80%.

download_90

Cosa significa

Un nuovo bundle è stato scaricato — progresso al 90%.

download_complete

Cosa significa

Il download del bundle è terminato con successo.

download_manifest_start

Cosa significa

Il dispositivo ha iniziato a scaricare il manifest dell'update.

download_manifest_complete

Cosa significa

Il dispositivo ha terminato il download del manifest dell'update.

download_zip_start

Cosa significa

Il dispositivo ha iniziato a scaricare l'archivio del bundle.

download_zip_complete

Cosa significa

Il dispositivo ha terminato il download dell'archivio del bundle.

download_manifest_file_fail

Cosa significa

Il download di una voce del manifest è fallito. version_name utilizza version:fileName per identificare l'asset.

Cosa fare

Risolvi l'asset mancante o bloccato, rigenera il manifest e fai nuovamente l'upload del bundle.

download_manifest_checksum_fail

Cosa significa

La validazione del checksum del file manifest è fallita.

Cosa fare

Carica nuovamente il bundle con una versione CLI aggiornata e verifica i checksum del manifest.

download_manifest_brotli_fail

Cosa significa

La decompressione Brotli di un file manifest è fallita.

Cosa fare

Verifica le impostazioni di compressione e carica nuovamente gli asset interessati.

download_fail

Cosa significa

Il download del bundle è fallito.

Cosa fare

Controlla la connettività di rete, la scadenza della signed URL, la raggiungibilità della CDN e lo storage del dispositivo.

update_fail

Cosa significa

Il bundle è stato installato ma l'app non è mai stata chiamata notifyAppReady, quindi Capgo è tornato alla versione precedente.

Cosa fare

Chiama notifyAppReady() dopo il bootstrapping dell'app. Testo del log Native notifyAppReady was not called, roll back current bundle corrisponde a questo code.

checksum_fail

Cosa significa

Il bundle scaricato ha fallito la validazione del checksum. Cause comuni: mismatch CRC32 vs SHA256 da un vecchio upload CLI, o mismatch della chiave di cifratura su plugin datati che segnalano un errore di decifratura come errore di checksum.

Cosa fare

Effettua nuovamente l'upload con un CLI/plugin aggiornato (SHA256). Se usi la crittografia, verifica che la chiave pubblica dell'app corrisponda alla chiave di upload, o passa al plugin 8.3.0+ per errori keyMismatch espliciti.

decrypt_fail

Cosa significa

Il bundle scaricato non è stato possibile decriptarlo.

Cosa fare

Verifica le chiavi di cifratura e carica nuovamente il bundle con la coppia di chiavi corrispondente.

windows_path_fail

Cosa significa

Lo zip contiene percorsi non validi in stile Windows.

Cosa fare

Ricrea il bundle con percorsi Unix o pulisci i percorsi dell'archivio prima dell'upload.

canonical_path_fail

Cosa significa

I percorsi dei file all'interno dello zip non sono canonici.

Cosa fare

Fix archive path generation before upload.

directory_path_fail

Cosa significa

Lo zip contiene percorsi di directory non validi.

Cosa fare

Correggi la struttura dell'archivio prima dell'upload.

unzip_fail

Cosa significa

Il dispositivo non è riuscito a scompattare il bundle scaricato.

Cosa fare

Verifica l'integrità dell'archivio e il tipo di compressione supportato.

low_mem_fail

Cosa significa

Il download è fallito perché il dispositivo ha esaurito la memoria.

Cosa fare

Riduci la dimensione del bundle o riprova su un dispositivo con più memoria libera.

Stato dell'app ed eventi WebView

Diagnostica su crash, memoria e WebView lato dispositivo. Controlla sempre il JSON dei metadati nella dashboard.

app_moved_to_background

Cosa significa

L'app è passata in background.

app_moved_to_foreground

Cosa significa

L'app è tornata in foreground.

app_crash

Cosa significa

Crash del layer JavaScript o Capacitor. I metadati possono includere messaggio, stack, sorgente e il contesto del bundle attivo.

Cosa fare

Ispeziona i metadati e i log nativi. Combina il reporting degli errori JS e nativi (ad esempio Sentry) per individuare il percorso code che fallisce.

app_crash_native

Cosa significa

Crash della piattaforma Native. I metadati possono includere piattaforma, motivo, stack e dettagli del processo.

Cosa fare

Usa i crash log di Xcode o Logcat e correlali al bundle attivo tramite i metadati.

app_anr

Cosa significa

Evento Android Application Not Responding.

Cosa fare

Analizza i trace ANR in Logcat e riduci i blocchi sul main thread dopo gli update.

app_killed_low_memory

Cosa significa

L'OS ha terminato l'app a causa della pressione sulla memoria.

Cosa fare

Riduci l'uso della memoria dopo l'attivazione dell'update e analizza i metadati per i segnali di memoria disponibili.

app_killed_excessive_resource_usage

Cosa significa

Il sistema operativo ha chiuso l'app per uso eccessivo delle risorse.

Cosa fare

Ispeziona i metadati per il tipo di risorsa o la causa della piattaforma.

app_initialization_failure

Cosa significa

L'Updater o l'avvio sono falliti prima che il runtime fosse pronto.

Cosa fare

Ispeziona i metadati dello step fallito e il relativo messaggio di errore.

app_memory_warning

Cosa significa

Avviso di memoria su iOS.

Cosa fare

Analizza il contesto di memoria nei metadati e riduci il picco di utilizzo dopo gli update.

webview_javascript_error

Cosa significa

Errore JavaScript non gestito nella WebView. I metadati possono includere messaggio, URL sorgente, riga, colonna e stack trace.

Cosa fare

Installa un sistema di error reporting nei layer JS e nativi per catturare l'esatta riga che fallisce in produzione.

webview_unhandled_rejection

Cosa significa

Promise rejection non gestita nella WebView.

Cosa fare

Intercetta i fallimenti asincroni con il reporting degli errori JS e nativi.

webview_resource_error

Cosa significa

Il caricamento di una risorsa WebView è fallito.

Cosa fare

Usa l'URL dei metadati e i dettagli dello stato per risolvere asset o regole di rete errati.

webview_security_policy_violation

Cosa significa

La Content Security Policy ha bloccato una risorsa.

Cosa fare

Regola la CSP tramite la direttiva metadata e i dettagli dell'URI bloccato.

webview_unclean_restart

Cosa significa

La sessione WebView precedente non si è chiusa correttamente; potrebbe indicare crash loop dopo un aggiornamento.

Cosa fare

Correlazione tra eventi di crash, errori WebView prima e dopo il riavvio.

webview_render_process_gone

Cosa significa

Il processo di rendering di Android WebView è terminato.

Cosa fare

Ispeziona i segnali di crash del renderer nei metadati e nei log nativi.

webview_content_process_terminated

Cosa significa

Processo del contenuto della WebView di iOS terminato.

Cosa fare

Ispeziona il bundle attivo e l'URL della pagina dai metadati.

Contesto di ambiente e canale

Eventi di contesto lato device per correlare il comportamento degli update con OS, versione nativa o cambi di canale.

os_version_changed

Cosa significa

Device OS version changed between checks.

native_app_version_changed

Cosa significa

La versione nativa dell'app store è cambiata, aiutando a distinguere tra modifiche native e del web bundle.

getChannel

Cosa significa

Il dispositivo ha richiesto il suo canale attuale.

setChannel

Cosa significa

Un canale è stato impostato correttamente per il dispositivo.

uninstall

Cosa significa

L'app è stata disinstallata o i dati Capgo sono stati cancellati.

Stato del bundle

• SUCCESS: installazione bundle completata
• ERROR: installazione o download falliti
• PENDING: Download completato, in attesa di rilascio
• DELETED: Bundle eliminato, ancora presente nelle stats
• DOWNLOADING: Download di un bundle in corso

Analizzare i log del dispositivo

Comando di debug

È disponibile un comando di debug per gli utenti Capgo cloud.

npx @capgo/cli@latest app debug

Questo ti permetterà di controllare tutti gli eventi dell'app e trovare una soluzione se gli update non vengono eseguiti.

Log nativi iOS

per trovare i log su Xcode

Ottenere il Device Log in Xcode

Log nativi Android

per trovare i log su Android Studio

Visualizzare i log con Logcat

Mappatura delle frasi dei log nativi

• Failed to download from corrisponde a download_fail
• notifyAppReady was not called, roll back current bundle corrisponde a update_fail

Trovare il bundle scaricato sul dispositivo

iOS

Per il debug su iOS, devi scaricare l'app sul tuo computer; puoi farlo in questo modo:

Xcode ha una funzione integrata per ispezionare il file system delle app installate dagli sviluppatori su un dispositivo iOS.

To achieve this:

• Collega il dispositivo al Mac e seleziona Window > Devices nella barra dei menu di Xcode.
• Seleziona il tuo dispositivo nel pannello di sinistra sotto la sezione Devices.
• Verrà visualizzato un elenco delle app installate dagli sviluppatori su quel dispositivo.
• Seleziona l'app che vuoi ispezionare e poi clicca sull'icona con i 3 puntini verso il fondo dello schermo.
• Qui puoi visualizzare il file system corrente scaricando uno snapshot.

Selezionando Download Container… scaricherai ed esporterai uno snapshot del file system come file .xcappdata consultabile.

Fai clic destro su questo file e seleziona Show Package Contents per aprire la cartella.

Apri la cartella dei dati dell'app: dovresti vedere diverse sottocartelle come Documents, Library, tmp, ecc.

Troverai quindi una versione in 2 cartelle:

library/NoCloud/ionic_built_snapshots è necessario dopo il riavvio dell'app

e documents/versions per l'hot reload

Android

Per il debug su Android, devi accedere al dispositivo tramite Android Studio:

• Vai su View > Tool Windows > Device File Explorer, oppure clicca sul pulsante Device File Explorer nella barra degli strumenti.
• Seleziona un dispositivo dal menu a discesa.
• Apri il percorso data/data/APP_NAME/ dove APP_NAME è l'ID della tua app.

Poi cerca la versions cartella per vedere tutte le versioni

Lo sapevi?

Su Android tutte le versioni sono salvate in una sola cartella, a differenza di iOS dove devono essere duplicate in due posizioni.

Analizzare i crash log di produzione su iOS

Come esaminare i crash log della tua app

Continua da Debugging

Se stai usando Debug per pianificare il lavoro sui plugin nativi, collegalo a Usando @capgo/capacitor-updater per la funzionalità nativa in Usando @capgo/capacitor-updater, Directory dei plugin di Capgo per il workflow del prodotto nella Capgo Plugin Directory, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins di Capgo, Aggiunta o aggiornamento dei plugin per i dettagli su come aggiungere o aggiornare i plugin, e Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Alternative ai plugin Ionic Enterprise.