BugDumpbeta
Retour au blog

Comment ajouter un bouton de signalement de bug à votre site

widgetDenis Povarov

Un bouton de signalement de bug sur votre site fait bien une chose : il attrape les problèmes au moment où les utilisateurs tombent dessus, sur la page où ça se produit, au lieu d'espérer que quelqu'un retrouve plus tard votre e-mail de support. Voici comment en ajouter un avec BugDump, de l'installation en une ligne aux options de configuration qui comptent en production.

Option 1 : la balise script (recommandée)

Ajoutez une ligne à votre HTML, idéalement vers la fin du head ou du body :

HTML 
<script src="https://bugdump.com/sdk/latest.js" async data-api-key="your-api-key"></script>

C'est toute l'intégration. L'attribut data-api-key déclenche l'initialisation automatique : pas de JavaScript à écrire, pas d'étape de build, pas d'adaptateur de framework. Un bouton de bug flottant apparaît dans le coin de chaque page qui contient la balise.

L'attribut async compte : il empêche le SDK de bloquer l'analyse de la page ou DOMContentLoaded. Le widget s'initialise dès que le script arrive, mais votre page ne l'attend jamais. Le script d'entrée pèse environ 118 Ko (environ 28 Ko compressé en gzip) ; les parties plus lourdes, comme la bibliothèque de capture du DOM et le module de relecture de session, sont des chunks séparés qui ne se chargent que lorsqu'ils servent vraiment. Les pages qui n'en ont jamais besoin ne les téléchargent jamais.

Comme le widget vit dans un Shadow DOM, le CSS de votre site ne peut pas le casser et ses styles ne peuvent pas déborder sur votre mise en page, un vrai problème avec les anciens widgets intégrés.

Option 2 : npm

Si vous préférez avoir le SDK comme dépendance versionnée, intégrée à votre bundle :

Bash 
npm install @bugdump/sdk
TypeScript 
import { Bugdump } from '@bugdump/sdk';

const bugdump = Bugdump.init({ apiKey: 'your-api-key' });

Vous obtenez des définitions TypeScript complètes, et toutes les options de configuration apparaissent dans votre éditeur. Cette voie convient aux applications où chaque script tiers passe par le bundle et la revue des dépendances.

Option 3 : initialisation manuelle avec une file de commandes

Pour les sites qui chargent le script en asynchrone mais doivent appeler le SDK tout de suite, avant la fin du téléchargement, utilisez le pattern du stub :

HTML 
<script>
  window.bugdump = window.bugdump || function () {
    (window.bugdump.q = window.bugdump.q || []).push(arguments);
  };
</script>
<script src="https://bugdump.com/sdk/latest.js" async></script>
<script>
  bugdump('init', { apiKey: 'your-api-key' });
  bugdump('identify', { email: 'user@example.com' });
</script>

Tant que le SDK n'est pas arrivé, bugdump(...) met les appels en file d'attente ; une fois chargé, il les rejoue dans l'ordre. Sans le stub, un appel inline entrerait en concurrence avec le téléchargement asynchrone et lèverait une erreur. C'est le même pattern que celui des snippets d'analytics, et c'est le bon choix quand les options d'initialisation dépendent de l'état à l'exécution : l'utilisateur connecté, un feature flag, le type de page.

La configuration à régler dès le premier jour

Les valeurs par défaut sont raisonnables, mais quelques options méritent une décision réfléchie :

  • theme : 'light', 'dark' ou 'auto' (suit l'OS). Si votre application a son propre sélecteur de thème, alignez-vous dessus.

  • Identifiez vos utilisateurs. Pour les applications avec des comptes, appelez bugdump('identify', { email }) après la connexion. Les rapports arrivent avec leur auteur, et vous n'avez plus à demander aux utilisateurs de taper leur e-mail dans le widget.

  • bubbleText : une bulle d'accroche, que l'on peut fermer, à côté du bouton (« Vous avez trouvé un bug ? »). Utile pendant une bêta, quand vous cherchez activement des rapports ; la fermeture est mémorisée par navigateur.

  • hideButton : masque le bouton flottant pour ouvrir le widget depuis votre propre interface (une entrée « Signaler un problème » dans votre menu d'aide) via bugdump('open'). La page reste épurée, et le signalement reste à un clic.

  • translations : remplace n'importe quel texte du widget. Si votre produit n'est pas en anglais, le bouton de signalement ne devrait pas l'être non plus.

Filtrer le bruit avant qu'il vous coûte

Le widget garde des buffers glissants des entrées de console et des requêtes réseau, pour que chaque rapport contienne l'historique récent. Sur les pages qui exécutent des scripts tiers bavards (balises d'analytics, interrogations de feature flags, health checks), cet historique se remplit de bruit, et le bruit chasse le signal.

Configurez consoleFilter et networkFilter pour écarter les entrées inutiles avant qu'elles n'entrent dans les buffers. Double avantage : les entrées qui vous intéressent survivent jusqu'à l'envoi du rapport, et le trafic tiers que vous préférez ne pas stocker ne quitte jamais le navigateur. Si vous activez captureNetworkBodies, le filtrage protège aussi la vie privée, en plus de faire le ménage : décidez explicitement pour quels endpoints les corps ont leur place dans un rapport de bug.

Les pièges à éviter

  • Ne cachez pas le bouton derrière un formulaire. Chaque champ obligatoire coûte des rapports. La description est la seule chose à exiger ; l'environnement, la console, le réseau et la relecture sont collectés automatiquement, et c'est tout l'intérêt.

  • Pensez à votre Content-Security-Policy. Une CSP stricte doit inclure l'origine du SDK dans script-src. Notez que le SDK charge ses chunks optionnels depuis la même origine : autoriser seulement le fichier d'entrée ne suffit pas.

  • Si vous hébergez le SDK vous-même ou passez par un proxy, copiez tous ses fichiers, pas seulement le point d'entrée. Celui-ci résout ses chunks de capture d'écran et de relecture par rapport à sa propre URL ; servi seul, il laisse ces fonctions cassées sans bruit pendant que le reste du widget semble fonctionner.

  • Ne le déployez pas qu'en production. Mettez aussi le widget en staging, avec une clé de projet séparée. Votre équipe devient la première utilisatrice de votre propre circuit de signalement, et les erreurs de configuration apparaissent avant que de vrais utilisateurs ne les voient.

Vérifier que ça marche

Après l'installation, envoyez vous-même un rapport : cliquez sur le bouton, prenez une capture d'écran, annotez-la et envoyez. Ouvrez ensuite le rapport dans BugDump et vérifiez que les logs de la console, les requêtes réseau et les données d'environnement sont bien arrivés, et que identify a rattaché votre compte si vous l'avez configuré. La vérification prend deux minutes, et c'est exactement ce que vivront vos utilisateurs.

À partir de là, les rapports arrivent sur un tableau kanban et partent vers la messagerie de votre équipe ou votre outil de suivi via les intégrations. Si vous connectez le serveur MCP, votre assistant de code IA peut les analyser directement.

Pour aller plus loin