Saltar al contenido

Depuración

GitHub

Si obtienes una negación de la nube code y necesitas walkthroughs de remediaciónde mayor profundidad, vea Problemas de actualización comunes.

Capgo los registros pueden incluir metadatos para el evento. En la consola, filtra por la acción de snake_case code, y haz clic en la celda de metadatos para copiar el payload JSON completo. Los metadatos son especialmente útiles para eventos de crash y WebView porque pueden incluir el mensaje de error, la URL de origen, la línea y columna, el estado del proceso, la presión de memoria o la razón específica de la plataforma. Los registros más antiguos aún pueden mostrar alias de camelCase legados listados en paréntesis.

Cada título de sección coincide con la acción code mostrada en la tabla de registros de la consola, por lo que puedes enlazar directamente a ella.

Rechazos de backend relacionados con facturación, limitación de velocidad o estados no de error.

¿Qué significa

Capgo detectó tráfico que parece provenir de Google o infraestructura de la nube. Se ignoran actualizaciones menores a cuatro horas para evitar que el tráfico de bots se cuente como dispositivos facturables.

¿Qué hacer

Ignórelo en usuarios reales. Vuelva a intentarlo desde redes normales y dispositivos reales, o espere y vuelva a verificar más tarde.

¿Qué significa

Su organización alcanzó su límite de planificación o dispositivos. El dispositivo no recibirá actualizaciones hasta que se actualice o se reinicie el ciclo de facturación y se reinicie el uso.

¿Qué hacer

Actualice su plan en la consola o espere al próximo ciclo de facturación.

¿Qué significa?

El dispositivo ya tiene el último paquete disponible para su canal. Este es un estado normal, no un error.

¿Qué significa?

El dispositivo envió demasiadas solicitudes de actualización o de canal en un corto período de tiempo.

¿Qué hacer?

Detenga las llamadas a las API de actualización dentro de los bucles de renderizado. Llame setChannel / getChannel solamente desde acciones de usuario, y establezca defaultChannel en capacitor.config.

Formato de versión

Formato de versión

Rechazos del backend causados por metadatos de versión nativa inválidos.

¿Qué significa

La versión del app nativo en la configuración está faltando o no es válida semver (x.y.z).

¿Qué hacer

Establecer plugins.CapacitorUpdater.version a válida semver, verifíquelo en el Prueba de SemVer, luego reconstruya y vuelva a instalar el app nativo.

Configuración de plataforma y compilación

Configuración de plataforma y compilación

Rechazos de backend cuando la política de canal bloquea una plataforma, un tipo de compilación o una clase de dispositivo.

¿Qué significa?

El dispositivo ejecuta iOS, pero se han desactivado las actualizaciones de iOS para este canal.

¿Qué hacer?

Habilite iOS en el canal si esto fue accidental, o envíe compilaciones de iOS a un canal dedicado cuando el bloqueo sea intencional.

¿Qué significa?

El dispositivo ejecuta Android, pero se han desactivado las actualizaciones de Android para este canal.

¿Qué hacer?

Habilite Android en el canal si esto fue accidental, o envíe compilaciones de Android a un canal dedicado cuando el bloqueo sea intencional.

¿Qué significa

El dispositivo ejecuta Electron, pero se han deshabilitado las actualizaciones de Electron para este canal.

¿Qué hacer

Habilite Electron en el canal si esto fue accidental, o dirija las compilaciones de Electron a un canal dedicado cuando el bloqueo sea intencional.

¿Qué significa

El dispositivo es una compilación de desarrollo, pero los compilados de desarrollo están bloqueados para este canal.

¿Qué hacer

Permita compilaciones de desarrollo en un canal de prueba, o mantenga este canal solo para lanzamientos y mueva los dispositivos de desarrollo a otro lugar.

¿Qué significa

Una compilación de producción llamada /updates, pero las actualizaciones de producción están bloqueadas para este canal.

¿Qué hacer

Permitir actualizaciones de producción en el canal si esto fue accidental, o redirigir las compilaciones de producción al canal correcto.

¿Qué significa

Un teléfono o tableta real fue bloqueado porque este canal bloquea dispositivos reales.

¿Qué hacer

Habilitar actualizaciones de dispositivos reales si esto fue accidental, o mantener la restricción y redirigir a los dispositivos reales a otro canal.

¿Qué significa

El dispositivo es un emulador, pero las actualizaciones de emulador están deshabilitadas para este canal.

¿Qué hacer

Activa actualizaciones del emulador en un canal de prueba, o mantén este canal bloqueado para emuladores y utiliza otro canal para la validación del emulador.

Rechazos de backend cuando las reglas de semver o de metadatos bloquean el paquete objetivo.

¿Qué significa?

Las actualizaciones automáticas están desactivadas por la política de compatibilidad de canal. Los metadatos incluyen auto_update con una regla de coincidencia como major, minor, patch, metadata, o none.

¿Qué hacer?

Cambia la política de actualización automática del canal para permitir tu lanzamiento previsto.

¿Qué significa

El canal tiene un paquete más antiguo que la base del dispositivo y bloquea enviar actualizaciones bajo la versión nativa.

¿Qué hacer

Publicar un paquete a o por encima de la base nativa, o deshabilitar la protección bajo-nativa en el canal.

¿Qué significa

El canal requiere min_update_version, pero la versión nativa del dispositivo está por debajo de ese umbral.

¿Qué hacer

Establecer min_update_version en el paquete objetivo o la versión de lanzamiento desde una versión nativa más nueva.

¿Qué significa

El canal bloquea saltos de versión mayor, por ejemplo 1.x.x a 2.x.x.

¿Qué hacer

Alinea la estrategia de canal con tu plan de lanzamiento mayor, o permite saltos mayores para este track. Consulta Problemas de actualización comunes.

¿Qué significa

El canal bloquea saltos de versión menor relativos a la base de línea nativa del dispositivo (version_build), por ejemplo 1.2.3 a 1.3.0.

¿Qué hacer

Alinea la estrategia de canal con tu plan de lanzamiento menor, o permite saltos menores para este track.

¿Qué significa

Los bloqueos de canal impiden cambios a nivel de parche mientras se mantiene el mismo MAJOR.MINOR.PATCH prefijo; solo se permiten cambios de sufijo.

¿Qué hacer

Alinea el ritmo de lanzamiento con la política de canal, o permite saltos de parche para este track.

Rechazos de backend causados por configuración de canal faltante o incompatible.

¿Qué significa

The dispositivo intentó asociarse con un canal privado que no permite la asignación de dispositivos (allow_device_self_set es falso) y el canal no es público.

¿Qué hacer

Habilitar allow_device_self_set en el canal o cambiar el dispositivo a un canal público o permitido.

¿Qué significa

El canal utiliza disable_auto_update: "version_number" pero el paquete min_update_version es nulo, por lo que Capgo no puede decidir qué dispositivos deben actualizarse.

¿Qué hacer

Rellene la configuración faltante para esa regla o cambie a un modo de actualización automática más simple.

NoChannelOrOverride

NoChannelOrOverride

¿Qué significa?

No se ha configurado un canal por defecto y el dispositivo no tiene una sobrescritura de canal.

¿Qué hacer?

Establezca un canal por defecto en la consola o configure defaultChannel en la compilación.

Entrega y cifrado de paquetes

Entrega y cifrado de paquetes

Rechazos del servidor de backend cuando no se puede servir o descifrar el paquete Capgo.

¿Qué significa?

Capgo no pudo generar una URL de descarga firmada válida y no se encontró una sobrescritura de manifiesto disponible.

What to hacer

Re-subir el paquete, regenerar manifestos y verificar R2 o ajustes de paquete público.

¿Qué significa

El paquete asignado al canal no tiene contenido descargable: no external_url, no r2_path, no es una versión integrada, y no hay entradas de manifest.

¿Qué hacer

Reconstruir y re-subir la versión, luego confirme que el paquete tiene contenido de archivo real.

¿Qué significa

La clave pública de dispositivo de cifrado no coincide con la clave utilizada para cifrar el paquete. El metadatos pueden incluir device_key_id, bundle_key_id, y version.

¿Qué hacer

Compare la ID de dispositivo y la ID de paquete en la consola. Publica con la misma clave y versiones de plugin coincidentes CLI/.

Configuración de la aplicación y clientes legados

Sección titulada “Configuración de la aplicación y clientes legados”

Rechazos del servidor causados por la configuración de la aplicación o versiones de actualizador no soportadas.

¿Qué significa

La aplicación envió una ID de dispositivo personalizada, pero esta aplicación no acepta IDs personalizadas, por lo que se ignora la ID.

¿Qué hacer

Detener la envío de IDs personalizadas, o habilitar IDs personalizadas solo cuando su flujo de trabajo los requiera.

What significa

server.url está configurado en Capacitor config, por lo que la WebView carga una URL remota en lugar de archivos de paquete locales. Capgo actualizaciones en vivo requieren archivos locales y server.url se desaconseja en producción.

¿Qué hacer

Eliminar o borrar server.url para compilaciones de producción y mantener los payloads de actualización locales. Este code puede aparecer como una negativa del servidor o como un estado del dispositivo.

¿Qué significa

El plugin de actualización es v4, que ya no acepta el servidor.

¿Qué hacer

Actualizar el plugin y CLI a v5+ (preferir v8) con Capacitor v5+, reconstruir y volver a publicar metadatos de paquete.

Eventos del dispositivo para el flujo de actualización normal, activación y retroceso.

¿Qué significa?

Acción de prueba interna utilizada para verificar el pipeline de estadísticas.

¿Qué significa?

Capgo envió información de descarga para una nueva versión al dispositivo.

¿Qué significa?

Se activó un paquete en el dispositivo.

¿Qué significa

Un paquete no se activó en el dispositivo.

¿Qué hacer

Verifique los registros nativos con npx @capgo/cli@latest app debug y verifique la integridad del paquete, rutas y notifyAppReady flujo.

¿Qué significa

El dispositivo se reinició al paquete incorporado.

¿Qué significa

Se eliminó un paquete en el dispositivo.

Eventos en el dispositivo para el progreso de descarga, validación de archivo y errores de instalación.

¿Qué significa

La secuencia de descarga comenzó con un 0% de progreso.

¿Qué significa

Se ha descargado un nuevo paquete — indicado el progreso en el 10%.

¿Qué significa

Se ha descargado un nuevo paquete — indicado el progreso en el 20%.

¿Qué significa?

Se ha descargado una nueva colección — se indica el progreso en un 30%.

¿Qué significa?

Se ha descargado una nueva colección — se indica el progreso en un 40%.

¿Qué significa?

Se ha descargado una nueva colección — se indica el progreso en un 50%.

¿Qué significa?

Se ha descargado una nueva colección — se indica el progreso en un 60%.

¿Qué significa

Se ha descargado una nueva colección — se indica el progreso en un 70%

¿Qué significa

Se ha descargado una nueva colección — se indica el progreso en un 80%

¿Qué significa

Se ha descargado una nueva colección — se indica el progreso en un 90%

¿Qué significa

La descarga de la colección finalizó con éxito.

¿Qué significa?

El dispositivo comenzó a descargar el manifiesto de actualización.

¿Qué significa?

El dispositivo terminó de descargar el manifiesto de actualización.

¿Qué significa?

El dispositivo comenzó a descargar el archivo de paquete.

¿Qué significa?

El dispositivo terminó de descargar el archivo de paquete.

¿Qué significa?

Una entrada del manifiesto falló al descargarse. version_name se utiliza version:fileName para identificar el activo.

¿Qué hacer?

Reemplaza el activo faltante o bloqueado, regenera el manifiesto y vuelve a subir el paquete.

¿Qué significa?

Un archivo de manifiesto falló la validación de sumas de comprobación.

¿Qué hacer?

Vuelve a subir el paquete con una versión actualizada CLI y verifica las sumas de comprobación del manifiesto.

¿Qué significa

Un archivo de manifesto falló la descomposición Brotli.

¿Qué hacer

Verifique los ajustes de compresión y re-suba los activos afectados.

¿Qué significa

El paquete falló al descargar.

¿Qué hacer

Verifique la conectividad de red, la expiración de URL firmada, la accesibilidad de CDN y el almacenamiento del dispositivo.

¿Qué significa

El paquete se instaló pero la aplicación nunca llamó notifyAppReadyAsí que Capgo se deshizo.

¿Qué hacer

Llamar notifyAppReady() después de que la aplicación termine de inicializarse. El texto de registro nativo notifyAppReady was not called, roll back current bundle se mapea a este code.

¿Qué significa

La descarga del paquete falló la validación de checksum. Causas comunes: desacuerdo entre CRC32 y SHA256 desde una antigua CLI de carga, o desacuerdo de clave de cifrado en plugins antiguos que presentan falla de descifrado como falla de checksum.

¿Qué hacer

Re-subir con un CLI/plugin actual (SHA256). Si se utiliza cifrado, verifique que la clave pública de la aplicación coincida con la clave de carga, o actualice a plugin 8.3.0+ para errores keyMismatch explicitos.

¿Qué significa?

El paquete descargado no pudo descifrar.

¿Qué hacer?

Verifique las claves de cifrado y vuelva a subir el paquete con la clave de pareja correspondiente.

¿Qué significa?

El zip contiene rutas de Windows ilegales.

¿Qué hacer?

Reconstruya el paquete en rutas de Unix o sane las rutas del archivo antes de subir.

¿Qué significa?

Los rutas de archivos dentro del zip no son canónicas.

¿Qué hacer

Revisa la generación de la ruta del archivo antes de subir.

¿Qué significa

El zip contiene rutas de directorios inválidas.

¿Qué hacer

Revisa la estructura del archivo antes de subir.

¿Qué significa

El dispositivo falló al descomprimir el paquete descargado.

¿Qué hacer

Verificar la integridad del archivo y el soporte para compresión.

¿Qué significa

Falló la descarga porque el dispositivo se quedó sin memoria.

¿Qué hacer

Reduce el tamaño del paquete o inténtelo en un dispositivo con más memoria disponible.

Diagnósticos de fallas de dispositivo, memoria y WebView. Siempre inspeccione el JSON de metadatos en la consola.

¿Qué significa

La aplicación ingresó al segundo plano.

¿Qué significa?

La aplicación ingresó al primer plano.

¿Qué significa?

Crash de JavaScript o capa Capacitor. Los metadatos pueden incluir mensaje, pila, fuente y contexto de paquete activo.

¿Qué hacer?

Inspeccione los metadatos y registros nativos. Asocie el informe de errores de JS con el informe de errores nativo (por ejemplo Sentry) para localizar el camino fallido code.

¿Qué significa?

Crash de plataforma nativa. Los metadatos pueden incluir plataforma, razón, pila y detalles del proceso.

¿Qué hacer?

Use Xcode o Logcat para analizar los registros de errores y correlacionarlos con el paquete activo desde la metadata.

¿Qué significa?

Evento de no respuesta de la aplicación Android.

¿Qué hacer?

Inspeccione las huellas de ANR en Logcat y reduzca el trabajo de bloqueo en el hilo principal después de las actualizaciones.

¿Qué significa?

El sistema operativo mató la aplicación después de una presión de memoria.

¿Qué hacer?

Reduce el uso de memoria después de la activación de la actualización e inspeccione la metadata para señales de memoria disponibles.

¿Qué significa

La OS mató la aplicación por uso excesivo de recursos.

¿Qué hacer

Inspeccione los metadatos para el tipo de recurso o la razón de plataforma.

¿Qué significa

Falló el actualizador o el arranque antes de que estuviera lista la ejecución normal.

¿Qué hacer

Inspeccione los metadatos para el paso fallido y el mensaje de error.

¿Qué significa

Aviso de memoria de iOS.

¿Qué hacer

Inspeccionar el contexto de memoria en los metadatos y reducir el uso máximo después de las actualizaciones.

¿Qué significa

Error de JavaScript no capturado en el WebView. Los metadatos pueden incluir mensaje, URL de origen, línea, columna y pila.

¿Qué hacer

Instalar el informe de errores en JS y capas nativas para capturar la línea exacta fallida en producción.

¿Qué significa

Rechazo de promesa no manejada en el WebView.

¿Qué hacer

Capturar fallas asíncronas con el informe de errores de JS y nativo.

¿Qué significa?

Un recurso de WebView no se cargó correctamente.

¿Qué hacer?

Utilice la URL de metadatos y los detalles de estado para solucionar activos rotos o reglas de red.

¿Qué significa?

La política de seguridad de contenido bloqueó un recurso.

¿Qué hacer?

Ajuste la CSP utilizando la directiva de metadatos y los detalles de URI bloqueados.

¿Qué significa?

La sesión de WebView anterior no se cerró limpiamente, lo que puede indicar bucles de crash después de una actualización.

¿Qué hacer

Correlacionar con eventos de crash y errores de WebView antes y después del reinicio.

¿Qué significa

El proceso de renderizado de WebView de Android se ha salido.

¿Qué hacer

Inspeccionar señales de crash del renderizador en metadatos y registros nativos.

¿Qué significa

El proceso de contenido de WebView de iOS se ha terminado.

¿Qué hacer

Inspecciona la URL de la página y el paquete activo desde los metadatos.

Eventos del lado del dispositivo que ayudan a correlacionar el comportamiento de actualización con cambios en el sistema operativo, la versión nativa o el canal.

¿Qué significa

La versión del sistema operativo del dispositivo cambió entre comprobaciones.

¿Qué significa

La versión del almacenamiento de aplicaciones nativas cambió, lo que ayuda a separar los cambios en el paquete web de los cambios nativos.

¿Qué significa

The device queried its current channel.

¿Qué significa

Se estableció con éxito un canal para el dispositivo.

¿Qué significa

La aplicación se desinstaló o se eliminó Capgo datos.

  • SUCCESS: se completó la instalación del paquete
  • ERROR: falló la instalación o descarga
  • PENDING: se completó la descarga, pendiente de liberación
  • DELETED: Paquete eliminado, aún presentado para estadísticas
  • DOWNLOADING: Descargando actualmente un paquete

Existe un comando de depuración para los usuarios de Capgo de Cloudflare.

Ventana de terminal
npx @capgo/cli@latest app debug

Esto le permitirá verificar todos los eventos que están ocurriendo en la aplicación y encontrar una solución si los actualizaciones no ocurren.

para encontrar tus registros en Xcode

para encontrar tus registros en Android Studio

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

Encontrar el paquete descargado en un dispositivo

Sección titulada “Encontrar el paquete descargado en un dispositivo”

Para depurar en iOS, necesitas descargar la aplicación en tu computadora, puedes hacerlo de la siguiente manera:

Xcode tiene una característica integrada para inspeccionar el sistema de archivos de las aplicaciones instaladas por desarrolladores en un dispositivo iOS. Opción de menú de Xcode para dispositivos y simuladores

Para lograr esto:

  • Conecta tu dispositivo a tu Mac y selecciona Ventana > Dispositivos en el menú de Xcode.
  • Selecciona tu dispositivo en el panel izquierdo en la sección Dispositivos.
  • Esto mostrará una lista de aplicaciones instaladas por desarrolladores para ese dispositivo.
  • Selecciona la aplicación que deseas inspeccionar y luego selecciona el icono de tres puntos cerca de la parte inferior de la pantalla.
  • En este lugar puedes ver el sistema de archivos actual seleccionando descargar una instantánea de él.

Panel de dispositivos de Xcode mostrando opción de descargar contenedor de aplicación

Seleccionando Descargar Contenedor… descargará y exportará una instantánea del sistema de archivos como un archivo .xcappdata que puede explorar.

Archivo xcappdata descargado con menú de contexto Mostrar Contenido de Paquete

Haga clic derecho en este archivo y seleccione Mostrar Contenido de Paquete para abrir la carpeta.

Abra la carpeta de datos de la aplicación, y debería ver ahora unos pocos carpetas como Documents, Library, tmp, etc.

Estructura de la carpeta del contenedor de la aplicación de iOS mostrando carpetas de Documents y Library

Luego encontrará una versión en 2 carpetas:

library/NoCloud/ionic_built_snapshots es necesario después de reiniciar la aplicación

y documents/versions para recarga caliente

Para depurar en Android, necesita acceder al dispositivo desde Android Studio:

  • Haga clic en Vista > Ventanas de Herramienta > Explorador de Archivos de Dispositivo o haga clic en el botón Explorador de Archivos de Dispositivo en la barra de ventanas de herramienta para abrir el Explorador de Archivos de Dispositivo.
  • Seleccione un dispositivo de la lista desplegable.
  • Abrir el camino data/data/__CAPGO_KEEP_0__/ donde __CAPGO_KEEP_0__ es su ID de aplicación.

Explorador de Archivos de Dispositivo de Android Studio mostrando directorio de datos de la aplicación

Luego Encuentre el versions carpeta para ver todas las versiones

Entendiendo los registros de errores de producción de ios

Sección titulada “Entendiendo los registros de errores de producción de ios”

Si estás utilizando Depuración para planificar el trabajo de plugin nativo, conecta con Usando @capgo/capacitor-actualizador para la capacidad nativa en Usando @capgo/capacitor-actualizador, Capgo Directorio de plugin para el flujo de trabajo de producto en Capgo Directorio de plugin, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Agregar o Actualizar Plugins para el detalle de implementación en Agregar o Actualizar Plugins, y Alternativas de Plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas de Plugins de Ionic Enterprise.