Saltar al contenido

Depuración

GitHub

Si obtiene una negación de la nube code y necesita walkthroughs de remediaciónde mayor profundidad, consulte Problemas de Actualización Comunes.

Capgo los registros pueden incluir metadatos para el evento. En la consola, filtre por la acción de snake_case code, y haga 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 del sistema operativo. Los registros antiguos pueden mostrar alias de camelCase legado listados en paréntesis.

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

Límites de planificación y respuestas normales

Sección titulada “Límites de planificación y respuestas normales”

Negaciones de servidor relacionadas con facturación, limitaciones 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óralo en usuarios reales. Vuelve a intentarlo desde redes normales y dispositivos reales, o espera y vuelve a verificar más tarde.

¿Qué significa

Su aplicación está configurada para bloquear solicitudes de conocidas direcciones IP de centros de datos de Google y Apple. La protección se aplica a las comprobaciones de actualizaciones, estadísticas y solicitudes de canal-self, por lo que los probes alojados en la nube y los ejecutores de proveedor pueden recibir esta respuesta incluso cuando la configuración de la aplicación es válida en otro sentido.

¿Qué hacer

Reintentar desde un dispositivo físico en una red de usuario normal. Si el tráfico originado por el proveedor es intencional, deshabilite temporalmente Bloquear solicitudes de infraestructura de proveedor en la información de la aplicación pulse la pestaña, luego habilítelo de nuevo después del test. Las nuevas aplicaciones habilitan esta configuración por defecto; las aplicaciones existentes retienen su configuración deshabilitada anterior hasta que se cambie.

¿Qué significa?

Su organización ha alcanzado su límite de plan o dispositivo. El dispositivo no recibirá actualizaciones hasta que actualice o el próximo ciclo de facturación reinicie el uso.

¿Qué hacer?

Suba de categoría en la consola o espere al próximo ciclo de facturación.

¿Qué significa?

El dispositivo ya tiene el paquete más reciente disponible para su canal. Este es un estado normal, no un error.

¿Qué significa?

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

¿Qué hacer

Stop calling update APIs inside render loops. Call setChannel / getChannel solo desde acciones de usuario, y establezca defaultChannel en capacitor.config.

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

¿Qué significa

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

¿Qué hacer

Establecer plugins.CapacitorUpdater.version para semver válido, verifíquelo en el Prueba de SemVerluego reconstruye y reinstala la aplicación nativa.

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

¿Qué significa?

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

¿Qué hacer?

Habilitar iOS en el canal si esto fue accidental, o enviar compilaciones de iOS a un canal dedicado cuando el bloqueo es intencional.

¿Qué significa

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

¿Qué hacer

Habilite Android en el canal si esto fue accidental, o dirija las 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 versión de desarrollo, pero los builds de desarrollo están bloqueados para este canal.

Hacer qué

Allow dev builds in a test channel, or keep this channel release-only and move dev devices elsewhere.

¿Qué significa

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

Hacer qué

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

¿Qué significa

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

Hacer qué

Si esto fue accidental, habilite actualizaciones de dispositivos reales o mantenga la restricción y redirija dispositivos reales a otro canal.

¿Qué significa?

El dispositivo es un emulador, pero se han deshabilitado las actualizaciones de emulador para este canal.

¿Qué hacer?

Habilite actualizaciones de emulador en un canal de prueba, o mantenga este canal bloqueado para emuladores y utilice otro canal para la validación de emuladores.

Reglas de compatibilidad de actualizaciones automáticas

Sección titulada “Auto-update compatibility rules”

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

¿Qué significa?

Actualización automática deshabilitada por política de compatibilidad de canal. Incluye metadatos auto_update con una regla de coincidencia como major, minor, patch, metadata, o none.

¿Qué hacer

Cambie la política de actualización automática del canal para permitir su lanzamiento deseado.

¿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_versionpero la versión nativa del dispositivo está por debajo de ese umbral.

¿Qué hacer

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

Título de sección “desactivarActualizaciónAutomáticaParaMayor”

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

¿Qué hacer

Alinea la estrategia de canal con tu plan de lanzamiento principal, o permite saltos principales para este track. Ver Problemas Comunes de Actualización.

¿Qué significa

El canal bloquea los saltos de versión menor en relación con la base 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

La canalización bloquea cambios de nivel de parche mientras mantiene el mismo MAJOR.MINOR.PATCH prefijo; solo se permiten cambios de sufijo.

¿Qué hacer

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

Rechazos del servidor causados por una configuración de canal incompleta o incompatible.

¿Qué significa?

El dispositivo intentó asociarse con un canal privado que no permite la asignación automática de dispositivos.allow_device_self_set is false) and the channel is not public.

Habilitar

Enable 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 actualizar.

¿Qué hacer

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

¿Qué significa

No se ha configurado un canal por defecto y el dispositivo no tiene un canal sobrescrito.

¿Qué hacer

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

Rechazos del lado del servidor cuando Capgo no puede servir ni descifrar el paquete.

¿Qué significa?

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

¿Qué hacer?

Vuelve a subir el paquete, regenera los manifiestos y verifica las configuraciones de R2 o paquete público.

¿Qué significa?

El paquete asignado al canal no tiene contenido descargable: no external_urlno r2_pathNo es una versión integrada, ni hay entradas de manifiesto.

¿Qué hacer

Reconstruya y vuelva a 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 metadato puede incluir device_key_id, bundle_key_id, y version.

¿Qué hacer

Compare los IDs de dispositivo y 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 “App configuration and legacy clients”

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

¿Qué significa

La aplicación envió un ID de dispositivo personalizado, pero esta aplicación no acepta IDs personalizados, por lo que el ID se ignora.

¿Qué hacer

Detener la transmisión de IDs personalizados, o habilitar IDs personalizados solo cuando su flujo de trabajo los requiera.

¿Qué significa

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

¿Qué hacer

Eliminar o borrar server.url Para ediciones de producción y mantener los paquetes de actualización locales. Este code puede aparecer como una negativa del servidor o como un error del dispositivo.

¿Qué significa

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

¿Qué hacer

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

Eventos en el dispositivo para flujo de actualización normal, activación y rollback.

¿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?

Un paquete se activó en el dispositivo.

¿Qué significa?

Un paquete falló al activarse en el dispositivo.

¿Qué hacer?

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

¿Qué significa

El dispositivo se reinició a la versión integrada.

¿Qué significa

Se eliminó una versión en el dispositivo.

Eventos del 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 una nueva versión — se indica el progreso en un 10%.

¿Qué significa

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

¿Qué significa

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

¿Qué significa

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

¿Qué significa esto

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

¿Qué significa esto

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

¿Qué significa esto

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

¿Qué significa esto

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

¿Qué significa esto?

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

¿Qué significa esto?

La descarga del paquete finalizó con éxito.

¿Qué significa esto?

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

¿Qué significa esto?

El dispositivo finalizó la descarga del 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 no se pudo descargar. version_name uses version:fileName identificar el activo.

¿Qué hacer

Reemplaza el paquete faltante o bloqueado, regenera el manifiesto y re-sube el paquete.

¿Qué significa?

Un archivo de manifesto falló la validación del checksum.

¿Qué hacer?

Vuelva a subir el paquete con una versión actualizada CLI y verifique los checksums del manifest.

¿Qué significa?

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

¿Qué hacer?

Verifica las configuraciones de compresión y re-sube los activos afectados.

¿Qué significa?

El paquete no se pudo descargar.

¿Qué hacer?

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

¿Qué significa?

El paquete se instaló pero la aplicación nunca llamó notifyAppReadya Capgo se deshizo.

¿Qué hacer?

Llame notifyAppReady() después de que su aplicación termine de inicializarse. 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 carga, o desacuerdo de clave de cifrado en plugins más antiguos que presentan falla de descifrado como falla de checksum.

¿Qué hacer

Re-cargar con un CLI/plugin actualizado (SHA256). Si se utiliza cifrado, verificar que la clave pública de la aplicación coincida con la clave de carga, o actualizar a plugin 8.3.0+ para errores explícitos keyMismatch errors.

¿Qué significa

El paquete descargado no pudo descifrar.

¿Qué hacer

Verificar claves de cifrado y re-subir el paquete con la pareja de clave correspondiente.

¿Qué significa

El archivo zip contiene rutas de Windows ilegales.

¿Qué hacer?

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

¿Qué significa?

Las rutas de archivo dentro del archivo zip no son canónicas.

¿Qué hacer?

Corrija la generación de rutas de archivo antes de subir.

¿Qué significa?

El archivo zip contiene rutas de directorio inválidas.

¿Qué hacer?

Corrija la estructura del archivo antes de subirlo.

¿Qué significa?

El dispositivo falló al descomprimir el paquete descargado.

¿Qué hacer?

Verificar integridad del archivo y compresión admitida.

¿Qué significa?

La descarga falló 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 libre.

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

¿Qué significa?

La aplicación ingresó al fondo.

¿Qué significa?

La aplicación ingresó al primer plano.

¿Qué significa?

Crash de JavaScript o capa Capacitor. El metadato puede incluir mensaje, pila, fuente y contexto de paquete activo.

¿Qué hacer?

Inspeccionar metadatos y registros nativos. Paire el informe de errores JS y nativos (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?

Utilice registros de crash de Xcode o Logcat y correlacione con el paquete activo desde la metadata.

¿Qué significa?

Evento de no respuesta de la aplicación Android.

¿Qué hacer?

Inspect ANR traces in Logcat and reduce main-thread blocking work after updates.

¿Qué significa

The OS killed the app after memory pressure.

¿Qué hacer

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

¿Qué significa

El sistema operativo mató la aplicación por uso excesivo de recursos.

¿Qué hacer

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

¿Qué significa

Updater or startup failed before normal runtime was ready.

¿Qué hacer

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

¿Qué significa

Advertencia de memoria de iOS.

¿Qué hacer

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

¿Qué significa

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

¿Qué hacer

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

¿Qué significa?

Rechazo no gestionado de promesas en el WebView.

¿Qué hacer?

Captura de fallas asíncronas con JS y reporte de errores nativos.

¿Qué significa?

Un recurso del WebView falló cargar.

¿Qué hacer?

Utiliza la URL de metadatos y 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 CSP utilizando la directiva de metadatos y 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?

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

¿Qué significa?

El proceso de renderizado de Android WebView ha salido.

¿Qué hacer?

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

¿Qué significa?

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

¿Qué hacer?

Inspectar el paquete activo y la URL de la página desde la metadata.

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

¿Qué significa?

Sección titulada “Environment and channel context”

¿Qué significa

La versión del almacen de aplicaciones nativa cambió, ayudando a separar los cambios de paquetes nativos vs web.

¿Qué significa

El dispositivo consultó su canal actual.

¿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 ha instalado el paquete
  • ERROR: falló la instalación o descarga
  • PENDING: se ha descargado, pendiente de lanzamiento
  • DELETED: Paquete eliminado, aún presentado para estadísticas
  • DOWNLOADING: se está descargando actualmente un paquete

Hay un comando de depuración para los usuarios de la nube Capgo.

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 las actualizaciones no suceden.

para encontrar sus registros en Xcode

para encontrar sus 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

Para depurar en iOS, necesita descargar la aplicación en su computadora, puede hacerlo de la siguiente manera:

Xcode tiene una característica incorporada para inspeccionar el sistema de archivos de aplicaciones instaladas por desarrolladores en un dispositivo iOS. Menú de Ventanas de Xcode mostrando la opción de Dispositivos y Simuladores

Para lograr esto:

  • Conecte su dispositivo a su Mac y seleccione Ventana > Dispositivos en el menú de Xcode.
  • Seleccione su dispositivo en el panel izquierdo bajo la sección Dispositivos.
  • Esto mostrará una lista de aplicaciones instaladas por desarrolladores para ese dispositivo.
  • Seleccione la aplicación que desea inspeccionar y luego seleccione el icono de 3 puntos cerca de la parte inferior de la pantalla.
  • Aquí puede ver el sistema de archivos actual seleccionando descargar una instantánea de él.

Xcode Devices panel showing app container download option

Al seleccionar Descargar Contenedor… se 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 Documentos, Biblioteca, tmp, etc.

Estructura de carpetas del contenedor de la aplicación iOS mostrando carpetas 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 el recarga caliente

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

  • Click View > Tool Windows > Device File Explorer or click the Device File Explorer button in the tool window bar to open the Device File Explorer.
  • Selecciona un dispositivo de la lista desplegable.
  • Abre la ruta data/datos/APP_NOMBRE/ where APP_NAME es su ID de aplicación.

Android Studio Device File Explorer showing app data directory

Entonces Encuentra el versions carpeta para ver todas las versiones

Comprender registros de crash de producción de ios

Entendiendo los registros de crash de ios

Si estás utilizando Depuración para planificar el trabajo de plugin nativo, conecte con Usando @capgo/capacitor-actualizador para la capacidad nativa en Usando @capgo/capacitor-actualizador Capgo Carpeta de Plugins para el flujo de trabajo del producto en Capgo Carpeta de Plugins Capacitor Plugins por Capgo para el detalle de implementación en Capacitor Plugins por 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 Ionic Enterprise Plugin Alternativas.