Débogage

Copiez un prompt de configuration incluant les étapes d'installation et le guide markdown complet pour ce plugin.

Comprendre les logs cloud

Si vous recevez un refus cloud code et 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 en snake_case code, puis cliquez sur la cellule de métadonnées pour copier le payload JSON complet. Les métadonnées sont particulièrement utiles pour les crashs et les événements WebView car elles peuvent inclure le message d'erreur, l'URL source, la ligne et la colonne, l'état du processus, la pression mémoire ou une raison spécifique à la plateforme. Les logs plus anciens peuvent encore afficher les anciens alias en camelCase entre parenthèses.

Chaque titre de section correspond à l'action code affichée dans le tableau des logs de la console, vous permettant ainsi d'y accéder directement.

Limites du plan et réponses normales

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

`InvalidIp`

Signification

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

Que faire

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

`provider_infrastructure_request_blocked`

Signification

Votre application est configurée pour bloquer les requêtes provenant des plages d'IP connues des centres de données Google et Apple. Cette protection s'applique aux vérifications de mise à jour, aux stats et aux requêtes channel-self ; les sondes hébergées dans le cloud et les runners de fournisseurs peuvent donc recevoir cette réponse même si la configuration de l'app 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 paramètre désactivé jusqu'à modification.

`needPlanUpgrade`

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

Changez de plan dans le dashboard ou attendez le prochain cycle de facturation.

`noNew`

Signification

L'appareil possède déjà le dernier bundle disponible pour son canal. Il s'agit d'un état normal, pas d'une erreur.

`rateLimited`

Signification

L'appareil a envoyé trop de requêtes de mise à jour ou de canal dans un intervalle court.

Que faire

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

Format de version

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

`semver_error`

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.

Ciblage par plateforme et par build

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

`disablePlatformIos`

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.

`disablePlatformAndroid`

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 s'il s'agit d'une erreur, ou redirigez les builds Android vers un canal dédié si le blocage est intentionnel.

`disablePlatformElectron`

Signification

L'appareil utilise Electron, mais les mises à jour Electron sont désactivées pour ce canal.

Que faire

Activez Electron dans le canal s'il s'agit d'une erreur, ou redirigez les builds Electron vers un canal dédié si le blocage est intentionnel.

`disableDevBuild`

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 de dev dans un canal de test, ou réservez ce canal aux releases et déplacez les appareils de dev ailleurs.

`disableProdBuild`

Signification

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

Que faire

Autorisez les mises à jour de production dans le canal s'il s'agit d'une erreur, ou redirigez les builds de production vers le bon canal.

`disableDevice`

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 s'il s'agit d'une erreur, ou maintenez la restriction et redirigez les appareils réels vers un autre canal.

`disableEmulator`

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é de l'auto-update

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

`disableAutoUpdate`

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 d'auto-update du canal pour permettre votre déploiement.

`disableAutoUpdateUnderNative`

Signification

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

Que faire

Publiez un bundle égal ou supérieur à la version native de base, ou désactivez la protection « under-native » dans le canal.

`disableAutoUpdateMetadata`

Signification

Le canal requiert 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.

`disableAutoUpdateToMajor`

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.

`disableAutoUpdateToMinor`

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

Alignez la stratégie du canal avec votre plan de déploiement progressif, ou autorisez les sauts de version mineure pour ce canal.

`disableAutoUpdateToPatch`

Signification

Le canal bloque les changements de niveau patch tout en conservant le même MAJOR.MINOR.PATCH préfixe ; seuls les changements de suffixe sont autorisés.

Que faire

Alignez la cadence des releases sur la politique du canal, ou autorisez les sauts de patch pour ce track.

Configuration du canal

Refus du backend causés par une configuration de canal manquante ou incompatible.

`cannotUpdateViaPrivateChannel`

Signification

L'appareil a tenté de s'associer à un canal privé qui n'autorise pas l'auto-assignation des appareils (allow_device_self_set est à 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é.

`channelMisconfigured`

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.

`NoChannelOrOverride`

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.

Livraison et chiffrement du bundle

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

`cannotGetBundle`

Signification

Capgo n'a pas pu générer d'URL de téléchargement signée valide et aucun manifest de secours n'était disponible.

Que faire

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

`missingBundle`

Signification

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

Que faire

Recompilez et renvoyez la version, puis confirmez que le bundle contient bien des fichiers.

`keyMismatch`

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.

Configuration de l'app et clients legacy

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

`customIdBlocked`

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 IDs personnalisés, ou activez-les uniquement si votre workflow l'exige.

`blocked_by_server_url`

Signification

server.url est configuré dans 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

Supprimez ou effacez server.url pour les builds de production et garder les payloads de mise à jour en local. Ce code peut apparaître comme un refus du backend ou comme une statistique côté appareil.

`backend_refusal`

Signification

Le plugin updater est en v4, ce que le backend n'accepte plus.

Que faire

Mettez à jour le plugin et CLI en v5+ (v8 recommandé) avec Capacitor v5+, recompilez et republiez les métadonnées du bundle.

Cycle de vie d'une MAJ

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

`ping`

Signification

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

`get`

Signification

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

`set`

Signification

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

`set_fail`

Signification

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

Que faire

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

`reset`

Signification

L'appareil a réinitialisé le bundle intégré.

`delete`

Signification

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

Échecs de téléchargement et d'installation

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

`download_0`

Signification

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

`download_10`

Signification

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

`download_20`

Signification

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

`download_30`

Signification

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

`download_40`

Signification

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

`download_50`

Signification

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

`download_60`

Signification

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

`download_70`

Signification

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

`download_80`

Signification

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

`download_90`

Signification

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

`download_complete`

Signification

Le téléchargement du bundle est terminé.

`download_manifest_start`

Signification

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

`download_manifest_complete`

Signification

L'appareil a fini de télécharger le manifeste de mise à jour.

`download_zip_start`

Signification

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

`download_zip_complete`

Signification

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

`download_manifest_file_fail`

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.

`download_manifest_checksum_fail`

Signification

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

Que faire

Réenvoyez le bundle avec une version CLI actuelle et vérifiez les checksums du manifest.

`download_manifest_brotli_fail`

Signification

La décompression Brotli d'un fichier manifest a échoué.

Que faire

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

`download_fail`

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.

`update_fail`

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.

`checksum_fail`

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

`decrypt_fail`

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.

`windows_path_fail`

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.

`canonical_path_fail`

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.

`directory_path_fail`

Signification

Le zip contient des chemins de répertoire invalides.

Que faire

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

`unzip_fail`

Signification

L'appareil n'a pas réussi à décompresser le bundle téléchargé.

Que faire

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

`low_mem_fail`

Signification

Le téléchargement a échoué car l'appareil est à court de mémoire.

Que faire

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

Santé de l'app et événements WebView

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

`app_moved_to_background`

Signification

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

`app_moved_to_foreground`

Signification

L'application est passée au premier plan.

`app_crash`

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. Couplez le reporting d'erreurs JS et natif (par exemple Sentry) pour localiser le chemin code défaillant.

`app_crash_native`

Signification

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

Que faire

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

`app_anr`

Signification

Événement Android Application Not Responding.

Que faire

Inspectez les traces ANR dans Logcat et réduisez les tâches bloquantes sur le thread principal après les mises à jour.

`app_killed_low_memory`

Signification

L'OS a tué l'application suite à une pression mémoire.

Que faire

Reduce memory use after update activation and inspect metadata for available memory signals.

`app_killed_excessive_resource_usage`

Signification

The OS killed the app for excessive resource use.

Que faire

Inspect metadata for the resource type or platform reason.

`app_initialization_failure`

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.

`app_memory_warning`

Signification

Avertissement mémoire iOS.

Que faire

Inspect memory context in metadata and reduce peak usage after updates.

`webview_javascript_error`

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.

`webview_unhandled_rejection`

Signification

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

Que faire

Capturez les échecs asynchrones avec le reporting d'erreurs JS et natif.

`webview_resource_error`

Signification

Une ressource WebView n'a pas pu être chargée.

Que faire

Use metadata URL and status details to fix broken assets or network rules.

`webview_security_policy_violation`

Signification

Content security policy blocked a resource.

Que faire

Ajustez la CSP via la directive metadata et les détails des URI bloqués.

`webview_unclean_restart`

Signification

La session WebView précédente ne s'est pas fermée correctement, ce qui peut indiquer des crash loops 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.

`webview_render_process_gone`

Signification

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

Que faire

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

`webview_content_process_terminated`

Signification

iOS WebView content process terminated.

Que faire

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

Contexte de l'environnement et du canal

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

`os_version_changed`

Signification

Device OS version changed between checks.

`native_app_version_changed`

Signification

La version native sur le store a changé, permettant de distinguer les changements natifs des changements de bundle web.

`getChannel`

Signification

L'appareil a interrogé son canal actuel.

`setChannel`

Signification

Un canal a été configuré avec succès pour l'appareil.

`uninstall`

Signification

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

Statut du bundle

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 stats
DOWNLOADING: téléchargement d'un bundle en cours

Comprendre les logs de l'appareil

Commande de debug

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

npx @capgo/cli@latest app debug

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

Logs natifs iOS

pour trouver vos logs sur Xcode

Récupérer le log de l'appareil dans Xcode

Logs natifs Android

pour trouver vos logs sur Android Studio

Consulter les logs avec Logcat

Mapping des phrases de logs natifs

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

Trouver le bundle téléchargé sur un appareil

iOS

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 que vous souhaitez inspecter, puis cliquez sur l'icône des trois points en bas de l'écran.
Vous pouvez visualiser le système de fichiers actuel en téléchargeant un snapshot.

Panneau Xcode Devices 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 plusieurs 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

Android

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

Cliquez sur View > Tool Windows > Device File Explorer ou cliquez sur le bouton Device File Explorer dans la barre d'outils pour l'ouvrir.
Sélectionnez un appareil dans la liste déroulante.
Ouvrez le chemin data/data/APP_NAME/ où APP_NAME est l'ID de votre application.

Android Studio Device File Explorer affichant le répertoire des données de l'application

Ensuite, trouvez le versions dossier pour voir toutes les versions

Comprendre les crash logs de production iOS

How to review your app's crash logs

Continuer depuis Débogage

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.