Dépannage

Vous rencontrez des problèmes ? Vous êtes au bon endroit. Ce guide couvre les problèmes les plus courants rencontrés par les développeurs lors de l'intégration du widget, ainsi que des solutions étape par étape. La plupart des problèmes peuvent être résolus en quelques minutes.

Widget ne se charge pas

Si le widget n'apparaît pas du tout sur votre page, suivez ces étapes de dépannage dans l'ordre :

❌ Problème : Le script du widget ne parvient pas à se charger

✅ Solution : Vérifiez les attributs requis

Assurez-vous que tous les attributs de données requis sont présents sur la balise script :

<script src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-locale="en"></script>

❌ Problème : Échec de l'authentification

✅ Solution : Vérifiez la configuration OAuth

Les problèmes d'authentification sont généralement simples à résoudre. Passez en revue ces vérifications :

• Vérifiez que client_id est correct dans votre application OAuth - Copiez-le directement depuis votre tableau de bord pour éviter les fautes de frappe
• Assurez-vous que l'application OAuth est active et non désactivée dans votre tableau de bord
• Vérifiez que l'application OAuth a des URI de redirection appropriées configurées - Le domaine du widget doit être autorisé
• Vérifiez que le domaine du widget est autorisé dans les paramètres CORS de votre backend
• Si vous avez récemment régénéré des identifiants, assurez-vous d'utiliser les nouvelles valeurs

Toujours bloqué ? Essayez de créer une nouvelle application OAuth dans votre tableau de bord. Parfois, repartir de zéro résout des problèmes de configuration obscurs.

❌ Problème : /api/v1/auth/widget-token retourne 400 (Origine non autorisée)

✅ Solution : Aligner l'origine hôte et la liste blanche OAuth

• Ajoutez l'origine de votre page d'intégration (par exemple http://localhost:3000) aux allowed_origins OAuth.
• Utilisez le format complet du schéma + hôte (+ port), sans chemin de fin.
• Lors de l'intégration dans un iframe, assurez-vous que les appels de jeton portent l'origine de la page hôte dans X-Embed-Origin.
• Vérifiez que l'URL de demande est /api/v1/auth/widget-token (pas de chemins hérités).

Astuce de validation : Vérifiez l'onglet réseau du navigateur pour les en-têtes de demande de jeton et comparez X-Embed-Origin avec votre entrée allowed_origins OAuth.

Widget non visible

❌ Problème : Le widget apparaît réduit mais le bouton est invisible

✅ Solution : Vérifiez le positionnement de la configuration

• Vérifiez le paramètre de position de configuration du widget
• Vérifiez les conflits CSS avec position: fixed
• Assurez-vous que les conteneurs parents n'ont pas overflow: hidden

❌ Problème : Widget caché sur mobile

✅ Solution : Ajustez les paramètres mobiles

Si hide_on_mobile est activé dans la configuration, le widget sera caché sur les appareils mobiles. Désactivez ce paramètre ou ajustez le point de rupture mobile.

Problèmes de style

Les problèmes visuels sont courants et généralement faciles à résoudre. Le widget est conçu pour être visuellement isolé de votre page, mais des conflits peuvent parfois se produire.

❌ Problème : Les couleurs ne s'appliquent pas

✅ Solution : Effacer le cache et vérifier la configuration

Suivez ces étapes pour diagnostiquer les problèmes de couleur :

• Effacez le cache du navigateur et rechargez la page (Ctrl+Shift+R ou Cmd+Shift+R pour un rechargement complet)
• Vérifiez que les valeurs de couleur sont des codes hexadécimaux valides (doivent commencer par # et avoir 6 caractères, par exemple, #FF5733)
• Vérifiez que la configuration a été enregistrée dans le tableau de bord - Recherchez une confirmation "enregistrée"
• Assurez-vous que vous modifiez la bonne configuration - Vérifiez que l'ID de configuration correspond à votre balise script
• Attendez quelques secondes après l'enregistrement - Les modifications de configuration peuvent prendre 5 à 10 secondes pour se propager

Conseil de débogage : Ouvrez le widget dans votre navigateur et utilisez l'outil d'inspection des éléments pour vérifier quelles valeurs CSS sont réellement appliquées. Cela vous montrera si vos couleurs se chargent ou sont remplacées.

❌ Problème : Les polices ne se chargent pas

✅ Solution : Configuration de la police

• Assurez-vous que la famille de polices est définie sur "system-ui" ou une police web-safe
• Les polices personnalisées peuvent ne pas se charger en raison de restrictions CORS
• Vérifiez que les valeurs de poids de police sont prises en charge

Problèmes de fonctionnalité

Lorsque le widget se charge correctement mais que les fonctionnalités ne fonctionnent pas comme prévu, ces solutions vous aideront.

❌ Problème : Les messages ne s'envoient pas

✅ Solution : Vérifiez la session et le réseau

Les problèmes d'envoi de messages sont généralement liés à la connectivité réseau ou aux sessions expirées. Diagnostiquez systématiquement :

• Vérifiez que les points de terminaison API sont accessibles - Essayez d'accéder directement à l'URL de l'API dans votre navigateur
• Vérifiez que le jeton d'authentification est valide - Recherchez des erreurs 401/403 dans l'onglet réseau
• Assurez-vous que la session n'a pas expiré - Les sessions durent généralement 30 minutes d'inactivité
• Vérifiez les problèmes de connectivité réseau - Votre connexion Internet est-elle stable ?
• Recherchez des erreurs CORS dans la console - Cela indique que votre domaine peut ne pas être sur liste blanche
• Vérifiez que le logiciel de pare-feu/de sécurité ne bloque pas l'API - Les réseaux d'entreprise bloquent parfois les API externes

Test rapide : Si les messages fonctionnent dans une fenêtre incognito mais pas dans votre navigateur normal, le problème est probablement lié aux extensions du navigateur ou aux données d'authentification mises en cache.

❌ Problème : Les flux de conversation ne fonctionnent pas

✅ Solution : Validez la configuration du flux

• Vérifiez que les mots-clés de déclenchement correspondent exactement
• Vérifiez que les réponses de flux sont correctement configurées
• Assurez-vous que les actions des boutons sont valides

Problèmes de performance

❌ Problème : Le widget se charge lentement

✅ Solution : Optimisez le chargement

• Utilisez la version de production au lieu du développement
• Activez la mise en cache du navigateur pour les actifs statiques
• Minimisez le CSS et les images personnalisés
• Envisagez le chargement paresseux si ce n'est pas critique

❌ Problème : Utilisation élevée de la mémoire

✅ Solution : Réduisez l'utilisation des ressources

• Limitez la longueur de l'historique des messages
• Optimisez les images et les médias
• Désactivez les fonctionnalités inutilisées

Compatibilité du navigateur

❌ Problème : Widget ne fonctionnant pas dans les anciens navigateurs

✅ Solution : Vérifiez la prise en charge du navigateur

Le widget nécessite des fonctionnalités modernes du navigateur :

• Prise en charge de JavaScript ES6+
• API PostMessage
• CSS Grid et Flexbox
• Capacités modernes des iframes

Navigateurs minimum pris en charge : Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

Obtenir de l'aide

Lorsque vous avez besoin d'une assistance supplémentaire au-delà de ce guide, ces outils et ressources vous aideront à diagnostiquer des problèmes ou à obtenir de l'aide.

Mode débogage

Activez le mode débogage pour voir des journaux détaillés dans la console de votre navigateur. Cela fournit des informations sur ce que fait le widget à chaque étape :

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-dev="true"></script>

Outils de développement du navigateur

• Vérifiez l'onglet Console pour les erreurs JavaScript
• Vérifiez l'onglet Réseau pour les requêtes échouées
• Vérifiez l'onglet Application pour les problèmes de stockage local
• Utilisez l'onglet Éléments pour inspecter le DOM du widget

Étapes de débogage courantes

1. Effacez le cache et les cookies du navigateur
2. Essayez en mode incognito/navigation privée
3. Testez avec différents navigateurs
4. Vérifiez la connectivité réseau
5. Vérifiez toutes les valeurs de configuration