Resolución de problemas
Aquí están algunos problemas comunes que puedes encontrar mientras usas Capgo y cómo resolverlos
Fallos en la subida
Si la subida de tu bundle falla, verifica:
- Tu ID de app en
capacitorconfigts
coincide con tu app en el panel de Capgo - Estás ejecutando el comando de subida desde la raíz de tu proyecto Capacitor
- Tus assets web están compilados y actualizados
Opciones avanzadas de subida
La CLI de Capgo proporciona algunas banderas adicionales para ayudar con problemas comunes de subida:
-
--tus
: Usa el protocolo de subida reanudable tus para subidas más confiables de bundles grandes o en conexiones de red deficientes. Si tu bundle es mayor a 10MB o tienes una conexión inestable, considera usar--tus
:Ventana de terminal npx @capgo/cli@latest upload --tus -
--package-json
y--node-modules
: Le indica a Capgo dónde encontrar tupackagejson
raíz ynode_modules
si tu app usa una estructura no estándar como un monorepo o espacio de trabajo npm. Pasa la ruta alpackagejson
raíz y la ruta de--node-modules
:Ventana de terminal npx @capgo/cli@latest upload --package-json=path/to/packagejson --node-modules=path/to/node_modulesCapgo necesita esta información para empaquetar correctamente las dependencias de tu app
Puedes combinar estas banderas con otras opciones como --channel
según sea necesario. Consulta la documentación de la CLI de Capgo para ver todos los detalles sobre las opciones de subida disponibles
Si sigues teniendo problemas con las subidas, contacta al soporte de Capgo para más ayuda
Depurando Actualizaciones
Si estás encontrando problemas con las actualizaciones en vivo, el comando debug de Capgo es una herramienta útil para solucionar problemas. Para usarlo:
-
Ejecuta el siguiente comando en el directorio de tu proyecto:
Ventana de terminal npx @capgo/cli@latest app debug -
Inicia tu app en un dispositivo o emulador y realiza la acción que debería activar una actualización (ej. reabrir la app después de subir un nuevo bundle)
-
Observa la salida del comando debug. Registrará información sobre el proceso de actualización, incluyendo:
- Cuándo la app busca una actualización
- Si se encuentra una actualización y qué versión es
- Progreso de descarga e instalación de la actualización
- Cualquier error que ocurra durante el proceso de actualización
-
Usa los registros de depuración para identificar dónde está ocurriendo el problema. Por ejemplo:
- Si no se encuentra actualización, verifica que tu bundle se subió correctamente y que la app está configurada para usar el canal correcto
- Si la actualización se descarga pero no se instala, asegúrate de haber llamado
CapacitorUpdater.notifyAppReady()
y que la app se cerró y reabrió completamente - Si ves un mensaje de error, busca ese error específico en la documentación de Capgo o contacta al soporte para obtener ayuda
El comando debug es especialmente útil para identificar problemas con el proceso de descarga e instalación de actualizaciones. Si los registros muestran que se encontró la versión de actualización esperada pero no se aplicó finalmente, enfoca tu solución de problemas en los pasos posteriores a la descarga
Depuración con Registros Nativos
Además del comando debug de Capgo, los registros nativos en Android e iOS pueden proporcionar información valiosa para solucionar problemas, especialmente para problemas en el lado nativo del proceso de actualización
Registros de Android
Para acceder a los registros de Android:
- Conecta tu dispositivo o inicia tu emulador
- Abre Android Studio y selecciona “View > Tool Windows > Logcat”
- En la ventana Logcat, filtra los registros solo para el proceso de tu app seleccionándolo del menú desplegable en la parte superior
- Busca cualquier línea que incluya
Capgo
para encontrar los registros del SDK
Alternativamente, puedes usar el comando adb logcat
y grep para Capgo
para filtrar los registros
El SDK de Capgo registrará eventos clave durante el proceso de actualización, como:
- Cuándo se inicia una verificación de actualización
- Si se encuentra una actualización y qué versión es
- Cuándo comienza y termina la descarga de la actualización
- Cuándo se activa la instalación de la actualización
- Cualquier error que ocurra durante los pasos de actualización nativos
Los problemas comunes específicos de Android que podrías ver en los registros incluyen:
- Problemas de conectividad de red que impiden la descarga de la actualización
- Errores de permisos de archivo al guardar o leer el bundle de actualización
- Espacio de almacenamiento insuficiente para el bundle de actualización
- Fallo al reiniciar la app después de que se instala la actualización
Registros de iOS
Para acceder a los registros de iOS:
- Conecta tu dispositivo o inicia tu simulador
- Abre Xcode y ve a “Window > Devices and Simulators”
- Selecciona tu dispositivo y haz clic en “Open Console”
- En la salida de la consola, busca cualquier línea que incluya
Capgo
para encontrar los registros del SDK
También puedes usar el comando log stream
en la terminal y grep para Capgo
para filtrar los registros
Similar a Android, el SDK de Capgo registrará eventos clave del lado de iOS:
- Inicio y resultado de la verificación de actualización
- Inicio, progreso y finalización de la descarga
- Activación y resultado de la instalación
- Cualquier error durante el proceso de actualización nativo
Los problemas específicos de iOS que puedes identificar en los registros incluyen:
- Problemas con certificados SSL al descargar la actualización
- Seguridad de transporte de la app bloqueando la descarga de actualización
- Espacio de almacenamiento insuficiente para el bundle de actualización
- Fallo al extraer o aplicar correctamente el bundle de actualización
En ambas plataformas, los registros nativos proporcionan una vista de más bajo nivel del proceso de actualización, con más detalles sobre la implementación nativa. Son especialmente útiles para identificar problemas que ocurren fuera de la capa JavaScript de Capgo
Cuando solucionas un problema complicado de actualización en vivo, es una buena idea capturar tanto los registros de depuración de Capgo como los registros nativos para tener una imagen completa de lo que está sucediendo. Los dos registros juntos te darán la mejor oportunidad de identificar y resolver el problema
Actualizaciones que no se aplican
Si has subido un bundle pero no ves los cambios en tu dispositivo:
- Asegúrate de haber llamado
CapacitorUpdater.notifyAppReady()
en el código de tu app como se muestra en la guía rápida - Verifica que tu dispositivo esté conectado a internet y que los registros de depuración de Capgo muestren que la actualización se descargó
- Intenta cerrar completamente y reabrir la app, ya que las actualizaciones solo se aplican en un inicio nuevo
- Busca cualquier error en los registros nativos que pueda indicar un problema al aplicar la actualización
Consulta la guía de implementación de actualizaciones en vivo para más detalles sobre el proceso de actualización. Si sigues atascado, usa el comando npx @capgo/cli@latest app debug
y los registros nativos para obtener más visibilidad de lo que está sucediendo
Instalación del SDK
Si tienes problemas instalando el SDK de Capgo, asegúrate de que:
- Tu app está usando una versión compatible de Capacitor (4.0 o más nueva)
- Has seguido los pasos de la guía rápida en orden, incluyendo sincronizar tu app después de instalar el SDK
Integración CI/CD
Para problemas con la activación de subidas de Capgo desde tu pipeline CI/CD:
- Verifica que tu token de autenticación de Capgo esté configurado correctamente
- Asegúrate de ejecutar el comando de subida después de que tus assets web estén compilados
- Verifica que el comando de subida esté usando el nombre de canal correcto para tu entorno objetivo
Consulta la documentación de integración CI/CD para más consejos de solución de problemas. También puedes usar el comando npx @capgo/cli@latest app debug
para confirmar si tu app está recibiendo las actualizaciones activadas por CI/CD