Debugging

Comprendere i log in cloud

Se ricevi un rifiuto cloud da code e hai bisogno di guide dettagliate per la risoluzione, 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 i crash e gli eventi WebView, poiché possono includere il messaggio di errore, l'URL sorgente, riga e colonna, lo stato del processo, la pressione della 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.

Limiti del piano e risposte normali

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 aggiornamenti effettuati da meno di quattro ore vengono ignorati, in modo che il traffico bot non venga conteggiato tra i 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 Google e Apple. La protezione si applica ai controlli degli update, alle statistiche e alle richieste channel-self; pertanto, probe cloud-hosted 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 dell'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 le 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.

Target 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 le 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 le build Electron verso un canale dedicato se il blocco è intenzionale.

disableDevBuild

Cosa significa

Il dispositivo è una dev build, ma le dev build sono bloccate per questo canale.

Cosa fare

Permetti le 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 è 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 su dispositivi reali se è 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 su emulatore in un canale di test, oppure mantieni questo canale bloccato per gli emulatori 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 dei canali 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 del canale al tuo piano di rollout, o permetti salti di versione minor 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 dal 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 devono 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 può 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 l'app non accetta ID custom, quindi l'ID viene ignorato.

Cosa fare

Smetti di inviare ID personalizzati, o attivali solo se 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 le 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%.

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'aggiornamento.

download_manifest_complete

Cosa significa

Il dispositivo ha terminato di scaricare il manifest dell'aggiornamento.

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

Non è stato possibile scaricare una voce del manifest. version_name usa version:fileName per identificare l'asset.

Cosa fare

Correggi l'asset mancante o bloccato, rigenera il manifest e fai di nuovo 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 ricarica gli asset interessati.

download_fail

Cosa significa

Il download del bundle è fallito.

Cosa fare

Controlla la connettività di rete, la scadenza dell'URL firmato, la raggiungibilità della CDN e lo spazio sul dispositivo.

update_fail

Cosa significa

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

Cosa fare

Esegui 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

Ricarica con un CLI/plugin aggiornato (SHA256). Se usi la crittografia, verifica che la chiave pubblica dell'app corrisponda a quella 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 crittografia e ricarica il bundle con la coppia di chiavi corrispondente.

windows_path_fail

Cosa significa

Lo zip contiene percorsi non validi per 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 decomprimere il bundle scaricato.

Cosa fare

Verifica l'integrità dell'archivio e la compressione supportata.

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 di 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 nativa. I metadati possono includere dettagli su piattaforma, motivo, stack e 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

Ispeziona 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 controlla i metadati per i segnali di memoria disponibile.

app_killed_excessive_resource_usage

Cosa significa

Il sistema operativo ha terminato l'app per uso eccessivo di risorse.

Cosa fare

Controlla i metadati per il tipo di risorsa o il motivo lato piattaforma.

app_initialization_failure

Cosa significa

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

Cosa fare

Controlla i metadati per il passaggio fallito e il messaggio d'errore.

app_memory_warning

Cosa significa

Avviso di memoria 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

Reiezione di una promise 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

Correla l'evento con i crash e gli errori WebView prima e dopo il riavvio.

webview_render_process_gone

Cosa significa

Il processo renderer di Android WebView è uscito.

Cosa fare

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

webview_content_process_terminated

Cosa significa

iOS WebView content process terminated.

Cosa fare

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

Contesto di ambiente e canale

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

os_version_changed

Cosa significa

Device OS version changed between checks.

native_app_version_changed

Cosa significa

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

getChannel

Cosa significa

Il dispositivo ha interrogato il suo canale attuale.

setChannel

Cosa significa

Il 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: errore durante l'installazione o il download
• PENDING: Download completato, in attesa del rilascio
• DELETED: Bundle eliminato, ancora presente nelle statistiche
• DOWNLOADING: Download di un bundle in corso

Comprendere 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 nell'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 frasi 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, poi seleziona l'icona con i tre puntini vicino al fondo della schermata.
• Qui puoi visualizzare il file system corrente selezionando l'opzione per scaricare 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:

• Clicca su View > Tool Windows > Device File Explorer oppure sul pulsante Device File Explorer nella barra delle tool window per aprire il Device File Explorer.
• 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 singola 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 Debugging per pianificare il lavoro sui plugin nativi, collegalo a Utilizzo di @capgo/capacitor-updater per la funzionalità nativa in Utilizzo di @capgo/capacitor-updater, Directory dei plugin Capgo per il workflow del prodotto nella Directory dei plugin Capgo, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins by Capgo, Aggiungere o aggiornare i plugin per i dettagli di implementazione in Aggiungere o aggiornare i plugin, e Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Alternative ai plugin di Ionic Enterprise.