Documentation

1. Quick Start

Install the Universal Bug Reporter in less than 1 minute. The widget is fully standalone, framework agnostic, and extremely lightweight (< 60kb). It has zero dependencies.

Vanilla HTML

Copy and paste this snippet just before the closing </body> tag.

React / Next.js

If using Next.js (App Router), add it to your app/layout.tsx.

import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script src="https://your-cdn.com/universal-bug-widget.js" strategy="lazyOnload" />
      </body>
    </html>
  )
}

2. Configuration

Customize the widget using simple data- attributes on the script tag.

Attribute	Description	Example
data-key	Your License Key. Required to unlock Pro/Agent features like AI analysis and MCP.	data-key="PRO_12345"
data-project-id	Links the incoming bug reports directly to a specific project dashboard in your account.	data-project-id="prj_xyz123"
data-theme	Button and widget color theme. Options: `light`, `dark`, `brand`.	data-theme="brand"
data-position	Widget floating position. Options: `bottom-right`, `bottom-left`.	data-position="bottom-left"
data-exclude-logs	Comma separated list of log levels to ignore and not send. Options: `info`, `warn`.	data-exclude-logs="info"

Example with Configuration

3. Advanced Features (AI & MCP)

🧠 Gemini 2.5 Analysis

Available on the Pro plan. The widget automatically captures a rolling buffer of your console logs and network errors. When a user reports a bug, these are safely transmitted to Google's Gemini 2.5 models alongside DOM state.

How to use: Open the widget, navigate to the AI Analysis tab, and click Unlock (requires an active internet connection to contact the AI). The model will suggest a precise, copy-pasteable code fix based on the logs.

🤖 MCP Agent Integration

Available on the Agent plan. Connect your autonomous AI agent (Cursor, Windsurf, etc.) to our standardized Model Context Protocol Server. Your local agent can securely listen for incoming bugs in real-time.

// Example Schema payload
{
  "appId": "prj_xyz123",
  "errorMsg": "Uncaught ReferenceError",
  "stackTrace": [...]
}

Endpoint: wss://api.bugreporter.io/mcp

🛡️ Log Sniffing & Privacy (GDPR)

To provide accurate fixes while maintaining strict privacy, the widget automatically manages data cleanly:

Session Logs: Captures console.log/warn/error locally without external transmission until the user clicks Report.
Consent Popup: A mandatory customizable consent dialog appears before any DOM screenshot or data is captured.

System Info: Captures OS, Browser, and Resolution. No IP tracking.
PII Masking: Sensitive input fields (password, credit-card, email) are automatically blurred out of the screenshot and redacted from strings.

4. Troubleshooting

Issue	Solution
Widget does not appear	Check that the `src` URL in your script tag is correct and that the script is placed before the closing `</body>` tag. Check your browser console for CSP errors.
AI Analysis Unavailable	If you are on the Free plan, AI analysis is locked. Upgrade to Pro. Check your monthly quota in your dashboard. Verify your `data-key` is valid.
Invalid Domain Error	The Free plan allows only 1 specific domain. If you are testing on localhost or a staging site, ensure it matches the registered domain in your account settings.

5. FAQ

Is it compatible with React / Vue / Angular?

Yes! Since the widget is built with Vanilla JavaScript and has zero dependencies, it works with any framework. Just add the script tag to your index.html.

Where do my data go?

All reports are securely transmitted to our Google Cloud servers. We process logs only for the purpose of analysis and do not store them longer than your plan allows (48h for Free, 30d for Pro).

Can I self-host the backend?

Currently, the hosted service uses specialized Google Cloud infrastructure for Gemini 2.5. An Enterprise self-hosted version is planned for Q4 2026.

Does the widget slow down my website?

No. The main JS bundle is loaded asynchronously and only activates when the user clicks the trigger button. The background log sniffing has < 1ms overhead.

How is the screenshot captured?

We use a customized version of html2canvas to render the DOM locally in the user's browser, meaning no external servers render your page.

Can I customize the trigger button?

Yes, you can apply your own CSS to the #ubr-trigger-btn element or use the data-theme attribute for built-in themes.