Solución de problemas

Aquí tienes algunos problemas comunes que podrías encontrar al usar Capgo y cómo resolverlos.

🚀 ¿Necesitas ayuda de un experto?

¿Atascado con un problema complejo? ¡Nuestro equipo de expertos está aquí para ayudarte! Obtén soporte personalizado, revisiones de code y soluciones a medida adaptadas a tus necesidades.

Obtén soporte profesional

Fallos de upload

Si el upload de tu bundle falla, verifica:

• Que tu app ID en capacitor.config.ts coincida con tu app en el dashboard de Capgo
• Estás ejecutando el comando de upload desde la raíz de tu proyecto Capacitor
• Que tus web assets estén buildeadas y actualizadas

Opciones avanzadas de upload

El Capgo CLI ofrece algunos flags adicionales para resolver problemas comunes de upload:

• --tus: Usa el tu protocolo de upload reanudable para uploads más fiables de bundles grandes o en conexiones de red deficientes. Si tu bundle supera los 10MB o tienes una conexión intermitente, considera usar --tus:

  npx @capgo/cli@latest bundle upload --tus

• --package-json y --node-modules: Indica a Capgo dónde encontrar tu root package.json y node_modules si tu app usa una estructura no estándar como un monorepo o un workspace de npm. Pasa la ruta al root package.json y la --node_modules ruta:

  npx @capgo/cli@latest bundle upload --package-json=path/to/package.json --node_modules=path/to/node_modules

  Capgo necesita esta información para empaquetar correctamente las dependencias de tu app.

Puedes combinar estos flags con otras opciones como --channel según sea necesario. Consulta la documentación de Capgo CLI para ver todos los detalles sobre las opciones de upload disponibles.

Si sigues teniendo problemas con los uploads, contacta a Soporte de Capgo para recibir asistencia técnica.

Depuración de actualizaciones

Si tienes problemas con los live updates, el comando de debug de Capgo es una herramienta útil para el troubleshooting. Para usarlo:

1. Ejecuta el siguiente comando en el directorio de tu proyecto:

   npx @capgo/cli@latest app debug

2. Ejecuta tu app en un dispositivo o emulador y realiza la acción que debería activar una actualización (ej. reabrir la app tras subir un nuevo bundle).

3. Observa la salida del comando de debug. Verás logs sobre el proceso de actualización, incluyendo:

   • Cuándo la app busca una actualización
   • Si se encuentra una actualización y de qué versión es
   • Progreso de la descarga e instalación de la actualización
   • Cualquier error que ocurra durante el proceso de actualización

4. Usa los logs de debug para identificar dónde ocurre el problema. Por ejemplo:

   • Si no se encuentra ninguna actualización, verifica que tu bundle se subió correctamente y que la app está configurada para usar el channel correcto.
   • Si la actualización se descarga pero no se instala, asegúrate de haber llamado a CapacitorUpdater.notifyAppReady() y que la app se cerró y reabrió por completo.
   • Si ves un mensaje de error, busca ese error específico en la documentación de Capgo o contacta a soporte para recibir ayuda.

El comando debug es especialmente útil para identificar problemas en el proceso de descarga e instalación de la actualización. Si los logs muestran que se encontró la versión esperada pero al final no se aplicó, centra el diagnóstico en los pasos posteriores a la descarga.

Depuración con logs nativos

Además del comando debug de Capgo, los logs nativos en Android, iOS y Electron pueden aportar información valiosa para el diagnóstico, especialmente para problemas del lado nativo del proceso de actualización.

Logs de Android

Para acceder a los logs de Android:

1. Conecta tu dispositivo o inicia el emulador
2. Abre Android Studio y selecciona “View > Tool Windows > Logcat”
3. En la ventana de Logcat, filtra los logs para ver solo el proceso de tu app seleccionándolo en el desplegable superior
4. Busca cualquier línea que incluya Capgo para encontrar los logs de SDK

Como alternativa, puedes usar el adb logcat comando y usar grep para Capgo filtrar los logs.

El SDK de Capgo registrará eventos clave durante el proceso de actualización, como:

• Al iniciar una comprobación de actualización
• Si se encuentra una actualización y qué versión es
• Cuando comienza y termina la descarga de la actualización
• Cuando se dispara la instalación de la actualización
• Cualquier error que ocurra durante los pasos de la actualización nativa

Los problemas comunes de Android que podrías ver en los logs 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 la actualización
• Sin espacio suficiente para el bundle de la actualización
• Error al reiniciar la app tras instalar la actualización

Logs de iOS

Para acceder a los logs de iOS:

1. Conecta tu dispositivo o inicia tu simulador
2. Abre Xcode y ve a “Window > Devices and Simulators”
3. Selecciona tu dispositivo y haz clic en “Open Console”
4. En la salida de la consola, busca las líneas que incluyan Capgo para encontrar los logs de SDK

También puedes usar el log stream comando en la terminal y grep para Capgo filtrar los logs.

Al igual que en Android, el Capgo SDK registrará eventos clave de iOS:

• Inicio y resultado de la comprobación de Update
• Inicio, progreso y finalización de la descarga
• Activación e resultado de la instalación
• Cualquier error durante el proceso de Native Build

Los problemas específicos de iOS que podrías identificar en los logs incluyen:

• Problemas de certificados SSL al descargar la actualización
• App Transport Security bloqueando la descarga de la actualización
• Insufficient storage space for the update bundle
• Error al extraer o aplicar correctamente el bundle de la actualización

Logs de Electron

Para apps de Electron, revisa la salida tanto del proceso principal como del renderer:

1. Ejecuta la app de Electron desde tu terminal con tu comando habitual (por ejemplo, bun run electron:dev o bun run electron:serve) y observa la salida de la terminal para ver el inicio, chequeos de update y errores de red.
2. Abre DevTools en la ventana del renderer (View → Toggle Developer Tools) e inspecciona los logs de la consola y las peticiones de red fallidas mientras reproduces el flujo de update.
3. Para apps empaquetadas, usa las herramientas de logs del SO para ver crashes o fallos de inicio:
   • macOS: abre Console.app y filtra por el nombre de tu app
   • Windows: abrir Visor de eventos → Registros de Windows → Aplicación
   • Linux: usa el visor de logs de tu escritorio o journalctl para el proceso de tu app

Al depurar actualizaciones, compara los mensajes de los logs del main-process y del renderer-process para distinguir problemas de arranque de Electron de problemas del ciclo de vida de Capgo.

En todas las plataformas, los logs nativos ofrecen una visión de 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 de JavaScript de Capgo.

Al solucionar un problema complejo de live update, es recomendable capturar tanto los logs de depuración de Capgo como los logs nativos para tener una visión completa de lo que ocurre. Ambos logs te darán la mejor oportunidad de identificar y resolver el problema.

Las actualizaciones no se aplican

Si has subido un bundle pero no ves los cambios en tu dispositivo:

• Asegúrate de haber llamado a CapacitorUpdater.notifyAppReady() en tu app code como se muestra en la quickstart
• Verifica que tu dispositivo tenga internet y que los logs de debug de Capgo muestren que se descargó la actualización
• Intenta cerrar y volver a abrir la app por completo, ya que las actualizaciones solo se aplican al iniciarla de nuevo
• Busca errores en los logs nativos que puedan indicar un problema al aplicar la actualización

Consulta la guía de despliegue de live updates para más detalles sobre el proceso de actualización. Si sigues con problemas, usa el npx @capgo/cli@latest app debug comando y los logs nativos para tener más visibilidad de lo que está pasando.

Códigos comunes de fallo de actualización

Si tus logs muestran errores de backend como disable_auto_update_to_major, semver_error, o cannot_update_via_private_channel, consulta la guía específica:

• Problemas comunes de actualización

Explica qué significa cada code común, por qué ocurre y cómo solucionarlo.

Instalación de SDK

Si tienes problemas para instalar el SDK de Capgo, asegúrate de:

• Que tu app use una versión compatible de Capacitor (4.0 o superior)
• Que hayas seguido la quickstart pasos en orden, incluida la sincronización de tu app después de instalar SDK

Integración CI/CD

Para problemas al lanzar uploads de Capgo desde tu pipeline de CI/CD:

• Verifica que tu token de autenticación de Capgo esté bien configurado
• Asegúrate de ejecutar el comando de upload después de buildear tus assets web
• Comprueba que el comando de upload use el nombre de canal correcto para tu entorno de destino

Consulta la integración con CI/CD la documentación para más consejos de solución de problemas. También puedes usar el npx @capgo/cli@latest app debug comando para confirmar si la app está recibiendo las actualizaciones activadas por tu CI/CD.

Continuar desde Solución de problemas

Si estás usando Solución de problemas para planificar el almacenamiento y la gestión de archivos, conéctalo con @capgo/capacitor-data-storage-sqlite para el detalle de implementación en @capgo/capacitor-data-storage-sqlite, Uso de @capgo/capacitor-data-storage-sqlite para la funcionalidad nativa en Uso de @capgo/capacitor-data-storage-sqlite, @capgo/capacitor-file para el detalle de implementación en @capgo/capacitor-file, Uso de @capgo/capacitor-file para la funcionalidad nativa en Uso de @capgo/capacitor-file, y @capgo/capacitor-uploader para el detalle de implementación en @capgo/capacitor-uploader.