Aller au contenu

Débogage

GitHub

En cas de refus cloud code et si vous avez besoin de guides de résolution plus détaillés, consultez Problèmes courants de mise à jour.

Les logs Capgo peuvent inclure des métadonnées pour l’événement. Dans le dashboard, filtrez par l’action code en snake_case, puis cliquez sur la cellule des métadonnées pour copier la charge utile JSON complète. Les métadonnées sont particulièrement utiles pour les événements de crash et de WebView, car elles peuvent contenir le message d’erreur, l’URL source, la ligne et la colonne, l’état du processus, la pression mémoire ou la raison spécifique à la plateforme. Les anciens logs peuvent encore afficher les alias camelCase legacy listés entre parenthèses.

Chaque titre de section correspond à l’action code affichée dans le tableau des logs de la console, ce qui permet d’y accéder directement.

Refus backend liés à la facturation, au throttling ou à des états non-erreur.

Signification

Capgo a détecté un trafic qui semble provenir de Google ou d’infrastructures cloud. Les mises à jour datant de moins de quatre heures sont ignorées afin que le trafic des bots ne soit pas comptabilisé comme des appareils facturables.

Que faire

Ignorez cela pour les utilisateurs réels. Réessayez via un réseau classique et un appareil réel, ou attendez et vérifiez plus tard.

Signification

Votre application est configurée pour bloquer les requêtes provenant des plages d'IP connues des datacenters Google et Apple. Cette protection s'applique aux vérifications de mise à jour, aux statistiques et aux requêtes channel-self ; les sondes hébergées dans le cloud et les runners des fournisseurs peuvent donc recevoir cette réponse même si la configuration de l'application est valide par ailleurs.

Que faire

Réessayez depuis un appareil physique sur un réseau utilisateur classique. Si le trafic provenant du fournisseur est intentionnel, désactivez temporairement Bloquer les requêtes d'infrastructure du fournisseur dans l'onglet Informations de l'application, puis réactivez-l’après le test. Les nouvelles applications activent ce paramètre par défaut ; les applications existantes conservent leur réglage désactivé précédent jusqu'à modification.

Signification

Your organization reached its plan or device limit. The device will not receive updates until you upgrade or the next billing cycle resets usage.

Que faire

Mettez à niveau votre plan dans le dashboard ou attendez le prochain cycle de facturation.

Signification

L’appareil dispose déjà du dernier bundle disponible pour son canal. C’est un état normal, pas une erreur.

Signification

L’appareil a envoyé trop de requêtes de mise à jour ou de canal sur une courte période.

Que faire

Arrêtez d’appeler les API de mise à jour dans des boucles de rendu. Appelez setChannel / getChannel uniquement depuis des actions utilisateur, et définissez defaultChannel dans capacitor.config.

Refus du backend causés par des métadonnées de version native invalides.

Signification

La version de l'app native dans la config est manquante ou n'est pas un semver valide (x.y.z).

Que faire

Définissez plugins.CapacitorUpdater.version pour un semver valide, vérifiez-la dans la testeur SemVer, puis recompilez et réinstallez l'app native.

Refus du backend lorsque la politique du canal bloque une plateforme, un type de build ou une classe d'appareil.

Signification

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

Que faire

Activez iOS pour ce canal si c'est involontaire, ou redirigez les builds iOS vers un canal dédié si le blocage est intentionnel.

Signification

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

Que faire

Activez Android dans le canal si c’était accidentel, ou orientez les builds Android vers un canal dédié si le blocage est intentionnel.

Signification

L’appareil exécute Electron, mais les mises à jour Electron sont désactivées pour ce canal.

Que faire

Activez Electron dans le canal si c’était accidentel, ou orientez les builds Electron vers un canal dédié si le blocage est intentionnel.

Signification

L’appareil est un build de développement, mais les builds de développement sont bloqués pour ce canal.

Que faire

Autorisez les builds dev dans un canal de test, ou limitez ce canal aux releases et déplacez les appareils dev ailleurs.

Signification

Un build de production appelé /updates, mais les mises à jour de production sont bloquées pour ce canal.

Que faire

Autorisez les mises à jour de production dans le canal si c’était accidentel, ou dirigez les builds de production vers le bon canal.

Signification

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

Que faire

Activez les mises à jour sur appareil réel si c’était accidentel, ou conservez la restriction et redirigez les appareils réels vers un autre canal.

Signification

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

Que faire

Activez les mises à jour sur émulateur dans un canal de test, ou gardez ce canal bloqué pour les émulateurs et utilisez un autre canal pour la validation sur émulateur.

Règles de compatibilité auto-update

Section titled “Auto-update compatibility rules”

Refus du backend lorsque les règles semver ou de métadonnées bloquent le bundle cible.

Signification

L'auto-update est désactivé par la politique de compatibilité du canal. Les métadonnées incluent auto_update avec une règle correspondante telle que major, minor, patch, metadata, ou none.

Que faire

Modifiez la politique de mise à jour automatique du canal pour autoriser le déploiement prévu.

Signification

Le canal contient un bundle plus ancien que la baseline de l’appareil et bloque l’envoi de mises à jour sous la version native.

Que faire

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

Signification

Le canal exige min_update_version, mais la version native de l’appareil est inférieure à ce seuil.

Que faire

Définissez min_update_version sur le bundle ou la release cible d'une version native plus récente.

Signification

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

Que faire

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

Signification

Le canal bloque les sauts de version mineure par rapport à la version native de l'appareil ("version_build), par exemple 1.2.3 vers 1.3.0.

Que faire

Align channel strategy with your minor rollout plan, or allow minor jumps for this track.

Signification

Le canal bloque les modifications de niveau patch tout en conservant le même MAJOR.MINOR.PATCH prefix; only suffix changes are allowed.

Que faire

Alignez la cadence de release avec la politique du canal, ou autorisez les sauts de patch pour cette piste.

Refus du backend dus à une configuration de canal manquante ou incompatible.

Signification

L'appareil a tenté de s'associer à un canal privé qui n'autorise pas l'auto-assignation des appareils (allow_device_self_set vaut false) et le canal n'est pas public.

Que faire

Activer allow_device_self_set sur le canal ou basculez l'appareil vers un canal public ou autorisé.

Signification

Le canal utilise disable_auto_update: "version_number" mais le bundle min_update_version est null, donc Capgo ne peut pas décider quels appareils doivent être mis à jour.

Que faire

Complétez la configuration manquante pour cette règle ou passez à un mode d'auto-update plus simple.

Signification

Aucun canal par défaut n'est configuré et l'appareil n'a pas d'override de canal.

Que faire

Définissez un canal par défaut dans le dashboard ou configurez-le defaultChannel lors du build.

Refus du backend lorsque Capgo ne peut pas fournir ou déchiffrer le bundle.

Signification

Capgo n’a pas pu générer une URL de téléchargement signée valide et aucun manifeste de secours n’était disponible.

Que faire

Réenvoyez le bundle, régénérez les manifestes et vérifiez les paramètres R2 ou de bundle public.

Signification

Le bundle assigné au canal ne contient aucun contenu téléchargeable : aucun external_url, non r2_path, pas une version intégrée, et aucune entrée dans le manifeste.

Que faire

Recompilez et renvoyez la version, puis vérifiez que le bundle contient bien des fichiers réels.

Signification

La clé publique de chiffrement de l'appareil 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.

Que faire

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

Refus du backend causés par la configuration de l'app ou des versions de l'updater non supportées.

Signification

L'app a envoyé un ID d'appareil personnalisé, mais cette app n'accepte pas les ID personnalisés ; l'ID est donc ignoré.

Que faire

Arrêtez d’envoyer des identifiants personnalisés, ou activez-les uniquement si votre workflow l’exige.

Signification

server.url est défini dans la configuration Capacitor, de sorte que la WebView charge une URL distante au lieu des fichiers du bundle local. Les live updates Capgo nécessitent des fichiers locaux et server.url est déconseillé en production.

Que faire

Supprimer ou vider server.url pour les builds de production et garder les payloads de mise à jour en local. Ce code peut se manifester par un refus du backend ou une stat côté appareil.

Signification

Le plugin updater est en v4, une version que le backend n’accepte plus.

Que faire

Passez le plugin et CLI en v5+ (de préférence la v8) avec Capacitor v5+, recompilez et republiez les métadonnées du bundle.

Événements côté appareil pour le flux de mise à jour normal, l’activation et le rollback.

Signification

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

Signification

Capgo a envoyé à l’appareil les informations de téléchargement d’une nouvelle version.

Signification

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

Signification

L’activation d’un bundle a échoué sur l’appareil.

Que faire

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

Signification

L’appareil a été réinitialisé sur le bundle intégré.

Signification

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

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

Signification

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

Signification

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

Signification

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

Signification

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

Signification

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

Signification

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

Signification

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

Signification

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

Signification

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

Signification

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

Signification

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

Signification

L’appareil a commencé à télécharger le manifeste de mise à jour.

Signification

L’appareil a terminé le téléchargement du manifeste de mise à jour.

Signification

L’appareil a commencé à télécharger l’archive du bundle.

Signification

L'appareil a fini de télécharger l'archive du bundle.

Signification

Une entrée du manifeste n'a pas pu être téléchargée. version_name utilise version:fileName pour identifier l'asset.

Que faire

Corrigez l'asset manquant ou bloqué, régénérez le manifeste et renvoyez le bundle.

Signification

La validation du checksum du fichier manifest a échoué.

Que faire

Re-upload the bundle avec une version actuelle de CLI et vérifiez les checksums du manifest.

Signification

Un fichier manifest a échoué lors de la décompression Brotli.

Que faire

Vérifiez les paramètres de compression et renvoyez les assets concernés.

Signification

Le téléchargement du bundle a échoué.

Que faire

Vérifiez la connectivité réseau, l’expiration de l’URL signée, l’accessibilité du CDN et le stockage de l’appareil.

Signification

Le bundle a été installé mais l'app n'a jamais appelé notifyAppReady, donc Capgo a effectué un rollback.

Que faire

Appelez notifyAppReady() après le bootstrapping de votre application. Texte des logs natifs notifyAppReady was not called, roll back current bundle correspond à ce code.

Signification

Le bundle téléchargé n'a pas passé la validation du checksum. Causes fréquentes : incohérence CRC32 vs SHA256 due à un ancien upload CLI, ou clé de chiffrement différente sur d'anciens plugins qui remontent un échec de déchiffrement comme un échec de checksum.

Que faire

Renvoyez le bundle avec un CLI/plugin à jour (SHA256). Si vous utilisez le chiffrement, vérifiez que la clé publique de l'app correspond à la clé d'upload, ou passez au plugin 8.3.0+ pour des keyMismatch erreurs.

Signification

Le bundle téléchargé n'a pas pu être déchiffré.

Que faire

Vérifiez les clés de chiffrement et renvoyez le bundle avec la paire de clés correspondante.

Signification

Le zip contient des chemins de style Windows non valides.

Que faire

Recompilez le bundle avec des chemins Unix ou nettoyez les chemins de l'archive avant l'upload.

Signification

Les chemins de fichiers dans le zip ne sont pas canoniques.

Que faire

Corrigez la génération des chemins de l'archive avant l'upload.

Signification

Le zip contient des chemins de répertoire invalides.

Que faire

Corrigez la structure de l'archive avant l'upload.

Signification

L'appareil n'a pas pu décompresser le bundle téléchargé.

Que faire

Vérifiez l'intégrité de l'archive et la compression prise en charge.

Signification

L'échec du téléchargement est dû à un manque de mémoire sur l'appareil.

Que faire

Réduisez la taille du bundle ou réessayez sur un appareil avec plus de mémoire libre.

Diagnostics de crash, de mémoire et de WebView côté appareil. Inspectez toujours le JSON des métadonnées dans le dashboard.

Signification

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

Signification

L'application est passée au premier plan.

Signification

Crash de la couche JavaScript ou Capacitor. Les métadonnées peuvent inclure le message, la stack, la source et le contexte du bundle actif.

Que faire

Inspectez les métadonnées et les logs natifs. Associez le reporting d'erreurs JS et natif (par exemple Sentry) pour localiser le chemin code défaillant.

Signification

Crash de la plateforme native. Les métadonnées peuvent inclure la plateforme, la raison, la pile et les détails du processus.

Que faire

Utilisez les logs de crash Xcode ou Logcat et croisez-les avec le bundle actif via les métadonnées.

Signification

Événement « Application ne répond pas » sur Android.

Que faire

Inspectez les traces ANR dans Logcat et réduisez le travail bloquant du thread principal après les mises à jour.

Signification

The OS killed the app after memory pressure.

Que faire

Réduire l’usage mémoire après l’activation de la mise à jour et inspecter les métadonnées pour les signaux de mémoire disponible.

Signification

The OS killed the app for excessive resource use.

Que faire

Inspectez les métadonnées selon le type de ressource ou motif de plateforme.

Signification

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

Que faire

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

Signification

Avertissement mémoire iOS.

Que faire

Inspectez le contexte mémoire des métadonnées et réduisez le pic après les mises à jour.

Signification

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

Que faire

Installez le reporting d'erreurs dans les couches JS et natives pour capturer la ligne exacte qui échoue en production.

Signification

Rejet de promesse non géré dans la WebView.

Que faire

Capturez les échecs asynchrones via le reporting d’erreurs JS et natif.

Signification

Un ressource WebView a échoué à charger.

Que faire

Utilisez l’URL de métadonnées et les détails du statut pour corriger les assets cassés ou les règles réseau.

Signification

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

Que faire

Ajustez la CSP à l’aide de la directive metadata et des détails des URI bloqués.

Signification

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

Que faire

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

Signification

Le processus de rendu WebView Android s'est arrêté.

Que faire

Inspectez les signaux de crash du renderer dans les métadonnées et logs.

Signification

Processus de contenu WebView iOS terminé.

Que faire

Inspectez le bundle actif et l'URL de page dans les métadonnées.

Ces événements de timing décrivent le cycle de vie de l’application. Ils ne garantissent pas que toutes les fonctionnalités fonctionnent.

Signification

L’application a démarré une mesure de lancement. C’est un événement normal du cycle de vie.

Signification

L’application a signalé qu’elle était prête. Les métadonnées de timing permettent de comparer le démarrage entre les versions. C’est un événement normal du cycle de vie.

Signification

L’application n’a pas signalé qu’elle était prête dans la fenêtre de mesure du lancement.

Que faire

Inspectez les erreurs de démarrage et la chronologie de l’appareil. Vérifiez que le démarrage atteint l’appel de readiness, puis appelez notifyAppReady() après le bootstrap réussi. Comparez les délais et les échecs avec le bundle précédent avant de modifier les paramètres de timeout.

Signification

Le WebView a signalé que le contenu DOM était chargé. Il s’agit d’un événement de chronométrage normal, pas d’une preuve que toutes les ressources ou fonctionnalités de l’application sont prêtes.

Signification

Le WebView a signalé le chargement d’une page. C’est un événement de chronométrage normal. Comparez les métadonnées de durée entre les versions lors de l’investigation de chargements lents.

Signification

L’app a signalé un événement de navigation. Il s’agit de télémétrie normale. Les métadonnées de route et de durée permettent des comparaisons par écran si l’app les fournit.

Signification

Un bundle a été planifié pour activation au prochain lancement de l’application. La planification est normale et ne signifie pas que le bundle a déjà été activé.

Signification

Le canal sélectionné est en pause. Le serveur n’envoie aucune mise à jour et l’appareil conserve son bundle actuel. Il peut s’agir d’une politique de release volontaire.

Que faire

Vérifiez pourquoi le canal a été mis en pause et s’il est sûr de le reprendre. Ne reprenez pas un déploiement progressif automatiquement pour faire taire cet événement.

Signification

L’appareil n’a pas pu finaliser un bundle téléchargé.

Que faire

Inspectez les métadonnées et les logs natifs pour identifier l’erreur sous-jacente de système de fichiers ou de validation. Vérifiez l’espace de stockage disponible et l’archive envoyée avant de réessayer.

Signification

Le chemin du fichier manifest a échoué à la validation ou n’a pas pu être utilisé lors de la mise à jour.

Que faire

Inspectez le chemin défaillant dans les logs natifs, corrigez la structure des fichiers du bundle et renvoyez-le. Ne contournez pas la validation des chemins.

Signification

L’updater nécessite des métadonnées de checksum manquantes pour ce téléchargement.

Que faire

Renvoyez le bundle avec le CLI actuel et vérifiez que les métadonnées de checksum sont présentes. Ne désactivez pas les vérifications d’intégrité pour contourner l’erreur.

Signification

L’appareil ne dispose pas d’assez d’espace de stockage pour la mise à jour.

Que faire

Libérez de l’espace de stockage sur l’appareil, réduisez la taille du bundle si possible et réessayez sur un appareil de test concerné. Ce problème ne se résout pas en modifiant la politique de version d’un canal.

Signification

L’échec d’une vérification de mise à jour ne permet pas à lui seul de déterminer si la cause est la connectivité, la disponibilité du serveur ou un refus de réponse spécifique.

Que faire

Inspectez les métadonnées de la réponse et les logs natifs environnants. Vérifiez la connectivité et l’URL de mise à jour configurée, puis consultez les erreurs backend spécifiques dans Common Update Problems avant de modifier les paramètres.

Événements de contexte côté appareil pour corréler le comportement des mises à jour avec les changements d’OS, de version native ou de canal.

Signification

Version d’OS de l’appareil changée entre deux vérifications.

Signification

La version de l’app native sur le store a changé, pour distinguer les changements natifs du bundle web.

Signification

L’appareil a interrogé son canal actuel.

Signification

Un canal a été défini avec succès pour l’appareil.

Signification

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

  • SUCCESS: installation du bundle terminée
  • ERROR: échec de l’installation ou du téléchargement
  • PENDING: téléchargement terminé, release en attente
  • DELETED: bundle supprimé, toujours affiché pour les statistiques
  • DOWNLOADING: téléchargement d’un bundle en cours

Il existe une commande de debug pour les utilisateurs cloud de Capgo.

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

Cela vous permettra de vérifier tous les événements de l’app et de trouver une solution si les mises à jour ne se déclenchent pas.

pour trouver vos logs dans Xcode

pour trouver vos logs dans 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 extraire l'app sur votre ordinateur, vous pouvez le faire de cette manière :

Xcode possède une fonctionnalité intégrée pour inspecter le système de fichiers des apps installées par un développeur sur un appareil iOS. Menu Fenêtre de Xcode affichant l'option Appareils et simulateurs

Pour ce faire :

  • Connectez votre appareil à votre Mac et sélectionnez Fenêtre > Appareils dans la barre de menus de Xcode.
  • Sélectionnez votre appareil dans le volet de gauche, sous la section Appareils.
  • Cela affiche la liste des apps installées par un développeur sur cet appareil.
  • Sélectionnez l’application à inspecter, puis cliquez sur l’icône à trois points située en bas de l’écran.
  • Vous pouvez consulter le système de fichiers actuel en téléchargeant un snapshot.

Panneau Devices de Xcode affichant l'option de téléchargement du conteneur de l'app

Sélectionner Download Container… téléchargera et exportera un snapshot du système de fichiers sous forme de fichier .xcappdata que vous pourrez parcourir.

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

Faites un clic droit sur ce fichier et sélectionnez Afficher le contenu du paquet pour ouvrir le dossier.

Ouvrez le dossier App Data, vous devriez maintenant voir quelques dossiers comme Documents, Library, tmp, etc.

Structure du dossier conteneur de l'app iOS montrant les dossiers Documents et Library

Vous trouverez ensuite une version dans 2 dossiers :

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

et documents/versions pour le hot reload

Pour déboguer sur Android, vous devez accéder à l’appareil depuis Android Studio :

  • Cliquez sur View > Tool Windows > Device File Explorer ou sur le bouton Device File Explorer dans la barre des fenêtres d’outils pour ouvrir le panneau Device File Explorer.
  • Sélectionnez un appareil dans la liste déroulante.
  • Ouvrez le chemin data/data/APP_NAME/ où APP_NAME est l’identifiant de votre application.

Device File Explorer d’Android Studio affichant le répertoire de données de l’application

Trouvez ensuite le versions dossier pour voir toutes les versions

Si vous utilisez Débogage pour planifier le travail sur les plugins natifs, connectez-l’à Utiliser @capgo/capacitor-updater pour la capacité native dans « Utiliser @capgo/capacitor-updater », Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Ajout ou mise à jour de plugins, et Alternatives aux plugins Ionic Enterprise pour le workflow produit dans Alternatives aux plugins Ionic Enterprise.