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 en 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 de la plataforma. Los registros más antiguos 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 puede enlazar directamente a ella.

Rechazos de servidor 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 aplicación está configurada para bloquear solicitudes de conocidos rangos de 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 probadores alojados en la nube y los ejecutores de proveedores pueden recibir esta respuesta incluso cuando la configuración de la aplicación es válida de otra manera.

¿Qué hacer?

Vuelva a intentarlo desde un dispositivo físico en una red de usuario normal. Si el tráfico originado por el proveedor es intencional, desactive temporalmente Bloquear solicitudes de infraestructura de proveedores In la aplicación, en la pestaña de Información, habilítelo nuevamente después del test. Las nuevas aplicaciones habilitan este ajuste por defecto; las aplicaciones existentes retienen su configuración previamente deshabilitada hasta que se cambie. Sección titulada “needPlanUpgrade” ¿Qué significa?

¿Qué hacer?

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

Sección titulada “noNew”

¿Qué significa?

Sección titulada “rateLimited”

Section titled “needPlanUpgrade”

¿Qué significa

El dispositivo envió demasiadas solicitudes de actualización o 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 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 a una versión válida de semver, verifíquelo en el Prueba de SemVer, luego reconstruye y reinstala la aplicación nativa.

Sección titulada “desactivar plataforma iOS”

disablePlatformIos

¿Qué significa

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

¿Qué hacer

What to do

Activa iOS en el canal si esto fue accidental, o envía los builds de iOS a un canal dedicado cuando el bloqueo es intencional.

¿Qué significa?

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

¿Qué hacer?

Activa Android en el canal si esto fue accidental, o envía los builds de Android a un canal dedicado cuando el bloqueo es intencional.

¿Qué significa?

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

¿Qué hacer?

Activa Electron en el canal si esto fue accidental, o envía los builds de Electron a un canal dedicado cuando el bloqueo es intencional.

¿Qué significa

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

¿Qué hacer

Permitir compilados de desarrollo en un canal de prueba, o mantener este canal con lanzamientos únicamente y mover dispositivos de desarrollo a otro lugar.

¿Qué significa

Una compilación de producción llamada /updates, pero los 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 enviar compilados de producción al canal correcto.

¿Qué significa

A un teléfono o tableta real se le impidió funcionar porque este canal bloquea dispositivos reales.

¿Qué hacer?

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

¿Qué significa?

El dispositivo es un emulador, pero se deshabilitan 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

Título de la sección “Auto-update compatibility rules”

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

¿Qué significa

La actualización automática está deshabilitada por la política de compatibilidad de canal. El metadato incluye 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 tu 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

Publica un paquete a o por encima de la base nativa, o deshabilita 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 o versión de destino de una versión nativa más reciente.

¿Qué significa

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

¿Qué hacer

Alinear la estrategia del canal con tu plan de lanzamiento mayor, o permitir saltos mayores para este track. Ver Problemas Comunes de Actualización.

¿Qué significa?

El canal bloquea saltos de versión menor en relación con 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 de versiones menores, o permite saltos de versiones menores para este track.

¿Qué significa?

El canal 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 parches para este track.

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

¿Qué significa

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

¿Qué hacer

Habilita allow_device_self_set en el canal o cambia 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 una sobrescritura de canal.

¿Qué hacer?

Establezca un canal por defecto en la consola o configure defaultChannel en el proceso de construcción.

Backend refusals when Capgo cannot serve or decrypt the bundle.

¿Qué significa?

Capgo failed to generate a valid signed download URL and no manifest fallback was available.

¿Qué hacer?

Vuelva a subir el paquete, regenere los manifiestos y verifique 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, y no 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 cifrado del dispositivo no coincide con la clave utilizada para cifrar el paquete. El metadato puede incluir device_key_id, bundle_key_idy version.

¿Qué hacer?

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

Configuración de la aplicación y clientes legados

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

Rechazos del lado 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 se ignora el ID.

¿Qué hacer?

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

¿Qué significa?

server.url está configurado en Capacitor config, 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 está desaconsejado 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 se acepta en el servidor.

¿Qué hacer?

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

Eventos del lado del dispositivo para el 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?

Se activó un paquete en el dispositivo.

¿Qué significa?

¿Qué hacer?

Verifique los registros nativos con

y verifique la integridad, rutas y npx @capgo/cli@latest app debug y notifyAppReady flujo.

¿Qué significa?

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

¿Qué significa?

Una versión se eliminó en el dispositivo.

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

¿Qué significa?

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

¿Qué significa?

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

¿Qué significa?

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

¿Qué significa?

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

¿Qué significa?

A un nuevo paquete se ha descargado — el progreso se indica en el 40%.

¿Qué significa?

A un nuevo paquete se ha descargado — el progreso se indica en el 50%.

¿Qué significa?

A un nuevo paquete se ha descargado — el progreso se indica en el 60%.

¿Qué significa?

A un nuevo paquete se ha descargado — el progreso se indica en el 70%.

¿Qué significa?

A un nuevo paquete se ha descargado — el progreso se indica en un 80%.

¿Qué significa?

A un nuevo paquete se ha descargado — el progreso se indica en un 90%.

¿Qué significa?

La descarga del paquete se ha completado con éxito.

¿Qué significa?

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

¿Qué significa?

El dispositivo ha finalizado la descarga del manifiesto de actualización.

¿Qué significa?

El dispositivo comenzó a descargar el archivo de paquete.

¿Qué significa?

El dispositivo ha finalizado la descarga del archivo de paquete.

¿Qué significa?

Una entrada del manifiesto falló en la descarga. version_name se utiliza version:fileName para identificar el activo.

¿Qué hacer

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

¿Qué significa

Un archivo de manifiesto falló la validación de checksum.

¿Qué hacer

Re-sube el paquete con una versión actualizada CLI y verifica los checksums del manifiesto.

¿Qué significa

Un archivo de manifiesto 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?

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

¿Qué significa?

El paquete se instaló pero la aplicación nunca llamó notifyAppReadypor lo que Capgo se deshizo.

¿Qué hacer?

Llame notifyAppReady() contexto: texto de fragmento de HTML de una cadena de Capgo UI más larga (clave de padre `appflow_migration_step2`). Página/área: Copia de marketing de comparación/migración de Appflow. Rol: Oración de copia de sitio web. Visto en: página ionic-appflow.astro. Preservar términos de producto/marca y términos de desarrollador de Capgo exactamente. Clave de mensaje `appflow_migration_step2` (Paso 2 de la migración de Appflow). 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 carga de CLI antigua, o desacuerdo de clave de cifrado en plugins antiguos que presentan falla de descifrado como falla de checksum.

¿Qué hacer?

Vuelva a subir con un CLI/plugin actualizado (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 explícitos. keyMismatch Sección titulada “decrypt_fail”

decrypt_fail

¿Qué significa?

La descarga del paquete falló a la hora de descifrar.

¿Qué hacer?

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

Section titled “update_fail”

¿Qué significa?

El archivo zip contiene rutas de Windows ilegales.

¿Qué hacer?

Reconstruya el paquete con rutas de Unix o sane las rutas del archivo antes de subirlo.

¿Qué significa?

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

¿Qué hacer?

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

¿Qué significa?

El archivo zip contiene rutas de directorios inválidas.

¿Qué hacer?

Corrija la estructura del archivo antes de subirlo.

¿Qué significa?

El dispositivo falló al descomprimir el paquete descargado.

¿Qué hacer?

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

¿Qué significa?

La descarga falló porque el dispositivo se quedó sin memoria.

¿Qué hacer?

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

Diagnostics de dispositivo para fallas, memoria y WebView. Inspecciona siempre el JSON de metadatos en la consola.

¿Qué significa?

La aplicación ingresó al fondo.

¿Qué significa?

La aplicación ingresó al primer plano.

¿Qué significa?

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

¿Qué hacer?

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

¿Qué significa?

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

¿Qué hacer?

Utilice los registros de errores de Xcode o Logcat y correlacione con el paquete activo desde los metadatos.

¿Qué significa?

Evento de no respuesta de la aplicación de 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 debido a presión de memoria.

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

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

¿Qué significa

El actualizador o inicio falló antes de que el tiempo de ejecución normal estuviera listo.

¿Qué hacer

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

¿Qué significa

Advertencia de memoria de iOS.

¿Qué hacer

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

¿Qué significa

Error de JavaScript no atrapado 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 fallida exacta en producción.

¿Qué significa

Rechazo de promesa no manejada en el WebView.

¿Qué hacer

Capturar fallas asíncronas con informes de errores JS y nativos.

¿Qué significa

Un recurso del WebView falló para cargar.

¿Qué hacer

Utilice la URL de metadatos y detalles de estado para corregir 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 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 WebView de Android se ha detenido.

¿Qué hacer?

Inspeccionar señales de crash en el registro de metadata y nativo.

¿Qué significa?

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

¿Qué hacer?

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

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.

What it means

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

What it means

La versión del almacenamiento de aplicaciones nativas cambió, ayudando a separar los cambios de paquetes nativos y web.

What it means

El dispositivo consultó su canal actual.

What it means

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

¿Qué significa

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

  • SUCCESS: se ha instalado el paquete
  • ERROR: falló la instalación o descarga
  • PENDING: se ha descargado, pendiente de liberación
  • DELETED: se ha eliminado el paquete, pero sigue presentado para estadísticas
  • DOWNLOADING: se está descargando actualmente un paquete

Existe un comando de depuración para los usuarios de la nube de 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 los 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 las aplicaciones instaladas por desarrolladores en un dispositivo iOS. Opción de menú de la ventana Xcode que muestra la opción de dispositivos y simuladores

To log this information, you can use the following command:

  • Conecta tu dispositivo a tu Mac y selecciona Ventana > Dispositivos en el menú de Xcode.
  • Selecciona tu dispositivo en el panel izquierdo bajo 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 3 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 la opción de descargar una instantánea del contenedor de la aplicación

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

Archivo xcappdata descargado con el menú de contexto Muestra Contenido del Paquete

Haz clic derecho en este archivo y selecciona Muestra Contenido del Paquete para abrir la carpeta.

Abre la carpeta de datos de la aplicación, y ahora deberías ver unos pocos carpetas como Documentos, Biblioteca, tmp, etc.

Estructura de la carpeta del contenedor de la aplicación de iOS mostrando las carpetas Documentos y Biblioteca

Luego encontrarás 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:

  • Haz clic en Ver > Ventanas de herramienta > Explorador de archivos de dispositivo o haz 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.
  • Selecciona un dispositivo de la lista desplegable.
  • Abre la ruta data/data/NOMBRE_DE_LA_APLICACIÓN/ donde APP_NAME es su ID de aplicación.

Explorador de archivos de dispositivo de Android Studio mostrando directorio de datos de la aplicación

Luego encuentra 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”

If you are using Depuración to plan native plugin work, connect it with Usando @capgo/capacitor-updater para la capacidad nativa en Usando @capgo/capacitor-updater Capgo Directorio de Plugins para el flujo de trabajo del producto en Capgo Directorio 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.