Troubleshooting

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

🚀 Besoin d’aide d’un expert ?

Bloqué sur un problème complexe ? Notre équipe d’experts est là pour vous aider ! Bénéficiez d’un support personnalisé, de revues de code et de solutions sur mesure adaptées à vos besoins spécifiques.

Obtenir un support professionnel

Échecs d'upload

Si l'upload de votre bundle échoue, vérifiez :

• Votre ID d'application dans capacitor.config.ts correspond à votre application dans le dashboard Capgo
• Vous exécutez la commande d'upload depuis la racine de votre projet Capacitor
• Vos assets web sont compilés et à jour

Options d'upload avancées

Le CLI de Capgo propose des flags supplémentaires pour résoudre les problèmes d'upload courants :

• --tus: Utilise le le protocole d'upload résumable tus pour des uploads plus fiables de gros bundles ou sur des connexions réseau médiocres. Si votre bundle dépasse 10 Mo ou si votre connexion est instable, envisagez d'utiliser --tus:

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

• --package-json et --node-modules: indique à Capgo où trouver votre répertoire racine package.json et node_modules si votre application utilise une structure non standard comme un monorepo ou un workspace npm. Indiquez le chemin vers le répertoire racine package.json et le --node_modules chemin :

  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 bundler correctement les dépendances de votre application.

Vous pouvez combiner ces flags avec d'autres options comme --channel au besoin. Consultez la documentation Capgo CLI pour tous les détails sur les options d'upload disponibles.

Si vous rencontrez toujours des problèmes d'upload, contactez le support Capgo pour plus d'aide.

Déboguer les mises à jour

Si vous rencontrez des problèmes avec les live updates, la commande de debug 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 (ex : rouvrir l'app après l'upload d'un nouveau bundle).

3. Surveillez la sortie de la commande de debug. Elle affichera les logs du processus de mise à jour, notamment :

   • Quand l'app vérifie la présence d'une mise à jour
   • Si une mise à jour est trouvée et quelle est sa version
   • Progression du téléchargement et de l'installation de la mise à jour
   • Toute erreur survenant pendant le processus de mise à jour

4. Utilisez les logs de debug pour identifier l'origine du problème. Par exemple :

   • Si aucune mise à jour n'est trouvée, vérifiez que votre bundle a bien été envoyé et que l'app 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 puis rouverte.
   • Si vous voyez un message d'erreur, recherchez cette erreur spécifique dans la doc Capgo ou contactez le support pour obtenir de l'aide.

La commande debug est particulièrement utile pour identifier les problèmes liés au téléchargement et à l'installation de la mise à jour. Si les logs indiquent que la version attendue a été trouvée mais n'a pas été appliquée, concentrez votre dépannage sur les étapes suivant le téléchargement.

Débogage avec les logs natifs

En plus de la commande debug Capgo, les logs natifs sur Android, iOS et Electron peuvent fournir des informations de dépannage précieuses, surtout pour les problèmes sur la partie native du processus de mise à jour.

Logs Android

Pour accéder aux logs Android :

1. Connectez votre appareil ou lancez votre émulateur
2. Ouvrez Android Studio et sélectionnez « View > Tool Windows > Logcat »
3. Dans la fenêtre Logcat, filtrez les logs pour ne garder 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 logs SDK

Vous pouvez aussi utiliser la adb logcat commande et faire un grep sur Capgo pour filtrer les logs.

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 quelle est sa version
• Quand le téléchargement de la mise à jour démarre et se termine
• Lorsque l'installation de la mise à jour est déclenchée
• Toute erreur survenant lors des étapes de mise à jour native

Les problèmes Android courants que vous pourriez voir dans les logs incluent :

• Problèmes de connectivité réseau empêchant le téléchargement de la mise à jour
• File permissions errors when saving or reading the update bundle
• Espace de stockage insuffisant pour le bundle de mise à jour
• Échec du redémarrage de l'app après l'installation de la mise à jour

Logs iOS

Pour accéder aux logs iOS :

1. Connectez votre appareil ou lancez 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 de la console, recherchez les lignes contenant Capgo pour trouver les logs SDK

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

Comme sur Android, Capgo SDK journalise les événements clés côté iOS :

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

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

• Problèmes de certificat SSL lors du téléchargement de la mise à jour
• ATS bloquant le téléchargement de la mise à jour
• Espace de stockage insuffisant pour le bundle de mise à jour
• Impossible d’extraire ou d’appliquer correctement le bundle de mise à jour

Logs Electron

Pour les applications Electron, vérifiez la sortie du processus principal et du processus renderer :

1. Lancez l’application Electron depuis votre terminal avec votre commande de lancement habituelle (par exemple bun run electron:dev ou bun run electron:serve) and watch the terminal output for startup, update checks, and network errors.
2. Ouvrez DevTools dans la fenêtre du renderer (Affichage → Activer les outils de développement) et inspectez les logs de la console ainsi que les requêtes réseau échouées en reproduisant le flux de mise à jour.
3. For packaged apps, check OS log tools for crashes or startup failures:
   • machine macOS : ouvrir Console.app et filtrez par le nom de votre app
   • Windows : ouvrir Observateur d'événements → Journaux Windows → Application
   • Linux : utilisez votre visionneuse de logs de bureau ou journalctl pour le processus de votre application

Lors du débogage des mises à jour, comparez les messages des logs du main-process et du renderer-process pour distinguer les problèmes de bootstrap Electron des problèmes de cycle de vie des mises à jour Capgo.

Sur toutes les plateformes, les logs natifs offrent une vue de plus bas niveau 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 surviennent en dehors de la couche JavaScript de Capgo.

Lorsque vous dépannez un problème live update complexe, il est conseillé de capturer à la fois les logs de debug Capgo et les logs natifs pour obtenir une vue d'ensemble de la situation. La combinaison de ces deux logs vous donnera les meilleures chances d'identifier et de résoudre le problème.

Mises à jour non appliquées

Si vous avez envoyé un bundle mais que les changements n’apparaissent pas sur votre appareil :

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

Reportez-vous au guide sur le déploiement des live updates pour plus de détails sur le processus de mise à jour. Si vous êtes toujours bloqué, utilisez la npx @capgo/cli@latest app debug commande et les logs natifs pour mieux comprendre ce qui se passe.

Codes d’erreur de mise à jour courants

Si vos logs 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 courants de mise à jour

Il explique ce que signifie chaque code courant, pourquoi cela se produit et comment le corriger.

Installation de SDK

Si vous rencontrez des difficultés pour installer le Capgo SDK, vérifiez que :

• Votre application utilise une version prise en charge de Capacitor (4.0 ou plus récente)
• Vous avez suivi le démarrage rapide étapes 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 uploads Capgo depuis votre pipeline CI/CD :

• Vérifiez que votre token d’authentification Capgo est correctement configuré
• Assurez-vous d’exécuter la commande d’upload après la compilation de vos assets web
• Vérifiez que la commande d’upload utilise le bon nom de canal pour votre environnement cible

Consultez le Intégration CI/CD docs pour plus d’astuces de dépannage. Vous pouvez également utiliser le npx @capgo/cli@latest app debug commande pour vérifier si les mises à jour déclenchées par votre CI/CD sont bien reçues par l’app.

Continuer depuis le dépannage

Si vous utilisez Troubleshooting pour planifier le stockage et la gestion des fichiers, connectez-l’à @capgo/capacitor-data-storage-sqlite pour les détails d'implémentation dans @capgo/capacitor-data-storage-sqlite, Utiliser @capgo/capacitor-data-storage-sqlite pour la capacité native dans Utiliser @capgo/capacitor-data-storage-sqlite @capgo/capacitor-file pour les détails d'implémentation dans @capgo/capacitor-file, Utiliser @capgo/capacitor-file pour la capacité native dans Utiliser @capgo/capacitor-file, et @capgo/capacitor-uploader pour les détails d'implémentation dans @capgo/capacitor-uploader.