Troubleshooting

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

🚀 Besoin d'une aide experte ?

Bloqué sur un problème complexe ? Notre équipe d'experts est là pour vous aider ! Bénéficiez d'un support personnalisé, de revues 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 :

• Que votre app ID dans capacitor.config.ts correspond à votre app dans le dashboard Capgo
• Que vous lancez la commande d'upload depuis la racine de votre projet Capacitor
• Que vos assets web sont buildé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 protocole d'upload résumable tus pour des uploads plus fiables de gros bundles ou sur des connexions instables. Si votre bundle dépasse 10 Mo ou si votre connexion est capricieuse, 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. Passez le chemin vers la racine package.json et la --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 selon vos besoins. Consultez la documentation Capgo CLI pour plus de détails sur les options d'upload disponibles.

Si vous rencontrez toujours des problèmes lors de l'upload, contactez Support Capgo pour obtenir de l'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 troubleshooting. 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'application 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 :

   • Lorsque l'application recherche 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 durant 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é uploadé 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 puis rouverte.
   • Si vous voyez un message d'erreur, recherchez cette erreur spécifique dans la documentation de 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 processus de téléchargement et d'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 de debug Capgo, les logs natifs sur Android, iOS et Electron peuvent fournir des informations précieuses pour le dépannage, surtout pour les problèmes liés à 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 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 logs SDK

Vous pouvez aussi utiliser la adb logcat commande puis grep pour Capgo filtrer les logs.

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

• Lorsqu'une vérification de mise à jour est lancée
• Si une mise à jour est trouvée et quelle est sa version
• 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 survenant pendant les étapes de mise à jour native

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

• Problèmes de connectivité réseau empêchant le téléchargement de la mise à jour
• Erreurs de permissions sur les fichiers du bundle de mise à jour
• 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 console, recherchez les lignes contenant Capgo pour trouver les logs SDK

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

Comme sur Android, le Capgo SDK enregistrera les événements iOS clés :

• Update check initiation and result
• Début, progression et fin du téléchargement
• Déclenchement et résultat de l'installation
• Toute erreur durant le processus de mise à jour native

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

• Problèmes de certificat SSL lors du téléchargement de la mise à jour
• App Transport Security bloque 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 du bundle de mise à jour

Logs Electron

Pour les apps Electron, vérifiez les sorties du processus principal et du processus de rendu :

1. Lancez l'app Electron depuis votre terminal avec votre commande habituelle (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 les DevTools dans la fenêtre de rendu (Affichage → Basculer les outils de développement) et inspectez les logs de la console et les requêtes réseau échouées pendant que vous reproduisez le flux de mise à jour.
3. For packaged apps, check OS log tools for crashes or startup failures:
   • macOS: ouvrez Console.app et filtrez par le nom de votre app
   • Windows: ouvrir Visualiseur d'événements → Journaux Windows → Application
   • Linux: utilisez votre visualiseur 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 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 surviennent en dehors de la couche JavaScript de Capgo.

Pour résoudre 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.

Les mises à jour ne s'appliquent pas

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 application code comme indiqué dans le quickstart
• Vérifiez que votre appareil est connecté à Internet et que les logs de debug 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 qu'au lancement
• Recherchez toute erreur dans les logs natifs qui pourrait indiquer un problème lors de l'application de la mise à jour

Consultez 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 qu'il se passe.

Codes d'erreur de mise à jour courants

Si vos logs indiquent 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 courant, pourquoi il survient et comment le corriger.

Installation de SDK

Si vous rencontrez des problèmes lors de l'installation du SDK Capgo, vérifiez que :

• Votre application utilise une version compatible de Capacitor (4.0 ou plus)
• Vous avez suivi le quickstart étapes dans l'ordre, y compris la synchronisation de votre app après l'installation de SDK

Intégration CI/CD

Pour les problèmes de déclenchement d'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 le build 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 de conseils de dépannage. Vous pouvez aussi utiliser la npx @capgo/cli@latest app debug commande pour confirmer si les mises à jour déclenchées par votre CI/CD sont bien reçues par l'app.

Continuer depuis Troubleshooting

Si vous utilisez Troubleshooting pour planifier le stockage et la gestion des fichiers, connectez-l’à @capgo/capacitor-data-storage-sqlite pour le détail d'implémentation dans @capgo/capacitor-data-storage-sqlite, Utilisation de @capgo/capacitor-data-storage-sqlite pour la capacité native, voir 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 les capacités natives dans l'utilisation de @capgo/capacitor-file, et @capgo/capacitor-uploader pour le détail d’implémentation dans @capgo/capacitor-uploader.