Troubleshooting

Voici quelques problèmes courants que vous pourriez rencontrer lors de l’utilisation de Capgo et comment les résoudre.

🚀 Besoin de l'aide d'un expert ?

Vous êtes confronté à un problème complexe ? Notre équipe d’experts est là pour vous aider ! Bénéficiez d’une assistance personnalisée, de révisions de code et de solutions personnalisées adaptées à vos besoins spécifiques.

Obtenez une assistance professionnelle

Échecs du téléchargement

Si le téléchargement de votre bundle échoue, vérifiez :

• Votre identifiant d’application dans capacitor.config.ts correspond à votre application dans le tableau de bord Capgo
• Vous exécutez la commande upload depuis la racine de votre projet Capacitor
• Vos actifs Web sont construits et à jour

Options de téléchargement avancées

Le Capgo CLI fournit des indicateurs supplémentaires pour vous aider à résoudre les problèmes de téléchargement courants :

• --tus : utilise le protocole de téléchargement avec reprise pour des téléchargements plus fiables de lots volumineux ou sur des connexions réseau médiocres. Si votre forfait dépasse 10 Mo ou si votre connexion est inégale, pensez à utiliser --tus :

  npx @capgo/cli@latest bundle upload --tus

• --package-json et --node-modules : indique à Capgo où trouver votre racine package.json et node_modules si votre application utilise une structure non standard comme un monorepo ou un espace de travail npm. Transmettez le chemin à la racine package.json et le chemin --node_modules :

  npx @capgo/cli@latest bundle upload --package-json=path/to/package.json --node_modules=path/to/node_modules

  Capgo a besoin de ces informations pour regrouper correctement les dépendances de votre application.

Vous pouvez combiner ces indicateurs avec d’autres options telles que --channel selon vos besoins. Consultez les docs Capgo CLI pour plus de détails sur les options de téléchargement disponibles.

Si vous rencontrez toujours des problèmes avec les téléchargements, contactez l’assistance Capgo pour obtenir de l’aide.

Mises à jour de débogage

Si vous rencontrez des problèmes avec les mises à jour en direct, la commande de débogage Capgo est un outil utile pour le dépannage. Pour l’utiliser :

1. Exécutez la commande suivante dans le répertoire de votre projet :

   npx @capgo/cli@latest app debug

2. Lancez votre application sur un appareil ou un émulateur et effectuez l’action qui doit déclencher une mise à jour (par exemple, rouvrir l’application après le téléchargement d’un nouveau bundle).

3. Regardez le résultat de la commande debug. Il enregistrera des informations sur le processus de mise à jour, notamment :

   • Lorsque l’application recherche une mise à jour
   • Si une mise à jour est trouvée et de quelle version il s’agit
   • Progression du téléchargement et de l’installation de la mise à jour
   • Toutes les erreurs survenues pendant le processus de mise à jour

4. Utilisez les journaux de débogage pour identifier où le problème se produit. Par exemple :

   • Si aucune mise à jour n’est trouvée, vérifiez que votre bundle a été téléchargé avec succès et que l’application est configurée pour utiliser le bon canal.
   • Si la mise à jour est téléchargée mais ne s’installe pas, assurez-vous d’avoir appelé CapacitorUpdater.notifyAppReady() et que l’application a été complètement fermée et rouverte.
   • Si vous voyez un message d’erreur, recherchez cette erreur spécifique dans la documentation Capgo ou contactez l’assistance pour obtenir de l’aide.La commande debug est particulièrement utile pour identifier les problèmes liés au processus de téléchargement et d’installation des mises à jour. Si les journaux indiquent que la version de mise à jour attendue a été trouvée mais n’a finalement pas été appliquée, concentrez votre dépannage sur les étapes suivant le téléchargement.

Débogage avec les journaux natifs

En plus de la commande de débogage Capgo, les journaux natifs sur Android, iOS et Electron peuvent fournir des informations de dépannage précieuses, en particulier pour les problèmes du côté natif du processus de mise à jour.

Android Journaux

Pour accéder aux journaux Android :

1. Connectez votre appareil ou démarrez votre émulateur
2. Ouvrez Android Studio et sélectionnez « Affichage > Fenêtres d’outils > Logcat ».
3. Dans la fenêtre Logcat, filtrez les journaux uniquement sur le processus de votre application en le sélectionnant dans la liste déroulante en haut.
4. Recherchez toutes les lignes incluant Capgo pour trouver les journaux SDK.

Alternativement, vous pouvez utiliser la commande adb logcat et grep pour Capgo pour filtrer les journaux.

Le Capgo SDK enregistrera les événements clés pendant le processus de mise à jour, tels que :

• Lorsqu’une vérification de mise à jour est lancée
• Si une mise à jour est trouvée et de quelle version il s’agit
• Lorsque le téléchargement de la mise à jour démarre et se termine
• Lorsque l’installation de la mise à jour est déclenchée
• Toutes les erreurs survenues lors des étapes de mise à jour native

Les problèmes courants spécifiques à Android que vous pourriez voir dans les journaux incluent :

• Problèmes de connectivité réseau empêchant le téléchargement de la mise à jour
• Erreurs d’autorisations de fichiers lors de l’enregistrement ou de la lecture du bundle de mise à jour
• Manque d’espace de stockage pour le bundle de mise à jour
• Impossible de redémarrer l’application après l’installation de la mise à jour

iOS Journaux

Pour accéder aux journaux iOS :

1. Connectez votre appareil ou démarrez votre simulateur
2. Ouvrez Xcode et allez dans « Fenêtre > Appareils et simulateurs »
3. Sélectionnez votre appareil et cliquez sur “Ouvrir la console”
4. Dans la sortie de la console, recherchez toutes les lignes incluant Capgo pour trouver les journaux SDK.

Vous pouvez également utiliser la commande log stream dans le terminal et grep pour Capgo pour filtrer les journaux.

Semblable à Android, le Capgo SDK enregistrera les événements clés côté iOS :

• Mise à jour du lancement et du résultat du contrôle
• Début, progression et fin du téléchargement
• Déclencheur et résultat de l’installation
• Toute erreur lors du processus de mise à jour native

Les problèmes spécifiques à iOS que vous pourriez identifier dans les journaux incluent :

• Problèmes de certificat SSL lors du téléchargement de la mise à jour
• Sécurité du transport de l’application bloquant le téléchargement de la mise à jour
• Espace de stockage insuffisant pour le bundle de mise à jour
• Échec de l’extraction ou de l’application correcte du bundle de mise à jour

Journaux d’électrons

Pour les applications Electron, vérifiez à la fois la sortie du processus principal et celle du processus de rendu :1. Exécutez l’application Electron depuis votre terminal à l’aide de votre commande de lancement normale (par exemple bun run electron:dev ou bun run electron:serve) et surveillez la sortie du terminal pour le démarrage, les vérifications de mise à jour et les erreurs réseau. 2. Ouvrez DevTools dans la fenêtre du moteur de rendu (Affichage → Basculer les outils de développement) et inspectez les journaux de la console et les requêtes réseau ayant échoué tout en reproduisant le flux de mise à jour. 3. Pour les applications packagées, vérifiez les outils de journalisation du système d’exploitation pour détecter les plantages ou les échecs de démarrage :

• macOS : ouvrez Console.app et filtrez sur le nom de votre application
• Windows : ouvrez Observateur d’événements → Journaux Windows → Application
• Linux : utilisez la visionneuse de journaux de votre bureau ou journalctl pour le processus de votre application

Lors du débogage des mises à jour, comparez les messages des journaux du processus principal et du processus de rendu pour séparer les problèmes d’amorçage d’Electron des problèmes de cycle de vie de mise à jour Capgo.

Sur toutes les plateformes, les journaux natifs fournissent une vue de niveau inférieur sur le processus de mise à jour, avec plus de détails sur l’implémentation native. Ils sont particulièrement utiles pour identifier les problèmes qui se produisent en dehors de la couche Capgo JavaScript.

Lors du dépannage d’un problème délicat de mise à jour en direct, c’est une bonne idée de capturer à la fois les journaux de débogage Capgo et les journaux natifs pour une image complète de ce qui se passe. Les deux journaux réunis vous donneront les meilleures chances d’identifier et de résoudre le problème.

Les mises à jour ne s’appliquent pas

Si vous avez téléchargé un lot mais que vous ne voyez pas les modifications sur votre appareil :

• Assurez-vous d’avoir appelé CapacitorUpdater.notifyAppReady() dans le code de votre application, comme indiqué dans le démarrage rapide.
• Vérifiez que votre appareil est connecté à Internet et que les journaux de débogage Capgo indiquent que la mise à jour a été téléchargée.
• Essayez de fermer et de rouvrir complètement l’application, car les mises à jour ne sont appliquées que lors d’un nouveau lancement.
• Recherchez les erreurs dans les journaux natifs qui pourraient indiquer un problème lors de l’application de la mise à jour.

Reportez-vous au guide Déploiement des mises à jour en direct pour plus de détails sur le processus de mise à jour. Si vous êtes toujours bloqué, utilisez la commande npx @capgo/cli@latest app debug et les journaux natifs pour obtenir plus de visibilité sur ce qui se passe.

Codes d’échec de mise à jour courants

Si vos journaux affichent des erreurs backend telles que disable_auto_update_to_major, semver_error ou cannot_update_via_private_channel, utilisez le guide dédié :

• Problèmes de mise à jour courants

Il explique la signification de chaque code commun, pourquoi il se produit et comment le corriger.

SDK Installation

Si vous rencontrez des difficultés pour installer Capgo SDK, assurez-vous :

• Votre application utilise une version prise en charge de Capacitor (4.0 ou plus récente)
• Vous avez suivi les étapes de démarrage rapide dans l’ordre, y compris la synchronisation de votre application après l’installation de SDK.

Intégration CI/CD

Pour les problèmes liés au déclenchement des importations Capgo à partir de votre pipeline CI/CD :

• Vérifiez que votre jeton d’authentification Capgo est correctement configuré
• Assurez-vous d’exécuter la commande de téléchargement une fois vos ressources Web créées.
• Vérifiez que la commande de téléchargement utilise le nom de canal correct pour votre environnement cibleConsultez la documentation Intégration CI/CD pour plus de conseils de dépannage. Vous pouvez également utiliser la commande npx @capgo/cli@latest app debug pour confirmer si vos mises à jour déclenchées par CI/CD sont reçues par l’application.