Debugging

Capire i log del cloud

Se ottieni un rifiuto del cloud code e hai bisogno di walkthroughs di rimediazione più approfonditi, vedi Problemi di Aggiornamento Comuni.

Capgo i log possono includere metadati per l'evento. Nel dashboard, filtra per l'azione in snake_case code, e clicca sulla cella dei metadati per copiare il payload JSON completo. I metadati sono particolarmente utili per gli eventi di crash e WebView perché possono includere il messaggio di errore, l'URL di origine, la riga e la colonna, lo stato del processo, la pressione della memoria o la ragione specifica della piattaforma. I log più vecchi possono ancora mostrare gli alias in camelCase di base elencati tra parentesi.

Ogni titolo di sezione corrisponde all'azione code mostrata nella tabella dei log del console, quindi puoi collegarti direttamente a essa.

Limiti del piano e risposte normali

I rifiuti del backend relativi a fatturazione, rallentamento o stati non di errore.

InvalidIp

Cosa significa

Capgo ha rilevato traffico che sembra provenire da Google o da infrastrutture cloud. Aggiornamenti meno di quattro ore vecchi vengono ignorati per evitare che il traffico dei bot venga considerato come dispositivi fatturabili.

Cosa fare

Ignorare questo su utenti reali. Riprovare da reti normali e dispositivi reali, o attendere e controllare nuovamente in un secondo momento.

provider_infrastructure_request_blocked

Cosa significa

Il tuo app è configurata per bloccare le richieste provenienti dalle aree IP note di Google e Apple. La protezione si applica alle verifiche degli aggiornamenti, alle statistiche e alle richieste di canale-self, quindi i probe ospitati in cloud e i provider runner possono ricevere questa risposta anche quando la configurazione dell'app è altrimenti valida.

Cosa fare

Riprovare da un dispositivo fisico su una rete di utente normale. Se il traffico proveniente dal provider è intenzionale, disabilitare temporaneamente Bloccare le richieste dell'infrastruttura del provider nella configurazione dell'app Informazioni tab, then enable it again after the test. New apps enable this setting by default; existing apps retain their previous disabled setting until changed.

needPlanUpgrade

Cosa significa

La tua organizzazione ha raggiunto il limite del piano o dispositivo. Il dispositivo non riceverà aggiornamenti fino a quando non sarai salito di livello o il ciclo di fatturazione successivo resettare l'uso.

Cosa fare

Aggiorna il tuo piano nel pannello di controllo o aspetta il prossimo ciclo di fatturazione.

noNew

Cosa significa

Il dispositivo già ha il pacchetto più recente disponibile per il suo canale. Questo è uno stato normale, non un fallimento.

rateLimited

Cosa significa

La dispositivo ha inviato troppi richieste di aggiornamento o canale in un breve intervallo di tempo.

Che fare

Stop calling update APIs inside render loops. Call setChannel / getChannel solo dalle azioni degli utenti, e impostare defaultChannel in capacitor.config.

Formato della versione

Rifiuti di backend causati da metadati di versione nativa non validi.

semver_error

Che significa

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

Che fare

Configura plugins.CapacitorUpdater.version verificare se è valido semver, verificare in Verificatore SemVer, quindi ricostruisci e reinstalla l'app nativa.

Sezione intitolata “Piattaforma e targeting di costruzione”

Rifiuti del backend quando la politica del canale blocca una piattaforma, un tipo di build o una classe di dispositivo.

disablePlatformIos

Cosa significa

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

Cosa fare

Abilita iOS nel canale se si trattava di un errore, o invia i build iOS a un canale dedicato quando il blocco è intenzionale.

disablePlatformAndroid

Cosa significa

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

Cosa fare

Abilita l'Android nel canale se si trattava di un errore, o invia gli Android costruiti a un canale dedicato quando il blocco è intenzionale.

disablePlatformElectron

Cosa significa

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

Cosa fare

Abilita Electron nel canale se questo era un errore, o invia i build di Electron in un canale dedicato quando il blocco è intenzionale.

disableDevBuild

Cosa significa

Il dispositivo è una versione di sviluppo, ma i build di sviluppo sono bloccati per questo canale.

Cosa fare

Consenti i build di sviluppo in un canale di test, o mantieni questo canale con rilascio solo e sposta i dispositivi di sviluppo altrove.

disableProdBuild

Cosa significa

Un rilascio di produzione chiamato /updates, ma gli aggiornamenti di produzione sono bloccati per questo canale.

Cosa fare

Consenti aggiornamenti di produzione nel canale se si trattava di un errore, o invia i build di produzione al canale corretto.

disableDevice

Cosa significa

Un telefono o tablet reale è stato bloccato perché questo canale blocca i dispositivi reali.

Cosa fare

Abilita gli aggiornamenti su dispositivi reali se si trattava di un errore, o mantieni la restrizione e invia i dispositivi reali a un altro canale.

disableEmulator

Cosa significa

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

Cosa fare

Abilita gli aggiornamenti dell'emulatore in un canale di test, o mantieni questo canale bloccato per l'emulatore e utilizza un altro canale per la validazione dell'emulatore.

Regole di compatibilità degli aggiornamenti automatici

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

disableAutoUpdate

Cosa significa

Aggiornamento automatico è disabilitato dalla politica di compatibilità del canale. I metadati includono auto_update con una regola di corrispondenza come major, minor, patch, metadata, o none.

Cosa fare

Cambia la politica di aggiornamento automatico del canale per consentire il tuo rilascio pianificato.

disableAutoUpdateUnderNative

Cosa significa

Il canale ha un bundle più vecchio della linea di base del dispositivo e blocca l'invio di aggiornamenti sotto la versione nativa.

Cosa fare

Pubblica un bundle a o sopra la linea di base nativa, o disabilita la protezione sotto-nativa nel canale.

disableAutoUpdateMetadata

Cosa significa

La canale richiede min_update_version, ma la versione nativa del dispositivo è sotto quel limite.

Che fare

Impostare min_update_version dalla versione nativa più recente sul bundle o rilascio di destinazione.

disableAutoUpdateToMajor

Sezione intitolata “disableAutoUpdateToMajor”

Il canale blocca i salti di versione maggiore, ad esempio 1.x.x to 2.x.x.

Che fare

Allinea la strategia del canale con il tuo piano di rilascio principale, o consenti salti principali per questo tracciato. Vedi Problemi di Aggiornamento Comuni.

disableAutoUpdateToMinor

Cosa significa

Il canale blocca i salti di versione minore rispetto alla linea di base nativa del dispositivo ("version_build, ad esempio 1.2.3 Cosa fare 1.3.0.

Cosa fare

Allinea la strategia del canale con il piano di rilascio minore, o consenti salti minori per questo tracciato.

disableAutoUpdateToPatch

Cosa significa

prefisso; sono consentite solo le modifiche di suffisso. MAJOR.MINOR.PATCH prefix; solo sono consentite le modifiche di suffisso.

Cosa fare

Allinea il ritmo di rilascio con la politica del canale, o consenti salti di patch per questo tracciato.

Configurazione del canale

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

cannotUpdateViaPrivateChannel

Cosa significa

Il dispositivo ha cercato di associarsi automaticamente a un canale privato che non consente l'assegnazione automatica del dispositivo (allow_device_self_set è falso) e il canale non è pubblico.

Cosa fare

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

channelMisconfigured

Cosa significa

Il canale utilizza disable_auto_update: "version_number" ma il pacchetto min_update_version è nullo, quindi Capgo non può decidere quali dispositivi dovrebbero aggiornarsi.

Cosa fare

Riempi la configurazione mancante per quella regola o passa a un modo di aggiornamento automatico più semplice.

NoChannelOrOverride

Cosa significa

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

Cosa fare

Imposta un canale di default nel pannello di controllo o configura defaultChannel in fase di costruzione.

Consegna e crittografia del pacchetto

Rifiuti del backend quando il Capgo non può servire o decrittografare il pacchetto.

cannotGetBundle

Cosa significa

Capgo non è riuscito a generare un URL di download firmato valido e non è disponibile alcun fallback del manifesto.

Cosa fare

Ricaricare il pacchetto, rigenerare i manifesti e verificare le impostazioni di R2 o pacchetto pubblico.

missingBundle

Cosa significa

Il pacchetto assegnato al canale non contiene contenuti scaricabili: nessun external_url, nessun r2_pathNon una versione integrata, e nessuna entità di manifesto.

cosa fare

Riavvia e riscarica la versione, quindi conferma che il pacchetto contiene file reali.

keyMismatch

Cosa significa

La chiave di crittografia del dispositivo non corrisponde alla chiave utilizzata per crittografare il pacchetto. I metadati possono includere device_key_id, bundle_key_id, e version.

cosa fare

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

Configurazione dell'app e clienti legacy

Rifiuti del backend causati da configurazioni dell'applicazione o versioni di aggiornamento non supportate.

customIdBlocked

Cosa significa

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

Cosa fare

Smettere di inviare ID personalizzati o abilitare gli ID personalizzati solo quando il tuo workflow li richiede.

blocked_by_server_url

Cosa significa

server.url è impostato nel Capacitor config, quindi il WebView carica una URL remota al posto dei file bundle locali. Capgo gli aggiornamenti in tempo reale richiedono file locali e server.url è sconsigliato in produzione.

Cosa fare

Eliminare o cancellare server.url Per edizioni di produzione e mantenimento dei pacchetti aggiornamenti locali. Questo code può apparire come una rifiuto del backend o come una statistica del dispositivo.

backend_refusal

Cosa significa

Il plugin di aggiornamento è v4, che il backend non accetta più.

Cosa fare

Aggiorna il plugin e CLI a v5+ (preferisci v8) con Capacitor v5+, ricostruisci e ripubblica i metadati del bundle.

Ciclo di aggiornamento

Eventi sul dispositivo per flusso di aggiornamento normale, attivazione e rollback.

ping

Cosa significa

Azione di test interna utilizzata per verificare il pipeline delle statistiche.

get

Cosa significa

Capgo ha inviato informazioni sul download di una nuova versione al dispositivo.

set

Cosa significa

Un pacchetto è stato attivato sul dispositivo.

set_fail

Cosa significa

Un bundle non è stato attivato sul dispositivo.

Cosa fare

Controlla i log nativi con npx @capgo/cli@latest app debug e verificare l'integrità, le vie e i notifyAppReady flow.

reset

Cosa significa

Il dispositivo è stato resettato sul bundle predefinito.

delete

Cosa significa

È stato eliminato un bundle sul dispositivo.

Fallimenti di download e installazione

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

download_0

Cosa significa

È iniziato il download sequenziale al 0% di avanzamento.

download_10

Cosa significa

E' stato scaricato un nuovo pacchetto — progresso indicato al 10%.

download_20

Cosa significa

E' stato scaricato un nuovo pacchetto — progresso indicato al 20%.

download_30

Cosa significa

E' stato scaricato un nuovo pacchetto — progresso indicato al 30%.

download_40

Cosa significa

E' stato scaricato un nuovo pacchetto — progresso indicato al 40%.

download_50

Cosa significa

E' stato scaricato un nuovo pacchetto — progresso indicato al 50%.

download_60

Cosa significa

E' stato scaricato un nuovo pacchetto — progresso indicato al 60%.

download_70

Cosa significa

E' stato scaricato un nuovo pacchetto — progresso indicato al 70%.

download_80

Cosa significa

E' stato scaricato un nuovo pacchetto — progresso indicato al 80%.

download_90

Cosa significa

È stato scaricato un nuovo pacchetto — progresso indicato al 90%.

download_complete

Cosa significa

La scarica del pacchetto è terminata con successo.

download_manifest_start

Cosa significa

Il dispositivo ha iniziato a scaricare l'elenco delle aggiornamenti.

download_manifest_complete

Cosa significa

Il dispositivo ha terminato di scaricare l'elenco delle aggiornamenti.

download_zip_start

Cosa significa

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

download_zip_complete

Cosa significa

Il dispositivo ha completato lo scaricamento dell'archivio del bundle.

download_manifest_file_fail

Cosa significa

È fallito il download di un'entrata del manifesto. version_name utilizza version:fileName per identificare l'asset.

Cosa fare

Risolve il problema di un asset mancante o bloccato, rigenera il manifesto e ricarica il bundle.

download_manifest_checksum_fail

Cosa significa

Un file di manifesto ha fallito la verifica del checksum.

Cosa fare

Ricarica il bundle con una versione attuale di CLI e verifica i checksum dei manifesti.

download_manifest_brotli_fail

Cosa significa

Un file di manifesto ha fallito la decompressione Brotli.

Cosa fare

Verifica le impostazioni di compressione e ricarica gli asset interessati.

download_fail

Cosa significa

Il pacchetto non è stato scaricato.

Cosa fare

Check network connectivity, signed URL expiry, CDN reachability, and device storage.

update_fail

Cosa significa

Il pacchetto è stato installato, ma l'app non l'ha mai chiamato notifyAppReady, quindi Capgo è stato annullato.

Cosa fare

Chiamare notifyAppReady() dopo che la tua app ha completato l'avvio. Testo di log nativo notifyAppReady was not called, roll back current bundle si mappa a questo code.

checksum_fail

Cosa significa

Il bundle scaricato non ha superato la verifica del checksum. Cause comuni: malfunzionamento del calcolo CRC32 vs SHA256 da un vecchio CLI caricamento, o malfunzionamento della chiave di crittografia su plugin più vecchi che presentano la falla di crittografia come falla del checksum.

Cosa fare

Ricaricare con un CLI/plugin (SHA256) attuale. Se si utilizza la crittografia, verificare che la chiave pubblica dell'app corrisponda alla chiave di caricamento, o aggiornare a plugin 8.3.0+ per l'uso esplicito keyMismatch di errori.

decrypt_fail

Cosa significa

Il bundle scaricato non è stato decrittografato.

Cosa fare

Verificare le chiavi di crittografia e ricaricare il bundle con la coppia di chiavi corrispondente.

windows_path_fail

Cosa significa

Il file zip contiene percorsi Windows non validi.

Cosa fare

Ricompila il bundle con percorsi Unix o sanifica i percorsi dell'archivio prima dell'upload.

canonical_path_fail

Cosa significa

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

Cosa fare

Ricompila i percorsi dell'archivio prima dell'upload.

directory_path_fail

Cosa significa

Il file zip contiene percorsi di directory non validi.

Cosa fare

Fix archive structure before upload.

unzip_fail

Cosa significa

Il dispositivo non è riuscito a scompattare il bundle scaricato.

Cosa fare

Verifica l'integrità dell'archiviazione e il supporto per la compressione.

low_mem_fail

Cosa significa

Il download è fallito perché il dispositivo è esaurito di memoria.

Cosa fare

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

Salute dell'app e eventi WebView

Diagnostics di crash, memoria e WebView sul dispositivo. Ispeziona sempre il metadata JSON nel dashboard.

app_moved_to_background

Cosa significa

L'app è entrata in background.

app_moved_to_foreground

Cosa significa

L'app è entrata in foreground.

app_crash

Cosa significa

Crash JavaScript o layer Capacitor. Il metadata può includere messaggio, stack, fonte e contesto del bundle attivo.

Cosa fare

Ispeziona i metadati e i log nativi. Collega il reporting degli errori JS e nativi (ad esempio Sentry) per individuare la cartella code che causa problemi.

app_crash_native

Cosa significa

Crollo del sistema operativo nativo. I metadati possono includere piattaforma, motivo, stack e dettagli del processo.

Cosa fare

Utilizza i log di crash di Xcode o Logcat e correla con il bundle attivo dai metadati.

app_anr

Cosa significa

Evento di non risposta dell'applicazione Android.

Cosa fare

Ispeziona le tracce ANR in Logcat e riduci il lavoro di blocco del thread principale dopo gli aggiornamenti.

app_killed_low_memory

Cosa significa

L'OS ha ucciso l'app dopo pressione di memoria.

Cosa fare

Riduci l'uso della memoria dopo l'attivazione dell'aggiornamento e ispeziona i metadati per segnali di memoria disponibile.

app_killed_excessive_resource_usage

Cosa significa

L'OS ha ucciso l'app per un uso eccessivo di risorse.

Cosa fare

Ispeziona i metadati per il tipo di risorsa o il motivo di piattaforma.

app_initialization_failure

Cosa significa

Aggiornamento o avvio fallito prima che il runtime normale fosse pronto.

Che fare

Ispeziona i metadati per il passaggio che ha fallito e il messaggio di errore.

app_memory_warning

Cosa significa

Avviso di memoria iOS.

Che fare

Analizza il contesto di memoria nei metadati e riduci l'uso massimo dopo gli aggiornamenti.

webview_javascript_error

Cosa significa

Errore JavaScript non catturato nel WebView. I metadati possono includere messaggio, URL della fonte, riga, colonna e stack.

Che fare

Installa il reporting degli errori in JS e layer nativi per catturare la riga esatta che fallisce in produzione.

webview_unhandled_rejection

Cosa significa

Rifiuto di promessa non gestito nel WebView.

Cosa fare

Cattura fallimenti asincroni con errori di reporting JS e nativi.

webview_resource_error

Cosa significa

Un risorsa del WebView non è riuscita a caricare.

Cosa fare

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

webview_security_policy_violation

Cosa significa

La politica di sicurezza del contenuto ha bloccato una risorsa.

Cosa fare

Regola CSP utilizzando la direttiva di metadati e i dettagli delle URI bloccate.

webview_unclean_restart

Cosa significa

La sessione WebView precedente non si è chiusa correttamente, il che può indicare loop di crash dopo un aggiornamento.

Cosa fare

Correlare con gli eventi di crash e di errore WebView prima e dopo il riavvio.

webview_render_process_gone

Cosa significa

Il processo di rendering di WebView Android è uscito.

Cosa fare

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

webview_content_process_terminated

Cosa significa

Il processo di contenuto di WebView iOS è stato terminato.

Cosa fare

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

Contesto di ambiente e canale

Device-side context events that help correlate update behavior with OS, native version, or channel changes.

os_version_changed

Cosa significa

Device OS version changed between checks.

native_app_version_changed

Cosa significa

Versione dell'applicazione nativa modificata, aiutando a separare le modifiche ai bundle nativi da quelle web.

getChannel

Cosa significa

La dispositivo ha interrogato il suo canale attuale.

setChannel

Cosa significa

È stato impostato con successo un canale per il dispositivo.

uninstall

Cosa significa

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

Stato del pacchetto

• SUCCESS: installazione del pacchetto completata
• ERROR: installazione o download fallito
• PENDING: download completato, rilascio in attesa
• DELETED: pacchetto cancellato, ancora presente per le statistiche
• DOWNLOADING: in corso il download di un pacchetto

L'analisi dei log del dispositivo

Comando di debug

Ci sono comandi di debug per gli utenti di cloud Capgo.

npx @capgo/cli@latest app debug

Ciò ti consentirà di verificare tutti gli eventi che si verificano nell'app e trovare una soluzione se gli aggiornamenti non avvengono.

Log nativi iOS

per trovare i tuoi log su Xcode

Ottenimento del Log del dispositivo in Xcode

Log nativi Android

per trovare i tuoi log su Android Studio

Visualizza log con Logcat

Mapping delle frasi di log native

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

Cercare il bundle scaricato su un dispositivo

iOS

Per debuggare su iOS, è necessario scaricare l'app sul proprio computer, si può farlo in questo modo:

L'Xcode ha una funzionalità integrata per esaminare il sistema di file degli app installati dai sviluppatori su un dispositivo iOS.

Per ottenere questo:

• Collega il tuo dispositivo al tuo Mac e seleziona "Finestre" > "Dispositivi" nel menu bar di Xcode.
• Seleziona il tuo dispositivo nella sezione dispositivi nella parte sinistra del pannello.
• Ciò mostrerà una lista di app installate dai sviluppatori per quel dispositivo.
• Seleziona l'app che desideri esaminare e seleziona poi l'icona dei puntini 3 vicino alla parte inferiore dello schermo.
• Ecco dove puoi visualizzare il sistema di file corrente selezionando il download di un suo snapshot.

Scaricamento del contenitore in corso… scaricherà e esporterà una snapshot del sistema di file come file .xcappdata che potrai esplorare.

Scaricato file xcappdata con contesto menu Mostra contenuto della cartella

Fai clic destro su questo file e seleziona Mostra contenuto della cartella per aprire la cartella.

Poi troverai una versione in 2 cartelle.

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

e documents/versions per il caricamento veloce

Android

Per debuggare su Android, è necessario accedere al dispositivo da Android Studio:

• Clicca su Visualizza > Finestre degli strumenti > Esplora file del dispositivo o clicca sul pulsante Esplora file del dispositivo nella barra degli strumenti per aprire l'Esplora file del dispositivo.
• Seleziona un dispositivo dalla lista a discesa.
• Apre la cartella "data/data/NOME_APP/" dove NOME_APP è il tuo ID dell'applicazione.

Poi Trova il versions cartella per vedere tutte le versioni

Did you know?

Sul sistema operativo Android, tutte le versioni sono memorizzate in una cartella, a differenza di IOS dove devono essere duplicate in due posizioni.

Capire i log di crash di ios in produzione

Come revisionare i log di crash del tuo app

Continua da Debugging

Se stai utilizzando Debugging per pianificare il lavoro dei plugin nativi, connettilo con Utilizzare @capgo/capacitor-aggiornatore per la capacità nativa in Utilizzare @capgo/capacitor-aggiornatore, Capgo Directory dei Plugin per il workflow del prodotto nella cartella del Plugin Capgo. Capacitor Plugin da Capgo per il dettaglio di implementazione in Capacitor Plugin da Capgo Aggiungere o Aggiornare i Plugin per il dettaglio di implementazione in Aggiungere o Aggiornare i Plugin, e Sostituti dei Plugin Enterprise Ionic per il flusso di lavoro del prodotto in Sostituti dei Plugin Enterprise Ionic.