Un jueves por la noche, tu app de compras en CapacitorJS empieza a mostrar dashboards en blanco para los usuarios de Android 14. Los clientes de iOS navegan con normalidad. Los usuarios de Electron en escritorio no han reportado nada. El ingeniero de guardia asume una regresión del WebView, abre Android Studio y pasa horas comparando el renderizado entre dispositivos. La causa final no es un bug de renderizado en absoluto. Una clave API de staging llegó a producción después de que la invalidación de caché del CDN no llegara a los clientes móviles.
Ese incidente resulta familiar porque los fallos en móvil rara vez respetan los límites de tu repositorio. Un cambio reciente en JavaScript puede ser inocente mientras que un despliegue, un valor de configuración, un estado de permisos, una dependencia de servicio o una ruta de red rompen el flujo del usuario. Un análisis de incidentes de Microsoft encontró que el 40% de los incidentes en producción se debieron a code o bugs de configuración, mientras que el 60% provino de infraestructura, despliegues y dependencias de servicios. La lección práctica es sencilla: el troubleshooting de la app debe empezar por todo el dominio de fallo, no por el stack trace. (El análisis de incidentes de Microsoft)
Este playbook sigue el flujo de trabajo que uso después de lanzar versiones de CapacitorJS y Electron: establecer exactamente qué ejecutó el usuario, inspeccionar la telemetría de producción antes de intentar reproducir el problema, verificar causas no relacionadas con code y depurar la capa más estrecha que coincida con el síntoma. Los siete pasos son: delimitar el incidente, revisar logs por capas, depurar web y nativo, verificar red y estado, aplicar guardrails en CI, recuperar actualizaciones en vivo y realizar una revisión post-incidente que asigne tareas de prevención.
Tabla de contenidos
- La noche en que el dashboard se apagó
- Lectura de logs de WebView, Native y el OS
- Depurando la capa web y la capa nativa
- Comprobaciones iniciales: Networking, Storage y permisos
- Tests automatizados y CI como sistemas de alerta temprana
- Live Updates como canal de recuperación de emergencia
- Análisis post-incidente para prevenir el siguiente
La noche en que el dashboard se apagó
Para el jueves por la noche, los usuarios de Android reportaban un dashboard en blanco, mientras que los de Electron seguían trabajando con normalidad. La primera hipótesis fue una regresión en Android 14 o WebView. Esa pista acotó la búsqueda, pero no identificó el fallo. Los usuarios afectados también compartían un release channel, una ruta de configuración en caché, un entorno API y una secuencia específica de peticiones al dashboard.
El ingeniero de guardia empezó comparando versiones de WebView. Los resultados parecían plausibles pero no llevaron a nada. Un dashboard en blanco puede deberse a una excepción de renderizado, una respuesta API vacía, una petición rechazada, un token inválido, un feature flag o una lectura de storage que impide restaurar la sesión. Antes de cambiar code, determina qué binario, web bundle, configuración y ruta de backend recibieron los usuarios afectados.
Define el alcance exacto del fallo
Empieza con la telemetría de producción, no con el portátil de un desarrollador. La guía de Google para crashes y ANR en Android recomienda filtrar eventos por dispositivo, sistema operativo y ventana temporal, y luego usar logcat durante la reproducción cuando la ubicación del fallo no esté clara. (Guía de troubleshooting de Android vitals de Google)
Captura estos campos de una sesión afectada:
- Identidad del build: Registra la versión de la app nativa, el build ID, el hash del web bundle y el timestamp del release.
- Canal de distribución: Confirma si el usuario recibió contenido canary, beta, staged o stable.
- Contexto de ejecución: Anota la versión de Android o iOS, el modelo del dispositivo, el tipo de red, el estado de los permisos y si la app se reanudó desde el background.
- Última acción exitosa: Preserva la secuencia exacta de taps, la petición, el estado de la respuesta y el resultado visible.
- Snapshot de configuración: Compara la URL base de API, los feature flags, la configuración de autenticación y de plugins con un dispositivo que funcione correctamente.
Capacitor mantiene la versión nativa separada del contenido web que se ejecuta en el WebView. Dos usuarios pueden compartir un binario instalado desde la store y recibir distintos bundles de JavaScript. También pueden compartir un web bundle y usar distintos plugins nativos. Electron requiere la misma comprobación en el release manifest, la versión del main process, el renderer bundle y el canal de actualización. Los metadatos del paquete del renderer por sí solos no determinan qué ejecutó el usuario.
Reproduce eliminando variables
Tras recolectar los identificadores, clasifica el incidente como canary-only, staged o fully rolled out. Un fallo canary-only apunta a una asignación específica de bundle, flag o canal. Un fallo staged sugiere problemas en la lógica de selección de audiencia o dispositivo. Un fallo fully rolled out eleva la prioridad de la configuración compartida, el comportamiento del backend y la compatibilidad nativa.
Compara el dispositivo afectado con uno que funcione correctamente. Revisa las versiones de los plugins nativos, el hash web, el canal, el entorno de API, el estado de autenticación y los permisos concedidos. Reproduce localmente la última secuencia de acciones del usuario antes de recurrir a un emulador. Si una sola bandera controla el fallo, mantén las demás variables estables y realiza una búsqueda binaria del comportamiento de esa bandera.
Regla práctica: No llames a una reproducción “el mismo bug” hasta que el build ID, el canal, el web bundle, el sistema operativo y la configuración coincidan.
El incidente del dashboard de Android se resolvió corrigiendo la configuración. El equipo comparó las instantáneas, confirmó que el binario nativo era válido y verificó que el WebView y el dashboard de code no habían cambiado. Los clientes de producción estaban solicitando un entorno con credenciales de staging porque la invalidación de caché anterior no había llegado a todos los clientes móviles. Por lo tanto, el trabajo de recuperación se centró en corregir la configuración, establecer las cabeceras de invalidación de caché adecuadas y verificar la purga del CDN desde las regiones y rutas de cliente afectadas.
Esa secuencia es importante porque un comando de purga exitoso no demuestra que todos los usuarios puedan obtener el valor corregido. Revisa las respuestas del CDN, la antigüedad de la caché, los hashes del bundle o la configuración y una sesión de cliente nueva antes de declarar la recuperación. Una recompilación nativa habría añadido tiempo de despliegue sin cambiar el artefacto que causó el fallo.
Usa la misma disciplina para futuros incidentes: identificar el artefacto del usuario, localizar la superficie de fallo, eliminar diferencias ambientales y luego depurar code. Una guía escrita de respuesta a incidentes para equipos móviles debería mantener esas comprobaciones junto al runbook de guardia, incluyendo consultas de telemetría, propiedad del rollout, verificación de purga y la decisión de usar un live update cuando el binario nativo no sea el componente que falla.
Lectura de logs de WebView, Native y el OS
Una aplicación CapacitorJS o Electron genera evidencia en varias capas, y cada capa responde a una pregunta diferente. El WebView puede mostrar excepciones de JavaScript y solicitudes fallidas, pero no explicará cada fallo de plugin. Los logs nativos exponen el comportamiento del bridge y del ciclo de vida, mientras que el sistema operativo registra la presión de memoria, denegaciones de permisos y terminación de procesos que la code de la aplicación puede no observar nunca.
Asocia cada síntoma con su evidencia
En la capa WebView, recopila errores de consola, rechazos de promesas no manejados, eventos de navegación, URLs de solicitud, estado de respuesta y temporización de solicitudes. Un rechazo silencioso de plugin es especialmente peligroso. La UI puede seguir renderizando mientras una operación de cámara, sistema de archivos, almacenamiento seguro o notificación ya ha fallado.
El capa nativa contiene la salida de logcat de Android, iOS os_log registros, excepciones del puente de plugins, eventos de ciclo de vida de activity o view-controller y trazas de crash nativos. Electron añade el flujo de logs del proceso principal, eventos de auto-update, fallos en la creación de ventanas y mensajes IPC. Un error del renderer no aparecerá necesariamente en el proceso principal, y un crash del proceso principal no será visible en la salida de la consola del renderer.
El capa del SO explica eventos fuera del control de la aplicación. Busca presión de memoria, terminación en segundo plano, restricciones de batería, permisos denegados, kills de proceso e informes de crash a nivel de sistema. Esta capa suele explicar un "crash aleatorio" aparente que no tiene una pila de JavaScript útil.
Correlaciona antes de filtrar
Usa un ID de solicitud u operación compartido entre el WebView, el puente nativo, el backend y el sink central de logs. Añade el ID antes de que comience la acción del usuario y presérvalo a través de la solicitud de red y el callback nativo. Correlaciona las marcas de tiempo en un formato consistente, ten en cuenta la deriva de la hora del dispositivo y filtra el ruido del framework solo después de conservar el evento original.
Almacena los mismos campos contextuales en cada capa: versión de la app, hash del web bundle, canal, dispositivo, SO, sesión y estado de feature flags. La recopilación centralizada permite comparar un intento de reproducción con la evidencia del usuario en lugar de reemplazarla por suposiciones. Un práctico kit de análisis de logs para depuración móvil debe ayudarte a buscar esos campos sin obligar a los ingenieros a recopilar capturas de pantalla de cada dispositivo.
Depurando la capa web y la capa nativa
Depura la capa que posee el síntoma. Una pantalla congelada que aún responde a eventos de ciclo de vida nativo suele originarse en el WebView. Una terminación de proceso, una excepción de plugin o un fallo de arranque pertenecen a las herramientas nativas o al proceso principal de Electron. Saltar entre capas sin esa regla de enrutamiento genera actividad sin acotar la causa.
Empieza con el WebView
En Android, conecta un build debuggable de Capacitor a Chrome y abre chrome://inspect. Inspecciona la consola, el panel de red, el storage y la línea de tiempo de rendimiento. En iOS, usa Safari Web Inspector con el dispositivo o simulador conectado. Para Electron, conéctate al renderer mediante su puerto de DevTools o llama a BrowserWindow.webContents.openDevTools() durante la investigación.
Los stack traces de producción solo son útiles si mapean al código fuente. Sube y conserva los source maps de cada web bundle, luego verifica que el artefacto de simbolización coincida con el hash exacto del bundle. Añade un interceptor de consola controlado para operaciones críticas, pero evita loguear credenciales, tokens o datos personales. En su lugar, captura nombres de operaciones, request IDs, clases de respuesta y transiciones de estado.
Pasa a herramientas nativas cuando la evidencia apunte en esa dirección
Filtra el Logcat de Android Studio por el package de la aplicación y luego reproduce el error con la secuencia de acciones más corta posible. npx cap run android --livereload acorta el ciclo de iteración para cambios en la WebView, pero no valida el artefacto nativo empaquetado. En iOS, ejecuta desde Xcode y usa la ventana Devices para ver los logs del dispositivo. El Time Profiler de Instruments ayuda con el trabajo sostenido de CPU, mientras que Allocations ayuda a identificar el crecimiento de memoria.
Electron tiene dos objetivos de debugging. Usa el DevTools del renderer para el DOM, JavaScript y comportamiento de red. Usa --inspect o --inspect-brk para el proceso principal, y conserva su salida stderr durante las pruebas de arranque y auto-actualización.
Enruta según el síntoma. El comportamiento de la UI se origina en el WebView. La terminación nativa se origina en Android Studio o Xcode. Los fallos de arranque de Electron se originan en el proceso principal.
Una explicación útil de por qué importa esta separación aparece en el modelo de WebView y bridge nativo de Capacitor. El bridge es un límite, no una única superficie de depuración. Trátalo así y cada línea de log tendrá más probabilidades de responder a la pregunta que tienes.
Comprobaciones iniciales: Networking, Storage y permisos
Los equipos suelen revisar API primero porque los errores de red parecen técnicos y familiares. Ese hábito pasa por alto fallos causados por estado obsoleto, declaraciones de permisos modificadas o una actualización de la plataforma que alteró el comportamiento del sandbox. La comprobación más rápida depende del dominio del fallo.
| Dominio del fallo | Patrón de síntoma común | Comprobación más rápida |
|---|---|---|
| Redes | Datos vacíos, bucles de login, timeouts, uploads fallidos o peticiones que funcionan en una red pero no en otra | Ejecuta curl desde la misma red, inspecciona las solicitudes fallidas de WebView, revisa el preflight de CORS, el certificate pinning, los portales cautivos y el comportamiento del proxy |
| Almacenamiento | Una función funcionaba antes, pero falla tras una actualización, un reinicio o un cambio de sistema operativo | Inspecciona las estimaciones de almacenamiento, revisa los errores de cuota de IndexedDB, compara las claves de cifrado y verifica la userData ruta de Electron y prueba un sandbox limpio |
| Permisos | La cámara, los archivos, las notificaciones, la ubicación o el comportamiento en segundo plano fallan sin una excepción de aplicación clara | Revisa las descripciones de uso de iOS, Android ACCESS_* declaraciones, el manejador de permisos de Electron y el timing de permisos en el arranque en frío |
Para problemas de almacenamiento, storage.estimate() puede revelar presión de cuota, pero no diagnosticará cada problema de base de datos. Prueba un sandbox de aplicación limpiado manualmente y luego compara el comportamiento con el perfil existente. La rotación de la clave de cifrado de preferencias de Capacitor puede hacer que valores previamente válidos sean ilegibles, mientras que el registro de escritura anticipada de SQLite puede dejar un estado dañado tras una terminación abrupta. Las aplicaciones de Electron también pueden parecer perder datos cuando una actualización del sistema operativo cambia la ruta resuelta userData path.
Los permisos merecen la misma atención. Las descripciones de uso en iOS deben coincidir con la capacidad solicitada. El comportamiento de los permisos en Android puede variar tras cambios en SDK, y los prompts de notificación pueden solaparse con la inicialización en frío. El handler de permisos de Electron puede rechazar una solicitud antes de que el renderer reciba una explicación útil.
Si un usuario dice “ayer funcionaba”, revisa el almacenamiento y los permisos antes de asumir que cambió la red.
Tests automatizados y CI como sistemas de alerta temprana
CI detecta regresiones de forma más económica cuando testea el artefacto que usarán los usuarios. Una suite de tests en verde contra un servidor de desarrollo no garantiza que el paquete firmado de Android, el archivo de iOS o el instalador de Electron puedan arrancar, cargar su bundle y completar una operación autenticada real.
Testea la lógica compartida y los shells
Usa Vitest para la lógica web compartida y Jest para el comportamiento del main process de Electron. Para plugins de Capacitor, testea el contrato de JavaScript y la implementación nativa por separado, y luego añade cobertura de integración para la denegación de permisos, el hardware no disponible, las respuestas malformadas y las interrupciones del ciclo de vida.
Playwright puede probar un web bundle ya construido. Para Electron, usa Playwright Electron o un test de shell equivalente contra el binario empaquetado, no solo el renderer servido por un proceso de desarrollo local. El test empaquetado detecta assets faltantes, rutas incorrectas, errores de firma y supuestos de arranque que los tests de navegador ocultan.
La cobertura de dispositivos debe reflejar tu base instalada real. BrowserStack o Sauce Labs pueden probar un conjunto seleccionado a propósito de perfiles de dispositivos, sistemas operativos, estados de permisos y condiciones de red. El objetivo no es el tamaño máximo de la matriz, sino una cobertura representativa de fallos.
Haz que los fallos bloqueen el merge
Añade checks explícitos para:
- Cambios en el bundle: Rechaza deltas inesperados en el tamaño del bundle y la falta de source maps.
- Alineación nativa: Detecta drift de versiones de plugins e incompatibilidades
minSdkVersionde configuración. - Integridad de artefactos: Verifica firmas, identidad del paquete, assets embebidos y manifiestos de release.
- Comportamiento de inicio: Arranca la app empaquetada y completa una petición autenticada a un endpoint.
- Comportamiento de las actualizaciones: Instala un bundle anterior, aplica la actualización candidata, reinicia y confirma el comportamiento de rollback.
Publica cada resultado mediante un control de estado de GitHub para que una señal roja bloquee el merge. Un build que pase los unit tests pero falle la verificación de artefactos firmados debe tratarse como fallido, no como «casi todo en verde».
El configuración de CI para releases de Capacitor es útil al integrar estos controles en un pipeline repetible. La CI no sustituye a la telemetría de producción, pero reduce los defectos que llegan a staging y da a los ingenieros de guardia menos incógnitas durante un incidente.
Live Updates como canal de recuperación de emergencia
Una regresión en producción no siempre requiere un nuevo build nativo. Si el defecto está en JavaScript, CSS, textos, configuración u otro asset web, un live update puede restaurar el flujo del usuario mientras el equipo prepara un release en condiciones. Eso convierte la entrega de live updates en un canal de recuperación operativa, no solo en una comodidad para cambios cosméticos.
El requisito de seguridad es el control. Canales separados con nombre para audiencias canary, beta y stable. Mantén explícitos el ID de la app nativa y las restricciones de runtime compatibles, y registra qué bundle recibe cada audiencia. Un live update no puede añadir un permiso nativo, reemplazar un plugin nativo, cambiar el proceso principal de Electron o reparar un fallo que ocurra antes de que el updater se inicialice. Esos casos siguen necesitando un release en la tienda o un instalador.
Usa un despliegue controlado
Un flujo de emergencia debería verse así:
- Confirmar el alcance: Identifica las versiones nativas afectadas, los canales, los hashes de bundle y las señales de fallo.
- Prepara el parche más pequeño posible: Cambia solo el comportamiento web necesario para restaurar la ruta que falla.
- Dirígete a una audiencia canary: Envía el bundle a un canal controlado en lugar de a todas las instalaciones.
- Monitorea la telemetría: Revisa las señales de crash, carga, solicitud y fallo de actualización en la cohorte afectada.
- Promover o revertir: Expande solo si las señales siguen siendo saludables. Revierte de inmediato si el parche introduce un nuevo fallo.
El rollback automático debe usar umbrales explícitos de crash-rate o fallos de carga elegidos por el equipo. Un rollback solo protege a los usuarios si el updater puede detectar fallos y el bundle anterior sigue disponible. Mantén el historial de versiones y los guardrails del canal intactos para que soporte pueda explicar qué ocurrió en un dispositivo específico.
Capgo ofrece entrega de web-bundles firmados, canales segmentados, logs por dispositivo, métricas de adopción y fallos, historial de versiones y protección de rollback automático para aplicaciones CapacitorJS y Electron. La regla de decisión práctica es directa: usa un live update cuando el fix se limite al web bundle y el updater pueda iniciar de forma segura; programa un native hotfix cuando intervengan el runtime, plugin, permiso, package o proceso principal. El flujo de live-update de Capacitor describe el límite entre esos dos caminos.
Análisis post-incidente para prevenir el siguiente
Una retrospectiva vale la pena cuando cambia el sistema. Escríbela mientras los logs, el contexto de deployment y las decisiones del operador sigan disponibles. Mantén el registro objetivo, sin culpar a nadie y con el detalle suficiente para que otro ingeniero identifique el guardrail que faltó sin reconstruir todo el incidente.
Usa cinco bloques concretos
Timeline con timestamps de telemetría. Registra la primera solicitud fallida, la release afectada, la creación de la alerta, los pasos de investigación, la mitigación y la recuperación. Para el incidente del dashboard de Android, la línea de tiempo podría mostrar que la vista en blanco apareció después de un despliegue de configuración, mientras que iOS seguía recibiendo respuestas válidas.
Modo de fallo visible para el usuario. Describe lo que experimentaron los clientes, no lo que hizo code. «Los usuarios de Android vieron un dashboard vacío tras la autenticación» da más dirección a los responsables que «desajuste de clave de API». La primera descripción apunta hacia el flujo roto y las señales que deberían haberlo detectado.
Brecha de detección. Indica por qué el equipo se enteró tarde. El monitoreo de crashes pudo haberse mantenido en verde porque la app se renderizó correctamente, mientras que ninguna alerta rastreaba fallos en solicitudes autenticadas o payloads de dashboard vacíos. Registra la señal faltante y dónde debería haberse emitido.
Factores contribuyentes no relacionados con code. Enumera la deriva de configuración, el comportamiento de la caché, el momento del despliegue, las dependencias de servicios, los cambios de permisos o una carrera en la auto-actualización de Electron. Estos dominios merecen verificaciones tempranas porque un fallo en producción puede ocurrir sin un defecto en el code de la aplicación.
Barrera preventiva. Asigna el test o control que habría detectado el problema. Ejemplos: validar credenciales de producción durante el despliegue, verificar la configuración entregada desde clientes representativos o añadir un test de arranque para Electron empaquetado. Un guardrail necesita un responsable y una condición de fallo, no solo una frase en la retrospectiva.
Las rutas de notificación deben estar en la misma revisión. Si las alertas por correo no llegan al equipo, usa un recurso práctico sobre cómo evitar que el correo vaya a spam en Gmail durante la verificación de notificaciones, comprueba la ruta de la alerta. No consideres la creación exitosa del mensaje como prueba de que un operador haya recibido la alerta.
Asigna tareas antes de cerrar el incidente
Para cada bloque, nombra un responsable, una fecha límite y un método de verificación. Revisa el incidente de nuevo dentro de 24 horas, mientras los ingenieros aún pueden cuestionar los supuestos de la investigación. Cierra un elemento solo después de que la nueva prueba, dashboard, verificación de configuración o regla de rollout haya ejecutado con éxito.
Usa esta lista de verificación final:
- ¿Identificamos el native build y el web bundle exactos?
- ¿Distinguimos causas de code, configuración, despliegue, infraestructura y dependencias?
- ¿La telemetría mostró el fallo visible para el usuario, no solo los crashes?
- ¿Probamos el canal afectado y un canal conocido como estable?
- ¿Añadimos un guardrail que falle antes de producción?
- ¿Documentamos si un live update o una release nativa era apropiada?
- ¿Un responsable designado verificó la corrección?
Las quejas de usuarios muestran por qué la revisión debe cubrir más que crashes. En una auditoría de 6.634 apps, los fallos de pago afectaron a 28.6% de las apps, la compatibilidad de dispositivos 28.4%, la fricción de UI y UX 25.4%, los problemas de suscripción 21.8%, y los errores de login 17.2%, while crashes ranked seventh at 10.3%. (La auditoría de Bright App Data sobre quejas de apps móviles) Un proceso de troubleshooting que solo pregunta “¿por qué se cayó la app?” puede pasar por alto los fallos que impiden el pago, el inicio de sesión o el uso normal del producto.
Los datos de estabilidad respaldan el mismo modelo operativo. Una referencia sitúa la app mediana en 99,95 % de sesiones sin bloqueos, con las apps de mejor rendimiento en 99.99% y las más débiles en 99,77 % o menos. También informa de una mediana de tasa de ANR de 2,62 por 10.000 sesiones, una tasa de OOM de 1,12 por 10.000 sesiones, y las tasas de app-hang de 64 a 103 por cada 10.000 sesiones según el nivel de calidad. (El benchmark de estabilidad móvil) La alta estabilidad aún deja fallos significativos. Los equipos necesitan telemetría para solicitudes fallidas, estados en blanco, bloqueos, errores de actualización y otros síntomas visibles para el usuario.
Un informe de 2026 indica que los usuarios presentaron 6 veces más quejas sobre funciones básicas rotas que solicitudes de nuevas funciones, y reportes que el 15,4 % desinstala tras un solo crash, mientras que más de la mitad abandona tras 2-3 crashes. (El informe de 2026 sobre funciones básicas rotas) La respuesta es práctica: detectar de forma amplia, recuperar rápidamente y convertir cada incidente en un control testeable.
Usa Capgo para entregar actualizaciones firmadas de bundles web de CapacitorJS y Electron a través de canales controlados, inspeccionar la telemetría por dispositivo y revertir una corrección de JavaScript fallida sin esperar a la revisión de la tienda. Conéctalo al pipeline de release, define audiencias estables y canary, y prueba la ruta de recuperación antes de la próxima caída del dashboard.
