Passer à la navigation

Débogage

GitHub

If you get a cloud refusal code and need deeper remediation walkthroughs, see Les __CAPGO_KEEP_0__ logs peuvent inclure des métadonnées pour l'événement. Dans le tableau de bord, filtrez par l'action en camelCase __CAPGO_KEEP_1__ et cliquez sur la cellule de métadonnées pour copier le payload JSON complet. Les métadonnées sont particulièrement utiles pour les événements de crash et de WebView car elles peuvent inclure le message d'erreur, l'URL de source, la ligne et la colonne, l'état du processus, la pression de mémoire ou la raison spécifique au système d'exploitation. Les anciens logs peuvent toujours afficher des alias de camelCase legacy listés en parenthèses..

Capgo logs can include metadata for the event. In the dashboard, filter by the snake_case 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 platform-specific reason. Older logs can still show legacy camelCase aliases listed in parentheses.

Each section title matches the action code shown in the console logs table, so you can link directly to it.

Refus de backend liés à la facturation, à la limitation de vitesse ou à des états non d'erreur.

Ce que cela signifie

Capgo a détecté un trafic qui ressemble à celui qui provient de Google ou d'infrastructure cloud. Les mises à jour moins de quatre heures sont ignorées afin que le trafic de bot ne soit pas compté comme des appareils facturables.

Ce à quoi faire

Ignorer cela sur les utilisateurs réels. Réessayer à partir de réseaux normaux et d'appareils réels, ou attendre et vérifier à nouveau plus tard.

Ce que cela signifie

Votre organisation a atteint ses limites de plan ou d'appareil. L'appareil ne recevra pas de mises à jour jusqu'à ce que vous augmentiez ou que le prochain cycle de facturation réinitialise l'utilisation.

Ce à quoi faire

Mettez à jour votre plan dans le tableau de bord ou attendez le prochain cycle de facturation.

Ce que cela signifie

Le dispositif dispose déjà de la dernière mise à jour disponible pour son canal. C'est un état normal, pas une erreur.

Ce que cela signifie

Le dispositif a envoyé trop de demandes d'actualisation ou de canal dans une fenêtre de temps courte.

Que faire

Arrêtez d'appeler les API d'actualisation à l'intérieur des boucles de rendu. Appelez-les setChannel / getChannel seulement à partir d'actions de l'utilisateur, et définissez defaultChannel dans capacitor.config.

Format de version

Format de version

Les refus de backend sont causés par des métadonnées de version native invalides.

Ce qu'il signifie

La version de l'application native dans la configuration est manquante ou non valide SemVer (x.y.z).

Ce qu'il faut faire

Définir plugins.CapacitorUpdater.version à une version SemVer valide, vérifiez-la sur le Testeur de SemVer, puis reconstruisez et réinstallez l'application native.

Ciblage de plateforme et de construction

Ce qu'il faut faire

Refusaux de backend lorsqu'une politique de canal bloque une plateforme, un type de build ou une classe de dispositif.

Ce que cela signifie

Le dispositif tourne sous iOS, mais les mises à jour d'iOS sont désactivées pour ce canal.

Ce qu'il faut faire

Activer iOS dans le canal si cela était accidentel, ou acheminer les builds iOS vers un canal dédié lorsque le blocage est intentionnel.

Ce que cela signifie

Le dispositif tourne sous Android, mais les mises à jour d'Android sont désactivées pour ce canal.

Ce qu'il faut faire

Activer Android dans le canal si cela était accidentel, ou acheminer les builds Android vers un canal dédié lorsque le blocage est intentionnel.

Ce que cela signifie

Le dispositif tourne sur Electron, mais les mises à jour d'Electron sont désactivées pour ce canal.

Que faire

Activez Electron dans le canal si cela était accidentel, ou dirigez les builds d'Electron vers un canal dédié lorsque le blocage est intentionnel.

Ce que cela signifie

Le dispositif est une build de développement, mais les builds de dev sont bloqués pour ce canal.

Que faire

Autorisez les builds de dev dans un canal de test, ou maintenez ce canal en version de production et déplacez les dispositifs de dev ailleurs.

Ce que cela signifie

Une build de production appelée /updates Mais les mises à jour de production sont bloquées pour ce canal.

Que faire

Permettre les mises à jour de production dans le canal si c'était une erreur, ou rediriger les builds de production vers le canal correct.

Ce que cela signifie

Un téléphone ou une tablette réelle a été bloqué car ce canal bloque les appareils réels.

Que faire

Activer les mises à jour d'appareils réels si c'était une erreur, ou maintenir la restriction et rediriger les appareils réels vers un autre canal.

Ce que cela signifie

L'appareil est un émulateur, mais les mises à jour d'émulateur sont désactivées pour ce canal.

Que faire

Activez les mises à jour de l'émulateur dans un canal de test, ou maintenez ce canal bloqué par l'émulateur et utilisez un autre canal pour la validation de l'émulateur.

Compatibilité des règles de mise à jour automatique

Section intitulée “Compatibilité des règles de mise à jour automatique”

Refus de backend lorsqu'une règle de semver ou de métadonnées bloque le bundle cible.

Ce que cela signifie

La mise à jour automatique est désactivée par la politique de compatibilité du canal. Les métadonnées incluent auto_update avec une règle correspondante comme major, minor, patch, metadata, ou none.

Ce à quoi faire

Modifier la politique de mise à jour automatique du canal pour permettre votre lancement prévu.

Ce que cela signifie

Le canal a un bundle plus ancien que la base de version native du dispositif et bloque l'envoi d'actualisations sous la version native.

Ce à quoi il faut faire

Publiez un bundle à ou au-dessus de la base de version native, ou désactivez la protection sous-version native dans le canal.

Ce que cela signifie

Le canal nécessite min_update_version, mais la version native du dispositif est en dessous de ce seuil.

Ce à quoi il faut faire

Définissez min_update_version sur le bundle cible ou la version de sortie à partir d'une version native plus récente.

Ce qu'il signifie

Le canal bloque les sauts de version majeure, par exemple 1.x.x à 2.x.x.

Ce qu'il faut faire

Alignez la stratégie de canal avec votre plan de mise à jour majeure, ou autorisez les sauts de version majeure pour ce suivi. Voir Problèmes de mise à jour courants.

Ce qu'il signifie

Le canal bloque les sauts de version mineure par rapport au niveau de base natif du dispositif (version_build), par exemple 1.2.3 à 1.3.0.

Ce qu'il faut faire

Aligner la stratégie de canal avec votre plan de mise à jour mineure, ou permettre des sauts mineurs pour cette piste.

Ce que cela signifie

Les blocs de canal empêchent les modifications au niveau des correctifs tout en conservant le même MAJOR.MINOR.PATCH préfixe; seuls les changements au niveau des suffixes sont autorisés.

Ce qu'il faut faire

Aligner le rythme de mise à jour avec la politique de canal, ou permettre des sauts de correctifs pour cette piste.

Les refus de serveur causés par une configuration de canal manquante ou incompatible.

Ce que cela signifie

Le dispositif a essayé de se connecter à un canal privé qui ne permet pas la mise en relation automatique des appareils (allow_device_self_set Qu'est-ce que vous devez faire

Activer

sur le canal ou basculer le dispositif vers un canal public ou autorisé. allow_device_self_set Section intitulée “channelMisconfigured”

channelMisconfigured

Qu'est-ce que cela signifie

Le canal utilise

mais le bundle disable_auto_update: "version_number" est null, donc __CAPGO_KEEP_0__ ne peut pas décider quelles appareils doivent se mettre à jour. min_update_version is null, so Capgo cannot decide which devices should update.

Remplir la configuration manquante pour cette règle ou basculer vers un mode de mise à jour automatique plus simple.

Section intitulé "channelMisconfigured"

Ce que cela signifie

Aucun canal par défaut n'est configuré et le dispositif n'a pas de surcharge de canal.

Que faire

Configurez un canal par défaut dans le tableau de bord ou configurez defaultChannel le build.

Refus du serveur de backend lorsque Capgo ne peut pas servir ou déchiffrer l'ensemble.

Ce que cela signifie

Capgo a échoué à générer une URL de téléchargement signée valide et aucune substitution de manifeste n'était disponible.

Que faire

Ré-uploader le bundle, régénérer les manifestes et vérifier les paramètres R2 ou du bundle public.

Ce que cela signifie

Le bundle attribué au canal n'a pas de contenu téléchargeable : aucun external_url, aucun r2_path, pas une version intégrée, et aucune entrée de manifeste.

Que faire

Reconstruire et ré-uploader la version, puis confirmer que le bundle a un contenu de fichiers réel.

Ce que cela signifie

La clé publique de chiffrement du dispositif ne correspond pas à la clé utilisée pour chiffrer le bundle. Les métadonnées peuvent inclure device_key_id, bundle_key_id, et version.

Qu'est-ce à faire

Comparez les clés ID de l'appareil et du bundle dans la console. Publiez avec la même clé et les mêmes versions CLI/plugin.

Refus de l'arrière-plan causé par la configuration de l'application ou des versions de l'actualiseur non supportées.

Qu'est-ce que cela signifie

L'application a envoyé un ID de appareil personnalisé, mais cette application ne prend pas en charge les IDs personnalisés, donc l'ID est ignoré.

Qu'est-ce à faire

Arrêtez d'envoyer des IDs personnalisés, ou activez les IDs personnalisés uniquement lorsque votre flux de travail les nécessite.

Ce que cela signifie

server.url est défini dans la configuration Capacitor, donc la vue Web charge une URL distante au lieu de fichiers de bundle locaux. Les mises à jour en temps réel Capgo nécessitent des fichiers locaux et server.url est déconseillé en production.

Que faire

Supprimer ou effacer server.url pour les builds de production et garder les payloads de mise à jour locaux. Cela code peut apparaître comme une refus de backend ou comme un statut du côté du dispositif.

Ce que cela signifie

Le plugin de mise à jour est v4, qui n'est plus accepté par le backend.

Que faire

Mettre à jour le plugin et CLI à v5+ (préférer v8) avec Capacitor v5+, reconstruire et républier les métadonnées du bundle.

Cycle de vie de la mise à jour

Section intitulée « Cycle de mise à jour »

Événements côté appareil pour le flux de mise à jour normal, d'activation et de reversion.

Ce qu'il signifie

Action de test interne utilisée pour vérifier le pipeline de statistiques.

Ce qu'il signifie

Capgo a envoyé des informations de téléchargement pour une nouvelle version vers l'appareil.

Ce qu'il signifie

Un bundle a été activé sur l'appareil.

Qu'est-ce que cela signifie

Un bundle a échoué à s'activer sur le dispositif.

Qu'est-ce qu'il faut faire

Vérifiez les journaux natifs avec npx @capgo/cli@latest app debug et vérifiez l'intégrité du bundle, des chemins et du notifyAppReady flux.

Qu'est-ce que cela signifie

Le dispositif a été réinitialisé sur le bundle intégré.

Qu'est-ce que cela signifie

Un bundle a été supprimé sur le dispositif.

Événements côté appareil pour le suivi du téléchargement, de la validation de l'archive et des erreurs d'installation.

Ce que cela signifie

La séquence de téléchargement a commencé à 0% de progression.

Ce que cela signifie

Un nouveau bundle a été téléchargé — progression indiquée à 10%.

Ce que cela signifie

Un nouveau bundle a été téléchargé — progression indiquée à 20%.

Ce que cela signifie

Un nouveau bundle a été téléchargé — progression indiquée à 30%.

Ce que cela signifie

Un nouveau bundle a été téléchargé — progression indiquée à 40%.

Ce que cela signifie

Un nouveau bundle a été téléchargé — progression indiquée à 50%.

Ce que cela signifie

Un nouveau bundle a été téléchargé — progression indiquée à 60%.

Ce que cela signifie

Un nouveau bundle a été téléchargé — progression indiquée à 70%.

Ce que cela signifie

Un nouveau bundle a été téléchargé — progression indiquée à 80%.

Ce que cela signifie

Un nouveau bundle a été téléchargé — progression indiquée à 90%.

Ce que cela signifie

Le téléchargement du bundle s'est terminé avec succès.

Ce que cela signifie

Le dispositif a commencé à télécharger le manifeste d'actualisation.

Ce que cela signifie

Le dispositif a terminé de télécharger le manifeste d'actualisation.

Ce que cela signifie

Le dispositif a commencé à télécharger l'archive du bundle.

Ce que cela signifie

Le dispositif a terminé de télécharger l'archive du bundle.

Ce qu'il signifie

Un élément de manifeste n'a pas pu être téléchargé. version_name utilise version:fileName pour identifier l'asset.

Ce qu'il faut faire

Réparez l'asset manquant ou bloqué, régénérez le manifeste et ré-uploadez le bundle.

Ce qu'il signifie

Un fichier de manifeste a échoué la validation de son checksum.

Ce qu'il faut faire

Ré-uploadez le bundle avec une version actuelle CLI et vérifiez les checksums de manifeste.

Ce que cela signifie

Un fichier de manifeste a échoué à décompresser Brotli.

Que faire

Vérifiez les paramètres de compression et ré-uploadez les actifs affectés.

Ce que cela signifie

Le bundle a échoué à se télécharger.

Que faire

Vérifiez la connectivité réseau, l'expiration des URL signées, la disponibilité du CDN et l'espace de stockage du dispositif.

Ce que cela signifie

Le bundle a été installé mais l'application n'a jamais appelé notifyAppReady, donc Capgo a été annulé.

Qu'est-ce que faire

Appeler notifyAppReady() après que votre application ait terminé de se démarrer. Le texte de journal natif notifyAppReady was not called, roll back current bundle se traduit par ce code.

Ce que cela signifie

Le bundle téléchargé a échoué la validation de checksum. Causes courantes : décalage CRC32 vs SHA256 d'un ancien CLI de téléchargement, ou décalage de clé de chiffrement sur les anciens plugins qui rendent la défaillance de déchiffrement comme une défaillance de checksum.

Qu'est-ce que faire

Ré-télécharger avec un CLI/plugin (SHA256) actuel. Si vous utilisez la chiffrement, vérifiez que la clé publique de l'application correspond à la clé de téléchargement, ou mettez à jour le plugin 8.3.0+ pour des erreurs explicites. keyMismatch Re-upload with a current __CAPGO_KEEP_0__/plugin (SHA256). If using encryption, verify the app public key matches the upload key, or upgrade to plugin 8.3.0+ for explicit

Ce que cela signifie

Le bundle téléchargé a échoué à se déchiffrer.

Que faire

Vérifiez les clés d'encryption et ré-uploadez le bundle avec la paire de clés correspondante.

Ce que cela signifie

Le zip contient des chemins Windows illégaux.

Que faire

Rebâtissez le bundle sur des chemins Unix ou nettoyez les chemins d'archive avant l'upload.

Ce que cela signifie

Les chemins de fichiers à l'intérieur du zip ne sont pas canoniques.

Ce qu'il faut faire

Fixez la génération du chemin d'archive avant l'envoi.

Ce que cela signifie

Le zip contient des chemins de répertoire non valides.

Ce qu'il faut faire

Fixez la structure de l'archive avant l'envoi.

Ce que cela signifie

Le dispositif a échoué à dézipper le bundle téléchargé.

Ce qu'il faut faire

Vérifiez l'intégrité de l'archive et les compressions supportées.

Ce que cela signifie

Téléchargement échoué car le dispositif a manqué de mémoire.

Ce que faire

Réduire la taille du bundle ou réessayer sur un appareil avec plus de mémoire gratuite.

État de santé de l'application et les événements WebView

Section intitulée “App health and WebView events”

Diagnostic de panne, de mémoire et de WebView côté appareil. Inspectez toujours le JSON de métadonnées dans le tableau de bord.

Ce que cela signifie

L'application est entrée en arrière-plan.

Cela signifie

L'application est entrée en avant-plan.

Cela signifie

Crash du JavaScript ou du niveau Capacitor. Les métadonnées peuvent inclure un message, une pile, une source et un contexte de bundle actif.

À faire

Inspectez les métadonnées et les journaux natifs. Associez le reporting d'erreurs JavaScript et natif (par exemple Sentry) pour localiser le chemin de code en panne.

Cela signifie

Crash du niveau natif. Les métadonnées peuvent inclure le système d'exploitation, la raison, la pile et les détails du processus.

À faire

Utilisez Xcode ou les journaux de crash Logcat et corrèlez-les avec le bundle actif à partir des métadonnées.

Ce que cela signifie

Événement d'application non réactive Android.

Ce que faire

Inspectez les traces ANR dans Logcat et réduisez le travail de blocage de la thread principale après les mises à jour.

Ce que cela signifie

L'OS a tué l'application après une pression sur la mémoire.

Ce que faire

Réduisez l'utilisation de la mémoire après l'activation des mises à jour et inspectez les métadonnées pour les signaux de mémoire disponibles.

Ce que cela signifie

L'OS a tué l'application en raison d'un usage excessif des ressources.

Que faire

Inspectez les métadonnées pour le type de ressource ou la raison de la plateforme.

Ce que cela signifie

L'actualisation ou le démarrage a échoué avant que le runtime normal soit prêt.

Que faire

Inspectez les métadonnées pour l'étape en échec et le message d'erreur.

Ce que cela signifie

Avertissement de la mémoire iOS.

Qu'est-ce à faire

Inspectez le contexte de la mémoire dans les métadonnées et réduisez l'utilisation maximale après les mises à jour.

Ce que cela signifie

Erreur JavaScript non capturée dans le WebView. Les métadonnées peuvent inclure le message, l'URL de la source, la ligne, la colonne et la pile.

Qu'est-ce à faire

Installez la gestion des erreurs dans les couches JS et natives pour capturer exactement la ligne en cause en production.

Ce que cela signifie

Réjection de promesse non traitée dans le WebView.

Qu'est-ce à faire

Capturez les échecs asynchrones avec la gestion des erreurs JS et natives.

Ce que cela signifie

Une ressource WebView a échoué à se charger.

Que faire

Utilisez l'URL de métadonnées et les détails du statut pour réparer les actifs endommagés ou les règles de réseau.

Ce que cela signifie

La politique de sécurité de contenu a bloqué une ressource.

Que faire

Ajustez la CSP en utilisant la directive de métadonnées et les détails de l'URI bloquée.

Ce que cela signifie

La session WebView précédente n'a pas fermé proprement, ce qui peut indiquer des boucles de crash après une mise à jour.

Qu'est-ce que vous devez faire

Corréler avec les événements de crash et d'erreur WebView avant et après le redémarrage.

Qu'est-ce que cela signifie

Le processus de rendu WebView Android est sorti.

Qu'est-ce que vous devez faire

Inspecter les signaux de crash du rendu dans les métadonnées et les journaux natifs.

Qu'est-ce que cela signifie

Le processus de contenu WebView iOS est terminé.

Qu'est-ce que vous devez faire

Inspectez le bundle actif et l'URL de la page à partir des métadonnées.

Événements de contexte côté appareil qui aident à corriger le comportement de mise à jour avec le système d'exploitation, la version native ou les changements de canal.

Ce que cela signifie

La version du système d'exploitation de l'appareil a changé entre les vérifications.

Ce que cela signifie

La version de l'application native du magasin a changé, ce qui aide à séparer les changements de bundle web et natif.

Ce que cela signifie

Le dispositif a interrogé son canal actuel.

Ce que cela signifie

Un canal a été configuré avec succès pour le dispositif.

Ce que cela signifie

L'application a été désinstallée ou les données Capgo ont été effacées.

  • SUCCESS : installation du paquet terminée
  • ERROR : installation ou téléchargement échoué
  • PENDING : téléchargement terminé, en attente de publication
  • DELETED: Paquet supprimé, toujours présent pour les statistiques
  • DOWNLOADING: En cours de téléchargement d'un paquet

Il existe une commande de débogage pour les utilisateurs Capgo de Cloudflare.

Fenêtre de terminal
npx @capgo/cli@latest app debug

Cela vous permettra de vérifier tous les événements se produisant dans l'application et de trouver une solution si les mises à jour ne se produisent pas.

pour trouver vos logs sur Xcode

pour trouver vos logs sur Android studio

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

Pour déboguer sur iOS, vous devez dump l'application sur votre ordinateur, vous pouvez le faire comme ceci :

Xcode a une fonctionnalité intégrée pour inspecter le système de fichiers des applications installées par les développeurs sur un appareil iOS. Menu Xcode Fenêtre montrant l'option Appareils et Simulateurs

Pour atteindre cela :

  • Connectez votre appareil à votre Mac et sélectionnez Fenêtre > Appareils dans le menu Xcode.
  • Sélectionnez votre appareil dans le panneau de gauche sous la section Appareils.
  • Cela affichera une liste des applications installées par les développeurs pour cet appareil.
  • Sélectionnez l'application que vous souhaitez inspecter et sélectionnez ensuite l'icône de trois points près du bas de l'écran.
  • Voici où vous pouvez afficher le système de fichiers actuel en sélectionnant télécharger un instantané de celui-ci.

Panneau Appareils Xcode montrant l'option de téléchargement du conteneur d'application

La sélection du conteneur de téléchargement… téléchargera et exporter un instantané du système de fichiers sous forme de fichier .xcappdata que vous pouvez parcourir.

Fichier xcappdata téléchargé avec le menu contextuel Afficher le contenu du package

Cliquez avec le bouton droit sur ce fichier et sélectionnez Afficher le contenu du package pour ouvrir le dossier.

Ouvrez le dossier App Data, et vous devriez maintenant voir quelques dossiers comme Documents, Bibliothèque, tmp, etc.

Structure du dossier du conteneur de l'application iOS montrant les dossiers Documents et Bibliothèque

Vous trouverez ensuite une version dans 2 dossiers :

library/NoCloud/ionic_built_snapshots est nécessaire après le redémarrage de l'application

et documents/versions pour le rechargement chaud

Pour déboguer sur Android, vous devez accéder au dispositif depuis Android Studio :

  • Cliquez sur Vue > Outils > Explorateur de fichiers de l'appareil ou cliquez sur le bouton Explorateur de fichiers de l'appareil dans la barre d'outils pour ouvrir l'Explorateur de fichiers de l'appareil.
  • Sélectionnez un appareil dans la liste déroulante.
  • Ouvrez le chemin data/data/__CAPGO_KEEP_0__/__CAPGO_KEEP_0__ est votre ID d'application.

Explorateur de fichiers de l'appareil Android Studio montrant le répertoire des données de l'application

Ensuite Trouvez le versions dossier pour voir toutes les versions

Comprendre les journaux de crash iOS

Comprendre les journaux de crash iOS

Continuez de la section Débogage

Comment planifier le travail de plugin natif

Débogage Pour planifier le travail de plugin natif, connectez-le à Utilisation de @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-mises à jour Utilisation de @capgo/capacitor-mises à jour pour la capacité native dans Utilisation de @capgo/capacitor-mises à jour for the native capability in Using @capgo/capacitor-updater, Capgo Répertoire de plugin pour le flux de travail de produit dans Capgo Répertoire de plugin for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Ajouter ou Mettre à Jour des Plugins pour le détail d'implémentation dans Ajouter ou Mettre à Jour des Plugins, et Alternatives de Plugins Entreprise Ionic pour le flux de travail du produit dans Alternatives de Plugins Entreprise Ionic.