Widget configuration reference

Every option accepted by Bugdump.init().

const bugdump = Bugdump.init({
  apiKey: 'your-api-key',
  endpoint: 'https://api.bugdump.com',
  theme: 'auto',
  hideButton: false,
  showReportLink: false,
  captureNetworkBodies: false,
});

Core options

Trailing slashes on endpoint are stripped automatically, so https://api.bugdump.com/ and https://api.bugdump.com behave identically.

Configuration applies once

init() creates a single instance. If one already exists, a second init() returns it and silently ignores the configuration you passed — there is no merge and no warning.

The usual way to hit this is a script tag carrying data-api-key: auto-init has already created the instance before your own code runs, so a later init() with new options changes nothing. Either put the option on the script tag as a data-* attribute, or omit data-api-key so that your init() is the first one.

To genuinely change configuration afterwards, destroy the instance first:

Bugdump.getInstance()?.destroy();
const bugdump = Bugdump.init({ apiKey: 'your-api-key', hideButton: true });

This discards telemetry collected up to that point, so prefer configuring correctly at init. With @bugdump/react, the provider does this for you when its apiKey, endpoint or locale changes; it reads the other options once. The theme is the one option you can change in place, with setTheme() — see Theme below.

See Choosing an installation method.

Theme

theme sets the theme the widget starts with:

• auto (the default) follows the user's OS preference, and keeps following it if they switch while the page is open.

• light and dark force one or the other.

From a script tag, use data-theme="light", "dark" or "auto".

If your app has its own light/dark toggle, pass the app's current theme at init, then call setTheme() whenever the user changes it. The widget switches immediately, including a panel that is already open:

bugdump.setTheme('dark');

bugdump('setTheme', 'dark'); // script tag, through the command queue

An app setting of "system" maps to auto. The theme also applies to the screenshot annotation editor. See Matching the widget to your app's theme for React, Vue, and plain JavaScript examples.

Which corner the widget sits in

position moves the button, its teaser bubble, and the panel to the other side of the screen. Use bottom-left when your own UI already lives in the bottom-right corner — a chat launcher, a cookie banner, or a back-to-top button.

Bugdump.init({
  apiKey: 'your-api-key',
  position: 'bottom-left',
});

From a script tag, use the matching attribute:

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

Only the two bottom corners are supported. An unrecognized data-position is ignored with a console warning and the widget falls back to bottom-right.

The button, bubble, and panel are laid out together, so the corner is the only thing you set — the bubble moves to the correct side of the button on its own. With hideButton: true the panel takes the button's place against the corner rather than leaving a gap where the button would have been.

On screens up to 440 pixels wide, such as phones, the corner does not apply to the panel: it opens as a sheet across the bottom of the screen and covers the button until it is closed.

Language

locale sets the language of every string in the widget. The default, 'auto', uses the first language the widget ships in from the page's <html lang>, then the visitor's browser languages, then English. The widget ships in English, Russian, Spanish, French, Portuguese and German.

Bugdump.init({
  apiKey: 'your-api-key',
  locale: 'es',
});

From a script tag, use data-locale="es". Regional tags work too: es-MX gets Spanish. A language the widget doesn't ship falls back to English strings, which you can replace with translations.

See Translating and rebranding the widget for the detection rules, the Widget page setting, and adding a language of your own.

The teaser bubble

bubbleText shows a small dismissible bubble next to the floating button:

Bugdump.init({
  apiKey: 'your-api-key',
  bubbleText: 'Found a bug?',
});

Clicking it opens the widget. Dismissing it is remembered in localStorage, so a user who waves it away does not see it again.

bubbleText is ignored when hideButton is set — there is no button for it to attach to.

Your own trigger button

Set hideButton: true and open the widget from your own UI. Use this when you already have a "Report a problem" item in a menu and do not want a second floating button.

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

document.querySelector('#report-bug').addEventListener('click', () => {
  bugdump.open();
});

From a script tag, set it as an attribute so auto-init applies it, and open through the bugdump(...) command queue:

<script>
  window.bugdump = window.bugdump || function () {
    (window.bugdump.q = window.bugdump.q || []).push(arguments);
  };
</script>
<script
  src="https://bugdump.com/sdk/latest.js"
  async
  data-api-key="your-api-key"
  data-hide-button="true"
></script>
<script>
  document.getElementById('report-bug').addEventListener('click', function () {
    bugdump('open');
  });
</script>

The three-line stub queues bugdump(...) calls made before the async script has finished loading and replays them once it arrives — so a click that lands early opens the panel instead of throwing. See Choosing an installation method for how the stub works.

hideButton hides the trigger; the widget itself still mounts, which is what gives open() something to open. The panel's own close and minimize controls keep working, so make sure your trigger stays reachable — it is the only way back in once a user closes the panel.

Linking reporters to their report

With showReportLink: true, the success screen shows a direct link to the report just created, with a copy button. Useful for internal QA, where the reporter will want to reference what they filed.

When your project has the public portal enabled, the widget footer automatically shows a "View reports" link. That requires no configuration.

Custom endpoint

endpoint only matters for self-hosted or proxied setups. On hosted BugDump, leave it unset.

How the SDK loads

The script tag build loads in two stages, so a page only downloads what it actually uses.

The entry (latest.js, about 33 KB gzipped) carries the widget, the console, network and action collectors, and report submission. Every page pays this.

Two optional chunks are fetched on demand and never touch a page that does not need them:

Because screenshotMethod defaults to screen-capture, most screenshots never load html2canvas at all. Session replay is on every plan, so the recorder is fetched shortly after the widget starts; a page that sets features.sessionReplay: false never downloads it.

If you self-host or proxy the SDK, copy all three files and keep them in the same directory. The entry resolves its chunks relative to its own URL, so serving latest.js alone leaves screenshots and session replay broken while the rest of the widget appears to work normally. You may rename the entry file; the chunk filenames must stay exactly as they are.

A strict Content-Security-Policy needs the SDK's origin in script-src for the chunk requests too, not only for the entry.

Also load the entry with async — see Choosing an installation method for why.

Feature toggles

features: {
  screenshot: true,
  screenshotMethod: 'screen-capture',
  screenRecording: true,
  screenRecordingMethod: 'screen-capture',
  sessionReplay: true,
  attachments: true,
  allowTaskAttach: false,
}

All default to true except allowTaskAttach, which defaults to false. Capture methods are 'screen-capture' or 'dom'. See Feature toggles and handling sensitive data for the full treatment.

Filtering capture

consoleFilter and networkFilter remove specific entries before anything is transmitted. See Filtering console and network capture.

Error capture

The widget sends uncaught errors and unhandled promise rejections to the project's Errors page on its own. captureErrors: false turns that off for one site or build, and release, sampleRate, ignoreErrors and beforeSend tune what is sent.

From a script tag, use data-capture-errors, data-release and data-sample-rate. ignoreErrors and beforeSend have no attribute, because an attribute can't hold a regular expression or a function: load the script without data-api-key and call bugdump('init', { ... }) yourself.

See Capturing JavaScript errors automatically for what an error event carries, what is never sent, and how to send errors you catch yourself.

Translating the widget

Every UI string can be overridden through translations, on top of whichever language locale picked. Pass only the keys you want to change; the rest keep the language's own strings.

Bugdump.init({
  apiKey: 'your-api-key',
  translations: {
    title: 'Report a bug',
    descriptionPlaceholder: 'What did you expect to happen?',
    sendButton: 'Send report',
    successTitle: 'Thanks!',
  },
});

triggerTitle is special: when omitted it falls back to whatever title is set to, so overriding title alone changes both the panel header and the button tooltip.

See Translating and rebranding the widget for every available key.

Restricting which sites can use your key

Widget keys are public by design, but you can restrict which origins are allowed to submit reports with them. Configure allowed origins on the project's Widget page — requests from other origins are rejected with a 403.

See Managing API keys safely.

Checking what took effect

bugdump.getConfig();

Returns the resolved configuration with all defaults merged in — the quickest way to confirm an option actually applied. If an option you passed is not reflected there, an earlier init() almost certainly won.

See also

• Choosing an installation method

• SDK API reference

• Feature toggles and handling sensitive data