Como adicionar um botão para reportar bugs no seu site

widgetDenis Povarov30 de agosto de 2026

Um botão de relatório de bug no seu site faz uma coisa bem: pega os problemas no momento em que os usuários esbarram neles, na página em que isso acontece, em vez de torcer para que alguém encontre o seu e-mail de suporte depois. Este guia mostra como adicionar um com o BugDump, da configuração de uma linha às opções que importam em produção.

Opção 1: a tag de script (recomendada)

Adicione uma linha ao seu HTML, de preferência perto do fim do head ou do body:

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

Essa é a integração inteira. O atributo data-api-key dispara a inicialização automática: nenhum JavaScript para escrever, nenhuma etapa de build, nenhum adaptador de framework. Um botão de bug flutuante aparece no canto de cada página que tem a tag.

O atributo async importa: ele impede que o SDK bloqueie o parsing da página ou o DOMContentLoaded. O widget inicializa assim que o script chega, mas a sua página nunca espera por ele. O script de entrada tem cerca de 118 KB (uns 28 KB com gzip); as partes mais pesadas, como a biblioteca de captura de tela do DOM e o módulo de replay de sessão, são chunks separados que só carregam quando são usados, então as páginas que nunca precisam deles nunca os baixam.

Como o widget vive num Shadow DOM, o CSS do seu site não consegue quebrá-lo, e os estilos dele não vazam para o seu layout, um problema real com widgets antigos do tipo embed.

Opção 2: npm

Se você prefere o SDK como uma dependência empacotada e versionada:

npm install @bugdump/sdk

import { Bugdump } from '@bugdump/sdk';

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

Você ganha as definições completas de TypeScript, e as opções de configuração aparecem no autocompletar do seu editor. Esse caminho serve para apps em que todo script de terceiros passa pelo bundle e pela revisão de dependências.

Opção 3: inicialização manual com fila de comandos

Para sites que carregam o script de forma assíncrona mas precisam chamar o SDK imediatamente, antes de o download terminar, use o padrão de stub:

<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>

Até o SDK chegar, bugdump(...) enfileira as chamadas; quando ele carrega, a fila é executada na ordem. Sem o stub, uma chamada inline disputaria corrida com o download assíncrono e lançaria um erro. É o mesmo padrão que os snippets de analytics usam, e é a escolha certa quando as opções de inicialização dependem do estado em tempo de execução: o usuário logado, uma feature flag, o tipo de página.

Configurações que valem desde o primeiro dia

Os padrões são sensatos, mas algumas opções merecem uma decisão consciente:

theme — 'light', 'dark' ou 'auto' (segue o sistema operacional). Se o seu app tem a própria alternância de tema, combine com ela.
Identifique seus usuários. Em apps com contas, chame bugdump('identify', { email }) depois do login. Os relatórios chegam com quem reportou anexado, e você não precisa pedir que os usuários digitem o e-mail no widget.
bubbleText — um balão ao lado do botão que o visitante pode fechar («Achou um bug?»). Útil durante um beta, quando você quer relatórios ativamente; o fechamento é lembrado por navegador.
hideButton — esconde o botão flutuante para você abrir o widget pela sua própria interface (um item «Relatar um problema» no menu de ajuda) com bugdump('open'). Assim a página fica limpa e o relatório continua a um clique de distância.
translations — substitui qualquer texto do widget. Se o seu produto não está em inglês, o botão de relatório também não deveria estar.

Filtre o ruído antes que ele custe caro

O widget mantém buffers circulares de entradas do console e de requisições de rede para que cada relatório traga o histórico recente. Em páginas com scripts de terceiros barulhentos (beacons de analytics, polling de feature flags, health checks), esse histórico se enche de ruído, e o ruído empurra o sinal para fora.

Configure consoleFilter e networkFilter para descartar as entradas irrelevantes antes que elas entrem nos buffers. Dois benefícios: as entradas que importam sobrevivem até o relatório ser enviado, e o tráfego de terceiros que você prefere não guardar nunca sai do navegador. Se você ligar captureNetworkBodies, o filtro passa a servir também à privacidade, não só à higiene dos dados: decida explicitamente de quais endpoints os corpos podem entrar num relatório de bug.

Armadilhas a evitar

Não esconda o botão atrás de um formulário. Cada campo obrigatório custa relatórios. A descrição é a única coisa que vale exigir; ambiente, console, rede e replay são coletados automaticamente, e é exatamente essa a ideia.
Atenção à sua Content-Security-Policy. Uma CSP restritiva precisa da origem do SDK em script-src, e o SDK carrega os chunks opcionais da mesma origem, então liberar só o arquivo de entrada não basta.
Se você hospeda o SDK por conta própria ou usa um proxy, copie todos os arquivos dele, não só o de entrada. O arquivo de entrada resolve os chunks de captura de tela e de replay em relação à própria URL; servi-lo sozinho deixa esses recursos quebrados sem nenhum aviso, enquanto o resto do widget parece funcionar.
Não coloque o widget só em produção. Instale-o também em staging, com uma chave de projeto separada. A sua equipe passa a ser a primeira a usar o seu próprio fluxo de relatórios, e os erros de configuração aparecem antes que usuários reais os vejam.

Como verificar se funciona

Depois de instalar, envie um relatório você mesmo: clique no botão, tire uma captura de tela, faça anotações nela e envie. Depois abra o relatório no painel e confira se os logs do console, as requisições de rede e os dados do ambiente chegaram, e se o identify anexou a sua conta, caso você o tenha configurado. A verificação toda leva dois minutos, e é a mesma experiência que os seus usuários vão ter.

A partir daí, os relatórios entram num quadro kanban, são encaminhados para o chat da equipe ou para o seu issue tracker pelas integrações e, se você conectar o servidor MCP, viram algo que o seu assistente de código com IA investiga diretamente.