Skip to main content

Widget Installation

Add the BugPin widget to your website with a single script tag.

Quick Start​

Add the following script tag to your HTML, just before the closing </body> tag:

<script
  src="https://your-bugpin-server.com/widget.js"
  data-api-key="your-project-api-key"
  async
></script>

Replace:

  • your-bugpin-server.com with your BugPin server URL
  • your-project-api-key with the API key from your project settings

Getting Your API Key​

  1. Log in to the BugPin admin panel
  2. Go to Projects and select your project (or create a new one)
  3. Copy the API Key from the project settings

Script Attributes​

AttributeRequiredDescription
data-api-keyYesYour project's API key
data-server-urlNoBugPin server URL (defaults to the script's origin)
data-positionNoWidget position (overrides admin settings)
data-button-textNoButton text (overrides admin settings)
data-themeNolight or dark (overrides admin settings)

Example with Options​

<script
  src="https://bugs.example.com/widget.js"
  data-api-key="bp_proj_abc123"
  data-position="bottom-left"
  data-theme="dark"
  async
></script>

Programmatic Initialization​

For more control, you can initialize the widget programmatically:

<script src="https://bugs.example.com/widget.js" async></script>
<script>
  // Wait for the widget to load
  window.addEventListener('load', function() {
    if (window.BugPin) {
      window.BugPin.init({
        apiKey: 'your-project-api-key',
        serverUrl: 'https://bugs.example.com',
        position: 'bottom-right',
        theme: 'auto'
      });
    }
  });
</script>

JavaScript API​

The widget exposes a global BugPin object with the following methods:

BugPin.init(config)​

Initialize the widget with custom configuration.

BugPin.init({
  apiKey: 'your-api-key',
  serverUrl: 'https://bugs.example.com',
  position: 'bottom-right',
  buttonText: 'Report Bug',
  theme: 'auto'
});

BugPin.open()​

Programmatically open the bug report dialog.

// Open the widget when a button is clicked
document.getElementById('report-bug').addEventListener('click', function() {
  BugPin.open();
});

BugPin.close()​

Programmatically close the bug report dialog.

BugPin.close();

Single Page Applications (SPA)​

The widget works with SPAs built with React, Vue, Angular, and other frameworks. It automatically detects route changes and captures the current URL.

React Example​

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    // Load widget script
    const script = document.createElement('script');
    script.src = 'https://bugs.example.com/widget.js';
    script.async = true;
    script.setAttribute('data-api-key', 'your-api-key');
    document.body.appendChild(script);

    return () => {
      // Cleanup on unmount
      const widget = document.getElementById('bugpin-widget');
      if (widget) widget.remove();
    };
  }, []);

  return <div>Your app content</div>;
}

Vue Example​

<script setup>
import { onMounted, onUnmounted } from 'vue';

onMounted(() => {
  const script = document.createElement('script');
  script.src = 'https://bugs.example.com/widget.js';
  script.async = true;
  script.setAttribute('data-api-key', 'your-api-key');
  document.body.appendChild(script);
});

onUnmounted(() => {
  const widget = document.getElementById('bugpin-widget');
  if (widget) widget.remove();
});
</script>

Content Security Policy (CSP)​

If your site uses a Content Security Policy, add the following directives:

script-src 'self' https://your-bugpin-server.com;
connect-src 'self' https://your-bugpin-server.com;
style-src 'self' 'unsafe-inline';
img-src 'self' data: blob:;

Style Isolation​

The widget uses Shadow DOM to encapsulate its styles. This means:

  • Widget styles won't affect your site's styles
  • Your site's styles won't affect the widget
  • The widget works on any site regardless of CSS frameworks used

Offline Support​

The widget automatically handles offline scenarios:

  1. If the user is offline when submitting a report, it's cached locally
  2. When connectivity is restored, cached reports are automatically submitted
  3. Reports include retry logic with exponential backoff

Next Steps​