BugDumpbeta
Volver al blog

Cómo añadir un botón de reporte de bugs a tu web

reportes de bugsDenis Povarov

Un botón de reporte de bugs en tu web hace bien una cosa: atrapa los problemas en el momento en que los usuarios se topan con ellos, en la página donde ocurren, en lugar de esperar a que alguien desentierre más tarde tu email de soporte. Esta guía explica cómo añadir uno con BugDump, desde la instalación de una línea hasta las opciones de configuración que importan en producción.

Opción 1: la etiqueta script (recomendada)

Añade una línea a tu HTML, idealmente cerca del final del head o del body:

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

Esa es toda la integración. El atributo data-api-key activa la inicialización automática: nada de JavaScript que escribir, ni paso de build, ni adaptador para tu framework. En la esquina de cada página que tenga la etiqueta aparece un botón flotante de bugs.

El atributo async importa: evita que el SDK bloquee el parseo de la página o DOMContentLoaded. El widget se inicializa en cuanto llega el script, pero tu página nunca lo espera. El script de entrada pesa unos 118 KB (unos 28 KB con gzip); las piezas más pesadas, como la librería de capturas del DOM y el módulo de repetición de sesión, son chunks aparte que solo se cargan cuando de verdad se usan, así que las páginas que nunca los necesitan nunca los descargan.

Como el widget vive en un Shadow DOM, el CSS de tu web no puede romperlo y sus estilos no se filtran a tu layout, un problema real con los widgets embebidos de estilo antiguo.

Opción 2: npm

Si prefieres tener el SDK como una dependencia empaquetada y con versión:

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

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

Tienes las definiciones completas de TypeScript, así que el editor te muestra todas las opciones de configuración. Esta vía encaja en apps donde cada script de terceros pasa por el bundle y por la revisión de dependencias.

Opción 3: inicialización manual con una cola de comandos

Para webs que cargan el script de forma asíncrona pero necesitan llamar al SDK de inmediato, antes de que termine la descarga, usa el patrón 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>

Hasta que llega el SDK, bugdump(...) encola las llamadas; cuando carga, la cola se reproduce en orden. Sin el stub, una llamada inline competiría con la descarga asíncrona y lanzaría un error. Es el mismo patrón que usan los snippets de analítica, y es la opción correcta cuando las opciones de init dependen del estado en tiempo de ejecución: el usuario con sesión iniciada, un feature flag, el tipo de página.

Configuración que conviene fijar el primer día

Los valores por defecto son sensatos, pero algunas opciones merecen una decisión consciente:

  • theme: 'light', 'dark' o 'auto' (sigue al sistema operativo). Si tu app tiene su propio selector de tema, haz que coincidan.

  • Identifica a tus usuarios. En apps con cuentas, llama a bugdump('identify', { email }) después del inicio de sesión. Los reportes llegan con los datos de quien los envió, y te ahorras pedir a los usuarios que escriban su email en el widget.

  • bubbleText: un pequeño aviso junto al botón que se puede cerrar («¿Encontraste un bug?»). Útil durante una beta, cuando buscas reportes activamente; el cierre se recuerda en cada navegador.

  • hideButton: oculta el botón flotante y abre el widget desde tu propia interfaz (una opción «Reportar un problema» en tu menú de ayuda) con bugdump('open'). Así la página queda limpia y reportar sigue estando a un clic.

  • translations: sobrescribe cualquier texto del widget. Si tu producto no está en inglés, el botón de reporte tampoco debería estarlo.

Filtra el ruido antes de que te cueste caro

El widget guarda buffers circulares de entradas de consola y peticiones de red para que cada reporte lleve el historial reciente. En páginas con scripts de terceros muy ruidosos (beacons de analítica, sondeos de feature flags, health checks), ese historial se llena de ruido, y el ruido desplaza a la señal.

Configura consoleFilter y networkFilter para descartar las entradas irrelevantes antes de que entren en los buffers. Ganas dos cosas: las entradas que te importan sobreviven hasta que se envía el reporte, y el tráfico de terceros que preferirías no guardar nunca sale del navegador. Si activas captureNetworkBodies, el filtrado pasa a ser un control de privacidad además de una cuestión de limpieza: decide de forma explícita qué endpoints merecen que sus cuerpos acaben en un reporte de bug.

Errores que conviene evitar

  • No escondas el botón detrás de un formulario. Cada campo obligatorio cuesta reportes. La descripción es lo único que vale la pena exigir; el entorno, la consola, la red y la repetición de sesión se recogen automáticamente, y de eso se trata.

  • Ojo con tu Content-Security-Policy. Una CSP estricta necesita el origen del SDK en script-src, y ten en cuenta que el SDK carga sus chunks opcionales desde ese mismo origen, así que permitir solo el archivo de entrada no basta.

  • Si alojas el SDK tú mismo o lo sirves a través de un proxy, copia todos sus archivos, no solo el de entrada. El archivo de entrada resuelve sus chunks de capturas y de repetición de sesión con rutas relativas a su propia URL; si lo sirves solo, esas funciones fallan sin avisar mientras el resto del widget parece funcionar.

  • No lo despliegues solo en producción. Pon el widget también en staging, con una clave de proyecto aparte. Tu equipo se convierte en el primer usuario de tu propio flujo de reportes, y los errores de configuración salen a la luz antes de que los vean los usuarios reales.

Comprueba que funciona

Después de instalarlo, envía tú mismo un reporte: haz clic en el botón, haz una captura de pantalla, anótala y envíala. Luego abre el reporte en el panel y comprueba que llegaron los logs de consola, las peticiones de red y los datos del entorno, y que identify adjuntó tu cuenta si lo configuraste. Toda la comprobación lleva dos minutos, y es la misma experiencia que tendrán tus usuarios.

A partir de aquí, los reportes llegan a un tablero kanban, se reenvían al chat de tu equipo o a tu gestor de issues mediante integraciones y, si conectas el servidor MCP, se convierten en algo que tu asistente de IA para programar puede investigar directamente.

Te puede interesar