Как добавить на сайт кнопку для баг-репортов

виджетDenis Povarov30 августа 2026 г.

Кнопка для баг-репортов на сайте хорошо делает одно: ловит проблемы в тот момент, когда пользователи на них натыкаются, и на той странице, где это случилось, — и не нужно надеяться, что кто-нибудь потом откопает адрес вашей поддержки. Ниже — как добавить её с BugDump: от установки в одну строку до настроек, которые важны в продакшене.

Способ 1: тег script (рекомендуется)

Добавьте в HTML одну строку, лучше ближе к концу head или body:

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

Вот и вся интеграция. Атрибут data-api-key запускает автоматическую инициализацию — не нужно писать JavaScript, не нужна сборка, не нужен адаптер под фреймворк. На каждой странице с этим тегом в углу появляется плавающая кнопка бага.

Атрибут async важен: с ним SDK не блокирует парсинг страницы и DOMContentLoaded. Виджет инициализируется, как только скрипт загрузится, но страница его никогда не ждёт. Основной скрипт весит около 118 КБ (примерно 28 КБ в gzip); тяжёлые части вроде библиотеки для скриншотов DOM и модуля воспроизведения сессии вынесены в отдельные чанки, которые загружаются, только когда до них доходит дело, так что страницы, где они не используются, их и не скачивают.

Виджет живёт в Shadow DOM, поэтому CSS вашего сайта не может его сломать, а его стили не протекают в вашу вёрстку. Со старыми встраиваемыми виджетами это была реальная проблема.

Способ 2: npm

Если вам удобнее подключить SDK как зависимость с фиксированной версией, которая попадает в бандл:

npm install @bugdump/sdk

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

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

Вы получаете полные определения TypeScript, так что все настройки видны прямо в редакторе. Этот путь подходит приложениям, где каждый сторонний скрипт проходит через бандл и проверку зависимостей.

Способ 3: ручная инициализация с очередью команд

Если сайт загружает скрипт асинхронно, но вызывать SDK нужно сразу — до окончания загрузки, — используйте заглушку:

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

Пока SDK не загрузился, bugdump(...) складывает вызовы в очередь; после загрузки очередь выполняется по порядку. Без заглушки вызов из инлайн-скрипта может выполниться раньше, чем загрузится SDK, и упасть с ошибкой. Такой же приём используют сниппеты аналитики, и он подходит, когда параметры инициализации зависят от состояния во время выполнения — вошедшего пользователя, фича-флага, типа страницы.

Что настроить в первый же день

Значения по умолчанию разумные, но несколько параметров стоит выбрать осознанно:

theme — 'light', 'dark' или 'auto' (следует за ОС). Если у вашего приложения свой переключатель темы, подстройтесь под него.
Идентифицируйте пользователей. В приложениях с аккаунтами вызывайте bugdump('identify', { email }) после входа. Отчёты приходят с указанием автора, и пользователям не нужно вводить почту в виджете.
bubbleText — подсказка рядом с кнопкой («Нашли баг?»), которую посетитель может закрыть. Полезна на бете, когда вы ждёте отчётов; браузер запоминает, что подсказку закрыли.
hideButton — скрывает плавающую кнопку, а виджет открывается из вашего интерфейса (например, пунктом «Сообщить о проблеме» в меню помощи) через bugdump('open'). Страница остаётся чистой, а до отчёта по-прежнему один клик.
translations — переопределяет любую строку виджета. Если ваш продукт не на английском, кнопка отчёта тоже не должна быть на английском.

Отфильтруйте шум, пока он не обошёлся дорого

Виджет держит кольцевые буферы записей консоли и сетевых запросов, чтобы к каждому отчёту прилагалась недавняя история. На страницах с болтливыми сторонними скриптами — маячками аналитики, опросом фича-флагов, проверками доступности — эта история заполняется шумом, а шум вытесняет полезный сигнал.

Настройте consoleFilter и networkFilter, чтобы отбрасывать лишние записи до того, как они попадут в буферы. Пользы две: нужные записи доживают до отправки отчёта, а сторонний трафик, который вы не хотите хранить, вообще не покидает браузер. Если вы включили captureNetworkBodies, фильтры не только наводят порядок, но и защищают приватность, — решите явно, тела каких эндпоинтов должны попадать в баг-репорт.

Чего избегать

Не прячьте кнопку за формой. Каждое обязательное поле стоит вам отчётов. Требовать стоит только описание: окружение, консоль, сеть и воспроизведение сессии собираются автоматически, в этом весь смысл.
Помните про Content-Security-Policy. При строгом CSP источник SDK нужно добавить в script-src — и учтите, что необязательные чанки SDK загружает с того же источника, поэтому разрешить только основной файл недостаточно.
Если вы раздаёте SDK со своего сервера или через прокси, копируйте все его файлы, а не только основной. Основной файл ищет чанки скриншотов и воспроизведения относительно своего URL; если отдавать его одного, эти функции тихо сломаются, а остальной виджет будет выглядеть рабочим.
Не ставьте его только в продакшен. Поставьте виджет и на стейджинг, с отдельным ключом проекта. Ваша команда станет первым пользователем собственного процесса отчётов, и ошибки настройки всплывут раньше, чем их увидят настоящие пользователи.

Проверьте, что всё работает

После установки отправьте отчёт сами: нажмите кнопку, сделайте скриншот, добавьте пометки и отправьте. Потом откройте отчёт в BugDump и проверьте, что логи консоли, сетевые запросы и данные об окружении дошли — и что identify привязал ваш аккаунт, если вы его настроили. Вся проверка занимает две минуты, и это ровно тот путь, который пройдут ваши пользователи.

Дальше отчёты попадают на канбан-доску, через интеграции уходят в чат команды или трекер задач, а если подключить MCP-сервер, их сможет разбирать напрямую ваш ИИ-ассистент для программирования.