BugPin Widget

Embeddable visual bug reporting widget for web applications. Capture screenshots, annotate issues, and submit bug reports with ease.

Features

• Screenshot Capture - Full page or visible area
• Screen Recording - Record the page with a pen, laser pointer, and click effects, with optional microphone audio, or attach an existing video
• Annotation Tools - Draw, highlight, blur, and add text
• Privacy First - Self-hosted, your data stays on your servers
• Customizable - Match your brand colors and style
• Lightweight - Less than 190KB gzipped
• Dark Mode - Automatic theme detection
• Responsive - Works on all devices
• Multilingual - Translated into 8 languages (English, German, French, Dutch, Spanish, Italian, Japanese, Simplified Chinese) with automatic detection from <html lang> or the visitor's browser
• Framework Agnostic - Works with React, Vue, Angular, Svelte, .NET, and more

Installation

npm install @arantic/bugpin-widget

Usage

import BugPin from '@arantic/bugpin-widget';

BugPin.init({
  apiKey: 'your-project-api-key',
  serverUrl: 'https://your-bugpin-server.com',
});

Starting with version 1.1.3, BugPin.init() reports the package version to the configured BugPin server so administrators can see compatibility warnings. Hosted /widget.js integrations do not send package metadata.

Configuration

The widget automatically fetches its configuration from the BugPin server based on your API key. All visual settings (theme, position, colors, button text) are managed in the BugPin Admin Console.

Required Options

| Option | Type | Description | | ----------- | -------- | ---------------------------------------- | | apiKey | string | Your project API key (from BugPin admin) | | serverUrl | string | Your BugPin server URL |

Optional Options

| Option | Type | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | language | string | BCP 47 language code (e.g. en, de, fr, nl, es, it, ja, zh). Overrides auto-detection and the project's default. | | reporterName | string | Prefills the editable reporter name field. | | reporterEmail | string | Prefills the editable reporter email field. |

Prefill Reporter Details

BugPin.init({
  apiKey: 'your-project-api-key',
  serverUrl: 'https://your-bugpin-server.com',
  reporterName: currentUser.name,
  reporterEmail: currentUser.email,
});

For automatic script-tag initialization:

<script
  src="https://your-bugpin-server.com/widget.js"
  data-api-key="your-project-api-key"
  data-reporter-name="{{ currentUser.name }}"
  data-reporter-email="{{ currentUser.email }}"
></script>

The reporter can still edit both fields before submitting.

Screen recording

Reporters can record their screen from the Recordings tab and attach the clip to the report. They can also drop in an existing MP4, WebM, or MOV file.

Screen recording is off by default. Turn it on in the Admin Console under Widget > Recording, or for a single project under Project Settings > Recording.

| Setting | Default | Allowed values | | -------------------------- | ----------------------------------------- | ---------------------------------------------------- | | Enable Screen Recording | Off | On or off | | Video Quality | Standard (1080p, 15 fps, about 11 MB/min) | Low (720p, 10 fps), Standard, High (1440p, 30 fps) | | Max. Recording Duration | 180 seconds | 10 to 600 seconds | | Max. Video Upload Size | 50 MB | 1 to 100 MB, also applies to uploaded video files | | Daily Video Upload Limit | 2048 MB per project in 24 hours | 0 to 1048576 MB, 0 turns the limit off | | Allow Microphone Recording | Off | On or off, reporters still opt in for each recording |

Recording a clip

1. The first time, the widget explains that the browser will ask what to share. Reporters can skip this notice for later recordings.
2. The browser's picker opens. In Chromium browsers it offers the current tab first.
3. The recording toolbar appears with a 3-second countdown after Start.
4. Reporters can pause, resume, stop, or discard the recording, and annotate the page while recording.

Toolbar tools and their shortcuts:

| Tool | Shortcut | | -------------- | ------------------------- | | Cursor | Alt+V (Option+V on macOS) | | Pen | Alt+P (Option+P on macOS) | | Laser pointer | Alt+L (Option+L on macOS) | | Click effects | Alt+C (Option+C on macOS) | | Undo stroke | Alt+Z (Option+Z on macOS) | | Back to cursor | Esc |

Shortcuts need Alt or Option, so plain keys keep working in the page being recorded. They are ignored while typing in a form field.

Recording stops on its own at the duration limit, or shortly before the clip would pass the upload size limit. When the reporter stops sharing through the browser's own controls, the clip is kept. A clip that is still too large keeps Submit disabled until it is removed.

When the browser supports Element Capture and the current tab is shared, the recording is limited to the page. The toolbar, the red recording frame, and widget notifications stay visible to the reporter but are left out of the video. If a whole screen is shared, the toolbar shows a warning.

Recovery after a crash or reload

While recording, the widget stores the video in the visitor's browser (IndexedDB database bugpin-recordings). If the tab crashes or reloads, the clip is restored the next time the widget loads, and the launcher shows a badge. Stored recordings are deleted once the report is submitted or the clip is removed, and expire after 7 days. A recording is only restored for the same reporter email.

Browser support and requirements

• Screen recording needs getDisplayMedia and MediaRecorder, which current desktop versions of Chrome, Edge, Firefox, and Safari provide. Mobile browsers generally cannot capture the screen; there the Recordings tab only offers video uploads.
• Clips are recorded as WebM or MP4, depending on the browser. The server adds duration and seek information so recordings play and seek correctly in the Admin Console.
• If the host page blocks screen capture with a Permissions-Policy header, or embeds the widget in a cross-origin iframe without allow="display-capture", recording is not available.
• Your reverse proxy must accept uploads up to the configured video size and allow enough time for slower uploads. See the reverse proxy guide. The widget shows upload progress, and reporters can cancel a running upload.

Offline and failed submissions

If the widget cannot reach the server, it stores the report in the browser and sends it automatically once the connection is back, and tells the reporter so. Each report carries a submission id, so retries never create a second report. If the server is reachable but the upload is rejected on the way, for example by a reverse proxy size limit, the reporter is asked to remove or shrink attachments and try again.

Privacy and diagnostic capture

The server controls which diagnostic categories the widget may collect. EU Privacy Mode disables the user activity trail for every project, with no project override. When EU Privacy Mode is off, the activity trail remains available automatically unless the project disables it. Console output, network failures, and storage-key names remain independent project controls; storage-key capture is off by default.

The activity trail records at most 30 recent interactions with buttons, links, inputs, selects, checkboxes, and similar controls. It does not record keystrokes or typed values. Common personal data and token patterns are redacted before entering the in-memory buffer.

Mark sensitive parts of an embedded website with data-bugpin-private. BugPin ignores activity inside the marked element and all of its descendants:

<section data-bugpin-private>
  <!-- Account, payment, health, or other sensitive UI -->
</section>

Activity remains in page memory until it is submitted with a report or cleared. When EU Privacy Mode or the project activity setting disables capture, the widget does not install the activity listener and clears the activity buffer.

Diagnostic capture is fail-closed and server-controlled:

• Console and network capture start only after the widget config has been fetched. Errors that occur before the widget initializes are not captured. If the config request fails, all diagnostic capture stays disabled for the session.
• The capture flags cannot be overridden through local BugPin.init() options; they are always resolved from the server configuration so instance and project privacy settings take precedence.

Language

The widget ships with translations for English, German, French, Dutch, Spanish, Italian, Japanese, and Simplified Chinese.

By default, the active language is resolved in this order:

1. language passed to BugPin.init()
2. data-language attribute on the script tag (when loaded via <script>)
3. The lang attribute on <html> (the widget watches for changes and re-renders)
4. The visitor's browser language
5. The project's default language (configured in the Admin Console)

BugPin.init({
  apiKey: 'your-project-api-key',
  serverUrl: 'https://your-bugpin-server.com',
  language: 'de',
});

Switch the language at runtime, for example when your app's locale changes:

BugPin.setLanguage('fr'); // returns the resolved locale, or null if unsupported
BugPin.getLanguage(); // returns the currently active locale

Framework Examples

React / Vite

import { useEffect } from 'react';
import BugPin from '@arantic/bugpin-widget';

function App() {
  useEffect(() => {
    BugPin.init({
      apiKey: import.meta.env.VITE_BUGPIN_API_KEY,
      serverUrl: import.meta.env.VITE_BUGPIN_SERVER_URL,
    });
  }, []);

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

Next.js

import { useEffect } from 'react';
import BugPin from '@arantic/bugpin-widget';

function App() {
  useEffect(() => {
    BugPin.init({
      apiKey: process.env.NEXT_PUBLIC_BUGPIN_API_KEY,
      serverUrl: process.env.NEXT_PUBLIC_BUGPIN_SERVER_URL,
    });
  }, []);

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

Vue / Nuxt

<script setup>
import { onMounted } from 'vue';
import BugPin from '@arantic/bugpin-widget';

onMounted(() => {
  BugPin.init({
    apiKey: import.meta.env.VITE_BUGPIN_API_KEY,
    serverUrl: import.meta.env.VITE_BUGPIN_SERVER_URL,
  });
});
</script>

Angular

// app.component.ts
import { Component, OnInit } from '@angular/core';
import BugPin from '@arantic/bugpin-widget';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent implements OnInit {
  ngOnInit() {
    BugPin.init({
      apiKey: environment.bugpinApiKey,
      serverUrl: environment.bugpinServerUrl,
    });
  }
}

TypeScript / Vanilla JavaScript

import BugPin from '@arantic/bugpin-widget';

// Initialize when DOM is ready
document.addEventListener('DOMContentLoaded', () => {
  BugPin.init({
    apiKey: 'your-api-key',
    serverUrl: 'https://bugpin.example.com',
  });
});

.NET / Blazor

// Services/BugPinService.cs
public class BugPinService
{
    private readonly IJSRuntime _js;

    public BugPinService(IJSRuntime js) => _js = js;

    public async Task InitializeAsync(string apiKey, string serverUrl)
    {
        await _js.InvokeVoidAsync("eval",
            $"import('@arantic/bugpin-widget').then(m => m.default.init({{apiKey: '{apiKey}', serverUrl: '{serverUrl}'}}))");
    }
}

// Program.cs or Startup.cs
builder.Services.AddScoped<BugPinService>();

@inject BugPinService BugPin
@inject IConfiguration Config

@code {
    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            await BugPin.InitializeAsync(
                Config["BugPin:ApiKey"],
                Config["BugPin:ServerUrl"]
            );
        }
    }
}

Environment Variables

Store your API key in environment variables (see framework examples above for usage):

# Vite (React, Vue) - .env
VITE_BUGPIN_API_KEY=your-api-key
VITE_BUGPIN_SERVER_URL=https://bugpin.example.com

# Next.js - .env.local
NEXT_PUBLIC_BUGPIN_API_KEY=your-api-key
NEXT_PUBLIC_BUGPIN_SERVER_URL=https://bugpin.example.com

# .NET (appsettings.json)
{
  "BugPin": {
    "ApiKey": "your-project-api-key",
    "ServerUrl": "https://bugpin.example.com"
  }
}

Getting Your API Key

You need an API key from your BugPin server to initialize the widget.

1. Deploy BugPin server on your infrastructure (e.g. using Docker)
2. Log in to the BugPin Admin Console
3. Open Projects, create a new project or select an existing one
4. Copy the API key (shown in the project card or in Project Settings)

Documentation

For complete documentation, visit: BugPin Documentation

License

MIT

Support

• Documentation
• Changelog
• Report Issues
• Discussions