Documentation

Everything you need to integrate IssueCapture

Installation

Add IssueCapture to your website in 3 simple steps:

1Add & Initialize

Include the script and initialize it with your API key in your HTML, right before the closing </body> tag:

<script type="module">
  import IssueCapture from 'https://issuecapture.com/widget.js';
  IssueCapture.init({ apiKey: 'your_api_key_here' });
</script>

That's it! A floating "Report Issue" button will appear automatically in the bottom-right corner.

Note

You can find your API key in your dashboard. Only 40KB gzipped initial load.

2Optional: Customize Trigger

Want to use your own button instead of the automatic one? Specify a custom trigger:

<button id="feedback">Report Issue</button>

<script type="module">
  import IssueCapture from 'https://issuecapture.com/widget.js';
  IssueCapture.init({
    apiKey: 'your_api_key_here',
    trigger: '#feedback'  // Use your own button
  });
</script>

Success!

Your widget is now ready to collect issues.

Configuration

Most settings are configured in your dashboard

Theme, title, components, and features are set once in the dashboard UI. Only runtime options need to be passed in code.

Required

{
  apiKey: 'string'       // Your IssueCapture API key
}

Optional Runtime Options

{
  // Required
  apiKey: 'string',                    // Your API key (required)

  // Trigger
  trigger: 'string' | 'auto',          // CSS selector or 'auto' for floating button

  // Auto-button (when trigger: 'auto')
  button: {
    position: 'bottom-right',          // bottom-right, bottom-left, top-right, top-left
    text: 'Report Issue',              // Button text
    icon: '🐛',                        // Button icon/emoji
    offset: { x: 20, y: 20 },          // Offset from corner (pixels)
    style: {
      backgroundColor: '#7C3AED',      // Background color
      textColor: '#FFFFFF',            // Text color
      borderRadius: '50px',            // Border radius
      size: 'medium',                  // small, medium, large
      shadow: true                     // Drop shadow
    },
    zIndex: 999999,                    // Z-index
    hidden: false                      // Start hidden (use show() to reveal)
  },

  // Internationalization (16 languages)
  locale: 'en',                        // en, es, de, fr, pt, ja, zh, it, nl, ru, pl, tr, ko, sv, da, no

  // Modal Title Override
  title: 'string',                     // Override dashboard title

  // Current User (dynamic per user)
  user: {
    name: 'string',                    // Pre-fill user name
    email: 'string'                    // Pre-fill user email
  },

  // Default Form Values
  defaultValues: {
    priority: 'string',                // Default priority
    component: 'string',               // Default component/team
    labels: ['string'],                // Pre-select labels
    customFields: {                    // Custom field defaults
      'customfield_10001': 'value'
    }
  },

  // Privacy Options
  enableMetadata: true,                // Collect page URL, user agent
  networkCaptureOptions: {
    sanitizeUrls: true,                // Strip query params/IDs from URLs
    excludeDomains: ['stripe.com'],    // Never capture these domains
    excludePatterns: ['/auth/', '/password'] // Exclude sensitive paths
  },

  // Callbacks
  onSubmit: function(data) {},         // After successful submission
  onOpen: function() {},               // When widget opens
  onClose: function() {},              // When widget closes
  onError: function(error) {}          // On error
}

Dashboard Settings (Loaded Automatically)

These are configured once in your dashboard and loaded when widget opens. Dashboard settings override JavaScript config:

  • Form fields (components, labels, etc.)
  • Required fields validation
  • Screenshot requirements
  • Error capture (console/network)
  • File attachments permissions
  • Themes & custom CSS
  • AI features settings
  • Jira project options

Note: Dashboard settings are fetched when the widget first opens (not at page load). Settings like requireScreenshot and captureConsoleLogs from dashboard will override any values set in JavaScript.

Runtime Customization

Pre-fill User Data

Pre-fill the form with the current user's information:

IssueCapture.init({
  apiKey: 'your_api_key',
  user: {
    name: 'John Doe',
    email: 'john@example.com'
  }
});

Tip: If you have user authentication, dynamically pass the logged-in user's details.

Custom Trigger

Use any CSS selector to trigger the widget with your own button:

<!-- Using ID -->
<button id="feedback-btn">Report Issue</button>

IssueCapture.init({
  apiKey: 'your_api_key',
  trigger: '#feedback-btn'  // ID selector
});

<!-- OR using Class -->
<button class="feedback-button">Report Issue</button>

IssueCapture.init({
  apiKey: 'your_api_key',
  trigger: '.feedback-button'  // Class selector
});

CSS Selectors: Use #id for IDs,.class for classes, or any valid selector likebutton[data-feedback]

Set Field Defaults

Programmatically set default values for priority, component, labels, and custom fields:

IssueCapture.init({
  apiKey: 'your_api_key',
  trigger: '#bug-button',
  defaultValues: {
    priority: 'High',              // Set default priority
    component: 'Frontend',         // Set default component
    labels: ['bug', 'ui'],         // Pre-select labels
    customFields: {                // Set custom field values
      'customfield_10001': 'value'
    }
  }
});

Use Case: Great for setting context-based defaults like priority based on user role, or component based on current page section.

Custom Fields

Add custom Jira fields to your issue submission form. IssueCapture automatically fetches field options from Jira.

How It Works

  1. Dashboard Setup - Go to your widget's Form Configuration page
  2. Click "Add Custom Field" - Fetches available fields from your Jira project
  3. Select Field - Choose from dropdown fields, text fields, multi-selects, etc.
  4. Configure - Set placeholder text, help text, and required status
  5. Save - Field appears in the widget form with all options from Jira

Supported Field Types

Text Fields

  • Single-line text
  • Multi-line textarea
  • Number input

Selection Fields

  • Single select dropdown
  • Multi-select checkboxes
  • Radio buttons

Special Fields

  • Date picker
  • Checkbox (boolean)
  • User picker (text input)

Automatic Features

  • Options fetched from Jira
  • Required field validation
  • Default values support

Setting Default Values Programmatically

Pre-fill custom field values when initializing the widget:

IssueCapture.init({
  apiKey: 'your_api_key',
  defaultValues: {
    customFields: {
      'customfield_10001': 'Critical',     // Single select (Urgency)
      'customfield_10002': 'v2.1.0',       // Text field (Version)
      'customfield_10003': ['Tag1', 'Tag2'] // Multi-select
    }
  }
});

Note: Field IDs (like customfield_10001) must match exactly what Jira uses. Find them in your dashboard when adding custom fields.

Pro Tip

Custom fields with dropdown options automatically show all available values from Jira. Users can select from these options without needing to know the exact values.

API Reference

IssueCapture.init(config)

Initialize the IssueCapture widget with your configuration.

Parameters

  • config (Object) - Configuration options

Returns

void

IssueCapture.init({
  apiKey: 'your_api_key'
});

IssueCapture.open()

Programmatically open the widget modal.

Returns

void

// Open widget on button click
document.getElementById('custom-button').addEventListener('click', () => {
  IssueCapture.open();
});

IssueCapture.close()

Programmatically close the widget modal.

Returns

void

IssueCapture.close();

Events

Listen to widget events with callbacks:

onSubmit

Called when an issue is successfully submitted.

IssueCapture.init({
  apiKey: 'your_api_key',
  onSubmit: function(data) {
    console.log('Issue submitted:', data);
    // data contains: issueId, summary, description, etc.
  }
});

onOpen / onClose

Track when users open or close the widget.

IssueCapture.init({
  apiKey: 'your_api_key',
  onOpen: function() {
    console.log('Widget opened');
    // Track analytics, show help text, etc.
  },
  onClose: function() {
    console.log('Widget closed');
  }
});

Custom Styling

Customize your widget's appearance with CSS. IssueCapture uses Shadow DOM isolation, so your custom CSS won't affect your website.

Dashboard Theme Editor

The easiest way to customize your widget is through the dashboard:

  1. Go to Widgets → Your Widget → Theme
  2. Choose from preset themes (Default, Dark, Minimal, etc.)
  3. Customize colors, border radius, and font family
  4. Add custom CSS for advanced styling
  5. Preview changes in real-time

Available CSS Selectors

Use these CSS selectors to target specific parts of the widget:

/* Main Widget Container */
.issuecapture-modal { }              /* Main modal wrapper */
.issuecapture-backdrop { }           /* Background overlay */

/* Modal Structure */
.issuecapture-header { }             /* Modal header */
.issuecapture-header h2 { }          /* Modal title text */
.issuecapture-close { }              /* Close button */
.issuecapture-content { }            /* Modal body/content */

/* Form Elements */
.issuecapture-form-group { }         /* Form field wrapper */
.issuecapture-label { }              /* Field labels */
.issuecapture-input { }              /* Text inputs */
.issuecapture-textarea { }           /* Text areas */
.issuecapture-select { }             /* Select dropdowns */

/* Buttons */
.issuecapture-btn { }                /* All buttons */
.issuecapture-btn-primary { }        /* Primary action buttons */
.issuecapture-btn-secondary { }      /* Secondary buttons */
.issuecapture-btn-ghost { }          /* Ghost/outline buttons */

/* States */
.issuecapture-success { }            /* Success screen */
.issuecapture-loading { }            /* Loading state */
.issuecapture-spinner { }            /* Loading spinner */

/* Screenshot Capture */
.issuecapture-screenshot-capture { } /* Screenshot step container */
.issuecapture-screenshot-title { }   /* Screenshot step title */

Important Notes:

  • Use !important to override default styles
  • CSS is sanitized for security — patterns like scripts are blocked
  • Shadow DOM isolation means your CSS won't affect your website

Need help?

Our team is here to assist you with any integration challenges.

Contact Support