Dépannage

Voici quelques problèmes courants que vous pourriez rencontrer en utilisant Capgo et comment les résoudre

Échecs de téléchargement

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

• L’ID de votre application dans capacitor.config.ts correspond à votre application dans le tableau de bord Capgo
• Vous exécutez la commande de téléchargement depuis la racine de votre projet Capacitor
• Vos ressources web sont construites et à jour

Options avancées de téléchargement

La CLI Capgo fournit des options supplémentaires pour aider avec les problèmes courants de téléchargement :

• --tus : Utilise le protocole de téléchargement reprise tus pour des téléchargements plus fiables de gros bundles ou sur des connexions réseau instables. Si votre bundle fait plus de 10 Mo ou si votre connexion est instable, envisagez d’utiliser --tus :

  npx @capgo/cli@latest upload --tus

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

  npx @capgo/cli@latest 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 options avec d’autres comme --channel selon vos besoins. Consultez la documentation CLI Capgo pour tous les détails sur les options de téléchargement disponibles

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

Débogage des mises à jour

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

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

   npx @capgo/cli@latest app debug

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

3. Observez la sortie de la commande debug. Elle enregistrera des informations sur le processus de mise à jour, notamment :

   • Quand l’application vérifie une mise à jour
   • Si une mise à jour est trouvée et quelle version elle est
   • La progression du téléchargement et de l’installation de la mise à jour
   • Toutes les erreurs qui surviennent pendant le processus de mise à jour

4. Utilisez les journaux de débogage pour identifier où se produit le problème. 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 se télécharge 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 le support pour obtenir de l’aide

La commande debug est particulièrement utile pour identifier les problèmes avec le processus de téléchargement et d’installation des mises à jour. Si les journaux montrent que la version de mise à jour attendue a été trouvée mais n’a pas été appliquée, concentrez votre dépannage sur les étapes après le téléchargement

Débogage avec les journaux natifs

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

Journaux Android

Pour accéder aux journaux Android :

1. Connectez votre appareil ou démarrez votre émulateur
2. Ouvrez Android Studio et sélectionnez “View > Tool Windows > Logcat”
3. Dans la fenêtre Logcat, filtrez les journaux pour n’afficher que le processus de votre application en le sélectionnant dans le menu déroulant en haut
4. Recherchez les lignes contenant “Capgo” pour trouver les journaux du SDK

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

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

• Quand une vérification de mise à jour est initiée
• Si une mise à jour est trouvée et quelle version elle est
• Quand le téléchargement de la mise à jour commence et se termine
• Quand l’installation de la mise à jour est déclenchée
• Toutes les erreurs qui surviennent pendant les étapes de mise à jour natives

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 de permissions de fichiers lors de l’enregistrement ou de la lecture du bundle de mise à jour
• Espace de stockage insuffisant pour le bundle de mise à jour
• Échec du redémarrage de l’application après l’installation de la mise à jour

Journaux iOS

Pour accéder aux journaux iOS :

1. Connectez votre appareil ou démarrez votre simulateur
2. Ouvrez Xcode et allez dans “Window > Devices and Simulators”
3. Sélectionnez votre appareil et cliquez sur “Open Console”
4. Dans la sortie console, recherchez les lignes contenant “Capgo” pour trouver les journaux du SDK

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

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

• Initiation et résultat de la vérification de mise à jour
• Début, progression et fin du téléchargement
• Déclenchement et résultat de l’installation
• Toutes les erreurs pendant le processus de mise à jour natif

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

Sur les deux plateformes, les journaux natifs fournissent une vue plus détaillée du 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 JavaScript de Capgo

Lors du dépannage d’un problème complexe de mise à jour en direct, il est recommandé de capturer à la fois les journaux de débogage Capgo et les journaux natifs pour avoir une vision complète de ce qui se passe. Les deux journaux ensemble vous donneront la meilleure chance d’identifier et de résoudre le problème

Mises à jour non appliquées

Si vous avez téléchargé un bundle mais ne voyez pas les changements sur votre appareil :

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

Consultez le 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 avoir plus de visibilité sur ce qui se passe

Installation du SDK

Si vous rencontrez des problèmes lors de l’installation du SDK Capgo, assurez-vous que :

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

Intégration CI/CD

Pour les problèmes de déclenchement des téléchargements Capgo depuis 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 après la construction de vos ressources web
• Vérifiez que la commande de téléchargement utilise le bon nom de canal pour votre environnement cible

Consultez 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 bien reçues par l’application