Screenshot Capture: Visual Context for Feedback

When users submit feedback, words can only convey so much. A screenshot captures exactly what they were seeing at that moment, making it infinitely easier to understand and resolve issues. Qaid offers flexible screenshot capture that works across different browsers and use cases.

Enabling Screenshot Capture

To add screenshot capture to your feedback widget, set captureScreenshot: true in your configuration:

<script
  src="https://unpkg.com/@qaiddev/thumbs-embed"
  data-endpoint="/api/feedback"
  data-capture-screenshot="true"
></script>

Or via JavaScript:

import { QaidFeedback } from '@qaiddev/thumbs-embed';

new QaidFeedback({
  endpoint: '/api/feedback',
  captureScreenshot: true
});

When enabled, the embed automatically captures a screenshot when users submit feedback. The image is compressed as WebP and included in the feedback payload.

Choosing a Capture Method

Qaid supports two screenshot capture methods, each with distinct tradeoffs. Choose the one that best fits your users and application.

Permission-Based Capture (Default)

The "permission" method uses the browser’s native Screen Capture API. This is the default when captureScreenshot is enabled.

new QaidFeedback({
  endpoint: '/api/feedback',
  captureScreenshot: true,
  screenshotMethod: 'permission'  // This is the default
});

How it works:

1. When the user submits feedback, the browser prompts them to share their screen
2. The user selects the current tab (modern browsers like Chrome auto-suggest it)
3. A frame is captured from the video stream
4. The stream is immediately stopped

Advantages:

• Pixel-perfect accuracy, exactly what the user sees
• Captures everything including canvas elements, WebGL, iframes, and dynamic content
• Works with any CSS, animations, or complex layouts
• No additional library dependencies

Tradeoffs:

• Requires user interaction (clicking “Share” in the browser dialog)
• Users may be confused or concerned by the permission prompt
• Some users may decline to share

DOM-Based Capture

The "dom" method reconstructs the page visually from the DOM using html2canvas. No permission dialog is shown.

new QaidFeedback({
  endpoint: '/api/feedback',
  captureScreenshot: true,
  screenshotMethod: 'dom'
});

How it works:

1. When feedback is submitted, html2canvas traverses the DOM
2. It reads computed styles and reconstructs the visual appearance
3. The result is drawn to a canvas element
4. The canvas is exported as a WebP image

Advantages:

• Completely automatic, no user interaction required
• No permission dialogs, invisible to the user
• Works in all browsers with canvas support

Tradeoffs:

• May not capture everything (canvas content, WebGL, some CSS features)
• Cross-origin images may be missing unless CORS headers are set
• Complex CSS like certain filters or blend modes may render differently
• Requires loading the html2canvas library (~40KB)

Comparing the Methods

Feature	Permission	DOM
Accuracy	Pixel-perfect	Good, with limitations
User interaction	Required (permission dialog)	None
Canvas/WebGL	Yes	No
Cross-origin content	Yes	Limited by CORS
Complex CSS	Full support	Partial support
Library dependency	None	html2canvas (~40KB)
Browser support	Modern browsers	All browsers with canvas

Our recommendation: Start with the default "permission" method. If user friction from the permission dialog becomes an issue, switch to "dom". For internal tools and dashboards where accuracy matters, stick with "permission".

Quality and Size Options

Control the output image quality and dimensions with screenshotOptions:

new QaidFeedback({
  endpoint: '/api/feedback',
  captureScreenshot: true,
  screenshotOptions: {
    quality: 0.8,      // WebP compression (0-1), default: 1.0
    maxWidth: 1920,    // Maximum width in pixels, default: 1280
    maxHeight: 1080    // Maximum height in pixels, default: 800
  }
});

Quality Setting

The quality parameter controls WebP compression:

• 1.0 - Lossless quality, larger files (~500KB-2MB typical)
• 0.8 - High quality, good compression (~100-400KB typical)
• 0.6 - Medium quality, smaller files (~50-150KB typical)

For most use cases, 0.8 provides an excellent balance of clarity and file size. If you’re storing many screenshots or have bandwidth concerns, consider 0.6.

Dimension Limits

The maxWidth and maxHeight settings cap the output dimensions while preserving aspect ratio. The screenshot is scaled down proportionally if it exceeds either limit.

Default values (1280x800) work well for most feedback use cases. Increase them if you need to capture high-resolution displays or if users commonly view your app on large monitors.

// For high-DPI displays or detailed UI
screenshotOptions: {
  quality: 0.9,
  maxWidth: 2560,
  maxHeight: 1440
}

// For minimal storage footprint
screenshotOptions: {
  quality: 0.6,
  maxWidth: 800,
  maxHeight: 600
}

Server-Side Capture (Pro Feature)

For Pro plan users, Qaid offers server-side screenshot capture as a fallback. When client-side capture fails or is declined by the user, the feedback payload includes element bounds and user agent information that our servers can use to render a screenshot.

This is particularly useful when:

• Users decline the permission prompt
• The DOM method cannot capture certain content
• You need consistent screenshots across all feedback

Server-side capture uses headless browsers to visit the page URL and capture the specified viewport, ensuring you always have visual context for feedback.

To enable server-side fallback, ensure your pages are publicly accessible or configure authenticated access in your project settings.

Complete Configuration Example

Here’s a full configuration showing all screenshot-related options:

import { QaidFeedback } from '@qaiddev/thumbs-embed';

new QaidFeedback({
  endpoint: '/api/feedback',
  apiKey: 'your-api-key',

  // Enable screenshot capture
  captureScreenshot: true,

  // Choose capture method
  screenshotMethod: 'permission',  // or 'dom'

  // Fine-tune output
  screenshotOptions: {
    quality: 0.85,
    maxWidth: 1600,
    maxHeight: 1000
  },

  // Other configuration
  position: 'bottom-right',
  colors: {
    positive: '#22c55e',
    negative: '#ef4444'
  }
});

Or using HTML data attributes:

<script
  src="https://unpkg.com/@qaiddev/thumbs-embed"
  data-endpoint="/api/feedback"
  data-api-key="your-api-key"
  data-capture-screenshot="true"
  data-screenshot-method="dom"
></script>

Best Practices

Inform your users. Consider adding a note in your privacy policy that feedback may include screenshots. Transparency builds trust.

Test both methods. Try permission-based capture with your actual users. If adoption suffers, switch to DOM-based capture.

Monitor file sizes. If storage costs become a concern, reduce quality or dimensions. The visual context is valuable even at lower resolutions.

Handle failures gracefully. Screenshot capture can fail for various reasons. The embed handles this automatically and submits feedback without the screenshot rather than failing entirely.

With screenshot capture enabled, your feedback inbox transforms from a list of text descriptions into a visual record of exactly what users experienced. Issues become easier to reproduce, understand, and resolve.