Saltar al contenido

Depuración

GitHub

Si obtienes una negación de la nube code y necesitas walkthroughs de remediaciónde mayor profundidad, ve a Problemas de actualización comunes.

Capgo los registros pueden incluir metadatos para el evento. En la consola, filtra por la acción en snake_case code, y haz 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 plataforma.

Los titulares de cada sección coinciden con la acción code mostrada en la tabla de registros de la consola, por lo que puedes 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 en la nube. Se ignoran las 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. Intente de nuevo 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 IP de conocidos 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 probedores 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?

Intente de nuevo 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 en el menú de la aplicación Información en el menú de la aplicación, luego habilítelo nuevamente 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 alcanzó su límite de plan o dispositivo. El dispositivo no recibirá actualizaciones hasta que suba de categoría o el próximo ciclo de facturación resetee 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 breve 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 app 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 reconstruya y vuelva a instalar la aplicación nativa.

Sección titulada “desactivar plataforma iOS”

disablePlatformIos

¿Qué significa

El dispositivo ejecuta iOS, pero se han desactivado 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 sea 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 sea 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 sea 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 compilaciones 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?

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

¿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

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 previsto.

¿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

Publique un paquete a o por encima de la base nativa, o deshabilite 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 lanzamiento objetivo desde una versión nativa más nueva.

¿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 su plan de lanzamiento mayor, o permitir saltos mayores para este track. Consulte Problemas Comunes de Actualización.

¿Qué significa?

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

Rechazos del backend causados por una configuración de canal faltante 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 es falso) y el canal no es público.

¿Qué hacer

Habilitar 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 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 las 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 el ID se ignora.

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

Actualice el plugin y CLI a v5+ (preference v8) con Capacitor v5+, reconstruya y vuelva 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?

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 notifyAppReady flujo.

¿Qué significa

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

¿Qué significa

Se eliminó un paquete en el dispositivo.

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

¿Qué significa

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

¿Qué significa?

Se ha descargado una nueva paquetería — se indica el progreso en un 10%.

¿Qué significa?

Se ha descargado una nueva paquetería — se indica el progreso en un 20%.

¿Qué significa?

Se ha descargado una nueva paquetería — se indica el progreso en un 30%.

¿Qué significa?

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

¿Qué significa?

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

¿Qué significa?

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

¿Qué significa?

Se ha descargado un nuevo paquete — el progreso se indica en un 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 terminó descargando el manifiesto de actualización.

¿Qué significa?

El dispositivo comenzó a descargar el archivo de paquete.

¿Qué significa?

El dispositivo terminó descargando el archivo de paquete.

¿Qué significa?

Una entrada del manifiesto falló al descargarse. 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 ha podido 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 el aplicativo nunca llamó notifyAppReadyentonces Capgo se deshizo.

¿Qué hacer?

Llame notifyAppReady() después de que su aplicativo termine de inicializarse. Texto de registro nativo notifyAppReady was not called, roll back current bundle se mapea a este code.

¿Qué significa?

La descarga de la paquetería falló la validación de checksum. Causas comunes: desacuerdo entre CRC32 y SHA256 desde una antigua CLI de carga, o desacuerdo de clave de cifrado en plugins antiguos que presentan la falla de descifrado como falla de checksum.

¿Qué hacer?

Re-cargar 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 Título de la sección “decrypt_fail”

decrypt_fail

¿Qué significa?

La descarga de la paquetería falló en descifrar.

¿Qué hacer?

Verifique las claves de cifrado y re-cargue la paquetería con la pareja de claves correspondiente.

Section titled “update_fail”

¿Qué significa?

El zip contiene rutas de Windows ilegales.

¿Qué hacer?

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

¿Qué significa?

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

¿Qué hacer?

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

¿Qué significa?

El 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éntelo en un dispositivo con más memoria libre.

Diagnostics de dispositivo para crash, memoria y WebView. Inspeccione 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 crash en JavaScript o en Capacitor capa. 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?

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

¿Qué hacer?

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

¿Qué significa?

Un evento de no respuesta de la aplicación de Android.

¿Qué hacer?

Inspecciona las trazas de ANR en Logcat y reduce el trabajo de bloqueo en el hilo principal después de las actualizaciones.

¿Qué significa?

El sistema operativo mató la aplicación después de presión de memoria.

¿Qué hacer?

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

¿Qué significa?

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

¿Qué hacer?

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

¿Qué significa

El actualizador o arranque 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 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 las capas de JS y nativo para capturar la línea exacta que falla en producción.

¿Qué significa

Rechazo de promesa no manejada en el WebView.

¿Qué hacer

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

¿Qué significa

Un recurso del WebView falló para cargar.

¿Qué hacer

Utilice 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 la CSP utilizando la directiva de metadatos y detalles de URI bloqueados.

¿Qué significa?

La sesión de WebView anterior no se cerró de manera limpia, 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 salido.

¿Qué hacer?

Inspeccionar señales de crash del proceso de renderizado en metadatos y registros nativos.

¿Qué significa?

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

¿Qué hacer?

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

Eventos de contexto 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.

¿Qué significa

Se cambió la versión del sistema operativo del dispositivo entre comprobaciones.

¿Qué significa

Se cambió la versión de la tienda de aplicaciones nativas, lo que ayuda a separar los cambios de la cesta de la web de los cambios nativos.

¿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ó 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 eliminó el paquete, pero sigue presentado para estadísticas
  • DOWNLOADING: se está descargando actualmente un paquete

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

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 integrada para inspeccionar el sistema de archivos de las aplicaciones instaladas por desarrolladores en un dispositivo iOS. Opción de dispositivos y simuladores en el menú de Xcode

Para lograr esto:

  • 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.
  • Aquí 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 un contenedor de la aplicación

Seleccionar 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 recargar 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 NOMBRE_DE_LA_APLICACIÓN 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.