Widget Configuration

The BugPin widget is a lightweight, embeddable feedback button that can be fully customized to match your brand. This reference covers all configuration options: button position, shape, colors for light and dark mode, tooltip, hover effects, feature toggles (screenshot, annotation, console capture), and screenshot settings.

Deployment Requirements

HTTPS Requirement

Both your BugPin server and websites embedding the widget must use HTTPS. Browsers block HTTP scripts on HTTPS sites (mixed content blocking).

Requirements:

• Valid SSL/TLS certificate on BugPin server
• HTTPS enabled on your website
• Use a reverse proxy (Nginx, Traefik, Caddy) for SSL termination

See Reverse Proxy Setup for configuration details.

CORS Headers

BugPin automatically configures CORS headers to allow the widget to be embedded on any website:

• Access-Control-Allow-Origin: * - Allows requests from any origin
• Cross-Origin-Resource-Policy: cross-origin - Allows cross-origin loading

No configuration needed - these headers are set automatically.

Reverse Proxy Configuration

Ensure your reverse proxy doesn't strip or override these CORS headers. See Reverse Proxy Setup for details.

Domain Whitelisting

For production deployments, configure domain whitelisting to restrict which websites can use your widget:

1. Go to Projects → Select project
2. Navigate to Settings → Security
3. Add allowed domains (e.g., example.com)
4. Subdomain support: example.com allows example.com and *.example.com

When enabled, the widget only accepts bug reports from whitelisted domains. Other domains receive 403 FORBIDDEN.

Security Recommendation

Enable domain whitelisting for production projects to prevent unauthorized usage.

Configuration Methods

Widget settings can be configured in three ways (in order of priority):

1. Script data attributes - Highest priority, set in HTML
2. Admin panel - Configure in project settings
3. Default values - Built-in defaults

Position

Control where the widget button appears on the screen.

Value	Description
bottom-right	Bottom right corner (default)
bottom-left	Bottom left corner
top-right	Top right corner
top-left	Top left corner

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

Button Appearance

Button Shape

Value	Description
round	Circular button (default)
rectangle	Rectangular button

Button Text

Set custom text to display on the button. If not set, only the icon is shown.

Button Icon

Choose from available icons or use the default bug icon. The icon is displayed alongside any button text.

Icon Customization

Option	Default	Description
buttonIconSize	18	Icon size in pixels
buttonIconStroke	2	Icon stroke width

Theme

The widget supports light and dark modes.

Value	Description
auto	Match user's system preference (default)
light	Always use light mode
dark	Always use dark mode

<script
  src="https://bugs.example.com/widget.js"
  data-api-key="your-project-api-key"
  data-theme="dark"
  async
></script>

Colors

Customize colors for both light and dark modes. All colors should be valid CSS color values (hex, rgb, etc.).

Launcher Button Colors (Light Mode)

Option	Default	Description
lightButtonColor	#02658D	Button background color
lightTextColor	#ffffff	Button text/icon color
lightButtonHoverColor	#024F6F	Button background on hover
lightTextHoverColor	#ffffff	Text/icon color on hover

Launcher Button Colors (Dark Mode)

Option	Default	Description
darkButtonColor	#02658D	Button background color
darkTextColor	#ffffff	Button text/icon color
darkButtonHoverColor	#036F9B	Button background on hover
darkTextHoverColor	#ffffff	Text/icon color on hover

Dialog Colors

The dialog (popup) has separate color settings for its buttons:

Light Mode Dialog:

Option	Default	Description
dialogLightButtonColor	#02658D	Dialog button background
dialogLightTextColor	#ffffff	Dialog button text
dialogLightButtonHoverColor	#024F6F	Dialog button hover background
dialogLightTextHoverColor	#ffffff	Dialog button hover text

Dark Mode Dialog:

Option	Default	Description
dialogDarkButtonColor	#02658D	Dialog button background
dialogDarkTextColor	#ffffff	Dialog button text
dialogDarkButtonHoverColor	#036F9B	Dialog button hover background
dialogDarkTextHoverColor	#ffffff	Dialog button hover text

Tooltip

Show a tooltip when users hover over the widget button.

Option	Default	Description
tooltipEnabled	false	Show tooltip on hover
tooltipText	null	Custom tooltip text

Hover Effects

Option	Default	Description
enableHoverScaleEffect	true	Scale button slightly on hover

Feature Toggles

Enable or disable specific widget features.

Option	Default	Description
enableScreenshot	true	Allow screenshot capture
enableAnnotation	true	Allow screenshot annotation
enableConsoleCapture	true	Capture browser console logs

Screenshot Settings

Capture Method

Value	Description
visible	Capture only the visible viewport (default)
fullpage	Capture the entire scrollable page
element	Capture a specific element

Screen Capture API

Option	Default	Description
useScreenCaptureAPI	false	Use browser's Screen Capture API

The Screen Capture API provides higher quality screenshots but requires user permission.

Maximum Screenshot Size

Option	Default	Description
maxScreenshotSize	5242880	Maximum size in bytes (5MB)

Complete Configuration Example

Here's an example using programmatic initialization with all options:

await BugPin.init({
  apiKey: 'your-project-api-key',
  serverUrl: 'https://bugs.example.com',

  // Position
  position: 'bottom-right',

  // Button appearance
  buttonText: 'Report Bug',
  buttonShape: 'rectangle',
  buttonIcon: 'bug',
  buttonIconSize: 18,
  buttonIconStroke: 2,

  // Theme
  theme: 'auto',

  // Light mode colors
  lightButtonColor: '#02658D',
  lightTextColor: '#ffffff',
  lightButtonHoverColor: '#024F6F',
  lightTextHoverColor: '#ffffff',

  // Dark mode colors
  darkButtonColor: '#02658D',
  darkTextColor: '#ffffff',
  darkButtonHoverColor: '#036F9B',
  darkTextHoverColor: '#ffffff',

  // Dialog colors (light mode)
  dialogLightButtonColor: '#02658D',
  dialogLightTextColor: '#ffffff',
  dialogLightButtonHoverColor: '#024F6F',
  dialogLightTextHoverColor: '#ffffff',

  // Dialog colors (dark mode)
  dialogDarkButtonColor: '#02658D',
  dialogDarkTextColor: '#ffffff',
  dialogDarkButtonHoverColor: '#036F9B',
  dialogDarkTextHoverColor: '#ffffff',

  // Tooltip
  tooltipEnabled: true,
  tooltipText: 'Found a bug? Click here!',

  // Effects
  enableHoverScaleEffect: true,

  // Features
  enableScreenshot: true,
  enableAnnotation: true,
  enableConsoleCapture: true,

  // Screenshot settings
  captureMethod: 'visible',
  useScreenCaptureAPI: false,
  maxScreenshotSize: 5 * 1024 * 1024
});

Note: BugPin.init() returns a Promise<void>. It fetches configuration from the server and merges it with the options you provide (your options take priority).

Admin Panel Configuration

Most settings can be configured through the BugPin admin panel:

1. Go to Projects and select your project
2. Click on Widget Settings
3. Configure appearance, colors, and features
4. Changes apply immediately to all sites using that project's API key

Settings configured via script data attributes will override admin panel settings.