Pular al contenido

Depuración

GitHub

If you get a refusal de Cloudflare code and need deeper remediation walkthroughs, see Problemas de Actualización Comunes.

Capgo logs can include metadata for the event. In the dashboard, filter by the action code and click the metadata cell to copy the full JSON payload. Metadata is especially useful for crash and WebView events because it can include the error message, source URL, line and column, process state, memory pressure, or reason específico de la plataforma. Older logs can still show legacy camelCase aliases listed in parentheses.

Cada título de sección coincide con la acción code mostrada en la tabla de registros del console, por lo que puedes vincular directamente a ella.

Rechazos relacionados con la facturación, la 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. Las actualizaciones menos de cuatro horas antiguas se ignoran para que el tráfico de bots no se cuente como dispositivos facturables.

¿Qué hacer?

Ignora esto en usuarios reales. Vuelve a intentarlo desde redes normales y dispositivos reales, o espera y verifica de nuevo más tarde.

¿Qué significa

Su aplicación está configurada para bloquear solicitudes de rangos de direcciones IP de centros de datos de Google y Apple conocidos. 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 en otro sentido.

¿Qué hacer

Intenta desde un dispositivo físico en una red de usuario normal. Si el tráfico originado por el proveedor es intencional, desactiva temporalmente Bloquear solicitudes de infraestructura del proveedor en la pestaña de Información del aplicativo, luego habilita de nuevo después del test. Las nuevas aplicaciones habilitan este ajuste por defecto; las aplicaciones existentes retienen su configuración deshabilitada previa hasta que se cambie.

¿Qué significa

Su organización ha alcanzado su límite de plan o dispositivo. El dispositivo no recibirá actualizaciones hasta que se actualice o el próximo ciclo de facturación resete el uso.

¿Qué hacer

Actualice su plan en la consola o espere al próximo ciclo de facturación.

¿Qué significa

El dispositivo ya tiene el último paquete disponible para su canal. Este es un estado normal, no un error.

¿Qué significa

El dispositivo envió demasiadas solicitudes de actualización o de 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 de backend causados por metadatos de versión nativa inválidos.

¿Qué significa?

La versión del app nativa en la configuración está faltando o no es válida semver (x.y.z).

¿Qué hacer?

Establecer plugins.CapacitorUpdater.version a un semver válido, verifíquelo en el Prueba de SemVer, luego reconstruya e instale de nuevo la app nativa.

Rechazos de backend cuando la política de canal bloquea una plataforma, tipo de compilación o clase de dispositivo.

¿Qué significa?

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

¿Qué hacer?

Habilite iOS en el canal si esto fue accidental, o envíe compilaciones de iOS a un canal dedicado cuando el bloqueo sea intencional.

¿Qué significa?

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

¿Qué hacer?

Habilite Android en el canal si esto fue accidental, o envíe compilaciones de Android a un canal dedicado cuando el bloqueo sea intencional.

¿Qué significa?

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

¿Qué hacer?

Habilite Electron en el canal si esto fue accidental, o dirija las compilaciones de Electron a un canal dedicado cuando el bloqueo sea intencional.

¿Qué significa?

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

¿Qué hacer?

Permita ediciones de desarrollo en un canal de prueba, o mantenga este canal solo para lanzamientos y mueva los dispositivos de desarrollo a otro lugar.

¿Qué significa?

Una compilación de producción llamada /updatesPero las 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 redirigir compilaciones de producción al canal correcto.

¿Qué significa

Un teléfono o tableta real fue bloqueado porque este canal bloquea dispositivos reales.

¿Qué hacer

Habilitar actualizaciones de dispositivos reales si esto fue accidental, o mantener la restricción y redirigir dispositivos reales a otro canal.

¿Qué significa

El dispositivo es un emulador, pero las actualizaciones de emulador están deshabilitadas para este canal.

¿Qué hacer

Habilite actualizaciones de emulador en un canal de prueba, o mantenga este canal bloqueado para emulador y utilice otro canal para la validación de emulador.

Compatibilidad de reglas de actualización automática

Sección titulada “Compatibilidad de reglas de actualización automática”

Rechazos de backend 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. Los metadatos incluyen auto_update con una regla compatible como major, minor, patch, metadatao none.

¿Qué hacer

Cambie la política de actualización automática del canal para permitir su lanzamiento previsto.

¿Qué significa?

El canal tiene una paquetería más antigua que la base del dispositivo y bloquea enviar actualizaciones bajo la versión nativa.

¿Qué hacer?

Publicar una paquetería a o por encima de la base nativa, o deshabilitar 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 la paquetería objetivo o en una versión más nueva de la versión nativa.

¿Qué significa?

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

¿Qué hacer?

Alinea la estrategia de canal con tu plan de lanzamiento de versiones principales, o permite saltos de versión mayor para este track. Consulta Problemas de actualización comunes.

¿Qué significa?

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

¿Qué significa

Los canales bloquean cambios de nivel de parche mientras mantienen el mismo MAJOR.MINOR.PATCH prefijo; solo se permiten cambios de sufijo.

¿Qué hacer

Alinea el ritmo de lanzamiento con la política de canal, o permite saltos de parche para este track.

Rechazos de backend causados por 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 la compilación.

Rechazos del servidor de backend cuando Capgo no puede servir o descifrar el paquete.

¿Qué significa

Capgo no pudo generar una URL de descarga firmada válida y no se encontró un fallback de manifiesto.

¿Qué hacer

Vuelva a subir el paquete, regenere los manifiestos y verifique R2 o ajustes de paquete público.

¿Qué significa

El paquete asignado al canal no tiene contenido descargable: no external_url, no r2_path, no 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 metadatos puede incluir device_key_id, bundle_key_id, y version.

¿Qué hacer

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

Configuración de la aplicación y clientes legados

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

Rechazos del backend causados por 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 se establece en Capacitor la configuración, 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 se desaconseja en ediciones de producción.

¿Qué hacer

Eliminar o borrar server.url para ediciones de producción y mantener los paquetes de actualización locales. Esto code puede aparecer como una negativa del servidor o como un estado del lado del dispositivo.

¿Qué significa

El plugin de actualizador es v4, que ya no acepta el servidor.

¿Qué hacer

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

Eventos en el dispositivo para el flujo de actualización normal, activación y desactivación.

¿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 no pudo activarse en el dispositivo.

¿Qué hacer?

Verifique los registros nativos con npx @capgo/cli@latest app debug y verifique la integridad del paquete, rutas y notifyAppReady flujo.

¿Qué significa?

El dispositivo se reinició al paquete incorporado.

¿Qué significa?

Se eliminó un paquete en el dispositivo.

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

¿Qué significa?

Se inició la secuencia de descarga en un 0% de progreso.

¿Qué significa?

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

¿Qué significa?

Se ha descargado una nueva colección — el progreso se indica en el 20%.

¿Qué significa esto?

Se ha descargado una nueva colección — el progreso se indica en el 30%.

Se ha descargado una nueva colección — el progreso se indica en el 40%.

¿Qué significa esto?

Sección titulada “download_60”

¿Qué significa esto?

¿Qué significa esto?

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

¿Qué significa esto?

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

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

¿Qué significa esto?

¿Qué significa esto?

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

download_complete

¿Qué significa esto?

Sección titulada “download_complete”

The descarga del paquete se completó con éxito.

¿Qué significa?

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

¿Qué significa?

El dispositivo terminó de descargar el manifiesto de actualización.

¿Qué significa?

El dispositivo comenzó a descargar el archivo del paquete.

¿Qué significa?

The dispositivo terminó de descargar el archivo de la cesta.

¿Qué significa?

Una entrada del manifiesto falló al descargar. version_name se utiliza version:fileName para identificar el activo.

¿Qué hacer?

Reemplaza el activo faltante o bloqueado, regenera el manifiesto y vuelve a subir la cesta.

¿Qué significa?

Un archivo de manifiesto falló la validación de suma de comprobación.

¿Qué hacer?

Vuelva a subir el paquete con una versión actualizada de CLI y verifique los cálculos de checksum del manifiesto.

¿Qué significa?

Un archivo de manifiesto falló la descomposición Brotli.

¿Qué hacer?

Verifique los ajustes de compresión y vuelva a subir los activos afectados.

¿Qué significa?

El paquete no se pudo descargar.

¿Qué hacer?

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

What significa

La instalación del paquete se realizó con éxito pero la aplicación nunca llamó. notifyAppReadyPor lo tanto, Capgo se deshizo.

¿Qué hacer?

Llamar notifyAppReady() después de que la aplicación termine de inicializarse. El texto de registro nativo 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 antigua CLI de carga, o desacuerdo de clave de cifrado en plugins antiguos que presentan falla de descifrado como falla de checksum.

¿Qué hacer?

Re-subir con un CLI/plugin (SHA256) actual. 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 una verificación explícita keyMismatch errores.

¿Qué significa

No se pudo descifrar el paquete descargado.

¿Qué hacer

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

¿Qué significa

El zip contiene rutas de Windows ilegales.

¿Qué hacer

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

What it means

Los paths de archivos dentro del zip no son canónicos.

What to do

Corrija la generación de ruta del archivo antes de subir.

What it means

El zip contiene rutas de directorios inválidas.

What to do

Corrija la estructura del archivo antes de subir.

What it means

El dispositivo falló al descomprimir el paquete descargado.

¿Qué hacer

Verifique la integridad del archivo y el soporte para la 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.

Diagnósticos de dispositivo de fallas, memoria y WebView. Siempre inspeccione 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?

Crash de capa JavaScript o 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 JS con el informe de errores nativo (por ejemplo Sentry) para ubicar el camino de code fallido.

¿Qué significa?

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 la metadata.

¿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 de la hilera 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 inspeccione la metadata 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 el arranque fallaron antes de que estuviera lista la ejecución normal.

¿Qué hacer?

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

¿Qué significa?

Advertencia de memoria de iOS.

¿Qué hacer

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

¿Qué significa

Error de JavaScript no capturado en el WebView. Los metadatos pueden incluir mensaje, URL de origen, línea, columna y pila.

¿Qué hacer

Instalar el informe de errores en las capas de JS y nativas para capturar la línea exacta fallida en producción.

¿Qué significa

Rechazo de promesa no manejada en el WebView.

¿Qué hacer

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

¿Qué significa?

Un recurso de WebView no se cargó.

¿Qué hacer?

Utilice la URL de metadatos y detalles de estado para reparar 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.

What significa

La sesión de WebView anterior no se cerró limpiamente, lo que puede indicar bucles de crash después de una actualización.

What hacer

Correlaciona con eventos de crash y errores de WebView antes y después del reinicio.

What significa

El proceso de renderizado de Android WebView se ha salido.

What hacer

Inspecciona señales de crash del renderizador en metadatos y registros nativos.

What 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 los metadatos.

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

El cambio de versión del sistema operativo del dispositivo entre comprobaciones.

native_app_version_changed

¿Qué significa

La versión del almacen de aplicaciones nativas cambió, ayudando a separar los cambios en el paquete web de los cambios nativos.

Sección titulada “getChannel”

¿Qué significa

El dispositivo consultó su canal actual.

¿Qué significa

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

¿Qué significa

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

  • SUCCESS: se completó la instalación del paquete
  • ERROR: falló la instalación o descarga
  • PENDING: Descarga finalizada, pendiente de liberación
  • DELETED: Paquete eliminado, aún presentado para estadísticas
  • DOWNLOADING: Descargando actualmente un paquete

Existe un comando de depuración para los usuarios de Capgo de Cloudflare.

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 las actualizaciones no ocurren.

para encontrar tus registros en Xcode

para encontrar tus registros en Android Studio

  • Failed to download from corresponde a download_fail
  • notifyAppReady was not called, roll back current bundle corresponde a update_fail

Para depurar en iOS, necesitas descargar la aplicación en tu computadora, puedes 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 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 en 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 tres 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 opción de descarga del contenedor de la aplicación

Al seleccionar "Descargar contenedor…" se descargará y exportará una instantánea del sistema de archivos como un archivo .xcappdata que puedes explorar.

Archivo xcappdata descargado con menú contextual Mostrar contenido del paquete

Haz clic derecho en este archivo y selecciona Mostrar contenido del paquete para abrir la carpeta.

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

Estructura de la carpeta del contenedor de la aplicación de iOS mostrando carpetas de Documents y Library

Luego encontrarás una versión en 2 carpetas:

library/NoCloud/ionic_built_snapshots es necesario después del reinicio de la aplicación

y documents/versions para el recarga caliente

Para depurar en Android, necesitas acceder al dispositivo desde Android Studio:

  • Haz clic en Ver > Ventanas de herramientas > Explorador de archivos de dispositivo o haz clic en el botón Explorador de archivos de dispositivo en la barra de ventanas de herramientas para abrir el Explorador de archivos de dispositivo.
  • Selecciona un dispositivo de la lista desplegable.
  • Abre la ruta data/data/APP_NOMBRE/ donde APP_NOMBRE es tu 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”

Si estás utilizando Depuración para planificar el trabajo de plugin nativo, conecta con Usando @capgo/capacitor-actualizador para la capacidad nativa en Usando @capgo/capacitor-actualizador, Capgo Carpeta de Plugin para el flujo de trabajo del producto en el directorio de plugins Capgo 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 Alternativas de Plugins de Ionic Enterprise