FeedbackEcho Embedded Widget Integration Guide

Overview

The FeedbackEcho embedded widget allows you to easily collect user feedback on any website. With just one line of code integration, it supports multi-language (English only in current configuration), privacy protection, and performance optimization.

🚀 Quick Start

Basic Integration

Add the following code to your HTML page:

<body>
  <!-- Custom Button -->
  <button onclick="openFeedback()" style="position: fixed; bottom: 20px; right:
20px; padding: 12px 24px; background: #4f46e5; color: white; border: none;
border-radius: 25px; cursor: pointer; box-shadow: 0 4px 12px rgba(79,70,229,0.3);
font-size: 16px; z-index: 9999;">
    💬 Feedback
  </button>
  <script>
    function openFeedback() {
      if (window.FeedbackEchoWidget) {
        window.FeedbackEchoWidget.open();
      } else {
        alert('Widget loading failed');
      }
    }
    setTimeout(() => {
      if (window.FeedbackEchoWidget) {
        console.log('✅ FeedbackEcho Widget loaded');
      }
    }, 2000);
  </script>
  <script src="https://feedback-echo.com/widget/v1/[your-organization-slug].js?v=3.2&min=true"></script>
</body>

Replace [your-organization-slug] with your organization's unique identifier. The widget will automatically load and appear in the bottom-right corner of your page.

Finding Your Organization Slug

Login to your FeedbackEcho dashboard
Navigate to Settings → Organization Settings
Your organization slug is displayed in the URL or organization information section
Alternatively, contact your team administrator for the organization slug

📋 Integration Methods

1. Basic Integration

The simplest one-line code integration:

<script src="https://feedback-echo.com/widget/v1/[your-organization-slug].js?v=3.2&min=true"></script>

Features: - Auto-initialization - Optimized caching - Minified code - Version control

2. Lazy Loading (Recommended)

Improve page load performance by loading the widget only when needed:

<script>
  // Lazy loading with Intersection Observer
  (function() {
    const loadWidget = () => {
      const script = document.createElement('script');
      script.src = 'https://feedback-echo.com/widget/v1/[your-organization-slug].js?v=3.2&min=true';
      script.async = true;
      document.head.appendChild(script);
    };
    // Load when user scrolls near bottom or interacts
    const observer = new IntersectionObserver((entries) => {
      if (entries[0].isIntersecting) {
        loadWidget();
        observer.disconnect();
      }
    }, { rootMargin: '200px' });
    // Create trigger element at bottom of page
    const trigger = document.createElement('div');
    trigger.style.position = 'absolute';
    trigger.style.bottom = '0';
    trigger.style.height = '1px';
    trigger.style.width = '1px';
    trigger.style.visibility = 'hidden';
    document.body.appendChild(trigger);
    observer.observe(trigger);
    // Also load on first user interaction
    ['click', 'scroll', 'mousemove'].forEach(event => {
      document.addEventListener(event, loadWidget, { once: true });
    });
    // Fallback timer
    setTimeout(loadWidget, 10000);
  })();
</script>

Features: - Intersection Observer technology - User interaction triggers - Fallback timer - Performance optimized

3. Custom Configuration

Control widget appearance and behavior:

<script src="https://feedback-echo.com/widget/v1/[your-organization-slug].js?v=3.2&min=true"></script>
<script>
  // Customize widget behavior after load
  window.addEventListener('load', function() {
    if (window.FeedbackEchoWidget) {
      window.FeedbackEchoWidget.config.position = 'top-left';
      window.FeedbackEchoWidget.config.button_text = 'Give Feedback';
      window.FeedbackEchoWidget.config.theme = 'minimal';
    }
  });
</script>

Features: - Custom position - Custom text - Theme selection - Runtime configuration

4. Programmatic Control

Full JavaScript API control over the widget:

<script src="https://feedback-echo.com/widget/v1/[your-organization-slug].js?v=3.2&min=true"></script>
<script>
  // Control widget programmatically
  function showFeedbackWidget() {
    if (window.FeedbackEchoWidget) {
      window.FeedbackEchoWidget.open();
    }
  }
  function hideFeedbackWidget() {
    if (window.FeedbackEchoWidget) {
      window.FeedbackEchoWidget.hide();
    }
  }
  // Open widget when user clicks custom button
  document.addEventListener('DOMContentLoaded', function() {
    const btn = document.getElementById('custom-feedback-btn');
    if (btn) {
      btn.addEventListener('click', showFeedbackWidget);
    }
  });
</script>

Features: - JavaScript API - Event handlers - Full control - DOM ready handling

⚙️ Configuration Options

Widget Settings

Parameter	Type	Default	Description
`position`	string	'bottom-right'	Widget position: 'bottom-right', 'bottom-left', 'top-right', 'top-left'
`button_text`	string	'Feedback'	Button display text
`primary_color`	string	'#3B82F6'	Primary color (hex)
`collect_email`	boolean	true	Whether to collect email
`collect_name`	boolean	true	Whether to collect name
`show_categories`	boolean	true	Whether to show category options
`show_priority`	boolean	false	Whether to show priority selector
`auto_screenshot`	boolean	false	Whether to auto-capture screenshots
`gdpr_compliant`	boolean	true	Whether to enable GDPR compliance
`theme`	string	'default'	Visual theme
`animation`	string	'slide'	Animation effect: 'slide', 'fade', 'none'
`lazy_load`	boolean	true	Whether to use lazy loading
`trigger_delay`	number	0	Delay before showing widget (ms)
`max_length`	number	1000	Maximum feedback message length
`rate_limit`	number	10	Max submissions per hour
`debounce_delay`	number	300	Input debounce delay (ms)
`preload_threshold`	number	1000	Pixels before viewport to start preloading

URL Parameters

Parameter	Description
`v`	Version number for cache control
`min`	Whether to use minified version

Theme Customization

The widget supports theme-based styling through CSS files:

<!-- Load a custom theme -->
<link rel="stylesheet" href="https://feedback-echo.com/widget/v1/css/minimal.css">
<script src="https://feedback-echo.com/widget/v1/[your-organization-slug].js"></script>

Available Themes: - default - Standard FeedbackEcho theme - minimal - Clean, minimal design - dark - Dark mode theme - custom - Organization-specific branding (Pro/Enterprise plans)

🔒 Privacy Protection (GDPR Compliance)

The FeedbackEcho widget is fully GDPR compliant:

Consent Banner

When GDPR compliance is enabled, the widget first shows a consent banner:

Accept: User agrees to data processing
Decline: Widget is not shown
Settings: Opens detailed privacy settings

Privacy Settings

Provides complete data processing information:

Processing Purpose: Service quality improvement
Data Retention: 2 years
Processor: FeedbackEcho
User Rights: Access, rectification, erasure, portability
Contact: privacy@feedback-echo.com

Consent Management

Uses LocalStorage to store consent state
Consent timestamp recording
Can revoke consent at any time
Consent verification before data submission

🌍 Language Support

The widget currently supports English as the primary language. The application is configured with:

config.i18n.available_locales = [:en]
config.i18n.default_locale = :en

While the widget infrastructure supports multiple languages (zh, ja, ko), the current deployment is English-only to ensure consistency across the platform.

📱 Responsive Design

The widget automatically adapts to different devices:

Desktop: Full-featured interface
Tablet: Touch-optimized
Mobile: Full-screen modal window
Small screens: Simplified interface

⚡ Performance Optimization

Caching Strategy

The widget implements advanced caching for optimal performance:

Production Environment: - 24-hour cache duration (max-age=86400) - ETag conditional request support - Immutable cache headers - S-maxage for CDN optimization

Development Environment: - 5-minute cache duration for testing - Public cache enabled

Code Optimization

Minification: Automatic code minification when min=true parameter is used
Version Control: Cache busting with v parameter
Gzip Compression: Automatic compression for smaller file sizes
Conditional Loading: ETag support prevents unnecessary downloads

Lazy Loading Features

Intersection Observer: Loads widget when user scrolls near trigger points
User Interaction Triggers: Activates on first user interaction (click, scroll, mousemove)
Fallback Timer: 10-second timer ensures loading even without interaction
Preload Threshold: Configurable pixel distance for early loading (default: 1000px)

🛠️ JavaScript API

Basic Methods

// Open widget
FeedbackEchoWidget.open()

// Close widget
FeedbackEchoWidget.close()

// Hide widget button
FeedbackEchoWidget.hide()

// Show widget button
FeedbackEchoWidget.show()

// Destroy widget
FeedbackEchoWidget.destroy()

// Get performance metrics
FeedbackEchoWidget.getMetrics()

// Access configuration
FeedbackEchoWidget.config

API Endpoints

The widget communicates with the following API endpoints:

Config: /api/v1/widget/config/[organization-slug]
Feedback Submission: /api/v1/widget/feedback/[organization-slug]
Boards List: /api/v1/widget/boards/[organization-slug]
Translations: /api/v1/widget/translations/[locale]

Event Listeners

// Widget loaded
window.addEventListener('feedbackWidgetLoaded', function() {
  console.log('FeedbackEcho Widget loaded');
});

// User opened feedback form
window.addEventListener('feedbackModalOpened', function() {
  console.log('User opened feedback form');
});

// Feedback submitted successfully
window.addEventListener('feedbackSubmitted', function(event) {
  console.log('Feedback submitted:', event.detail);
});

🔧 Troubleshooting

Common Issues

Issue: Widget not showing - Check if organization slug is correct - Confirm widget is enabled in dashboard - Check browser console for error messages

Issue: CORS errors - Ensure loading from correct domain - Check CORS settings - Contact technical support

Issue: Slow loading - Use lazy loading method - Enable CDN acceleration - Check network connection

Debug Mode

<script>
  // Enable debug mode
  window.FeedbackEchoDebug = true;
</script>
<script src="https://feedback-echo.com/widget/v1/[your-organization-slug].js"></script>

📊 Analytics & Monitoring

Performance Metrics

Load time
Cache hit rate
Error rate
Conversion rate

Usage Statistics

Widget impressions
Form open rate
Submission completion rate
Popular pages

Optimization Recommendations

The system automatically provides performance optimization suggestions: - Load time optimization - Cache setting improvements - Error rate reduction - Conversion rate enhancement

🆘 Technical Support

For assistance, please contact:

Documentation: https://feedback-echo.com/docs/widget-integration-guide
Support Email: feedbackecho.manager@gmail.com
Live Demo: https://feedback-echo.com/demo/widget

🔒 Security & Compliance

CORS Configuration

The widget is configured with secure CORS headers: - Cross-origin requests allowed for widget embedding - Access-Control headers properly configured - 20-day preflight cache for performance

Privacy & Data Protection

GDPR Compliance: Built-in consent management
Data Security: All data transmitted securely
Local Storage: Minimal use of browser storage for consent tracking
Rate Limiting: Protection against spam and abuse (10 submissions/hour default)

Authentication & Access Control

Organization-based Access: Widget tied to organization slug
Public Feedback Boards: Only public boards accessible via widget
API Authentication: Secure endpoints for data submission