# IssueBeam Feedback Widget

A framework-agnostic, vanilla JavaScript feedback widget that can be embedded in any website with a single script tag.

## Features

- ✨ **Zero Dependencies** - Pure vanilla JavaScript
- 📸 **Screenshot Capture** - Automatically captures page screenshots using html2canvas
- 🎨 **Drawing Tools** - Annotate screenshots with drawings
- 📱 **Mobile Responsive** - Works on all devices
- 🎯 **Easy Integration** - Just one script tag
- 🚀 **Lightweight** - ~15KB minified
- 🔒 **Privacy-First** - All data sent to your backend

## Installation

### Method 1: Data Attributes (Recommended for Static HTML)

Add this script tag to your HTML:

```html
<script
  defer
  data-app-id="YOUR_APP_ID"
  data-api-url="http://localhost:5000"
  data-position="bottom-right"
  src="http://localhost:5000/js/feedback.js"
></script>
```

### Method 2: Window Configuration (Recommended for Next.js/React)

Set configuration via `window.issuebeamConfig` before loading the script:

```jsx
// In Next.js layout.tsx or _app.tsx
import Script from 'next/script';

<Script id="issuebeam-config" strategy="beforeInteractive">
  {`
    window.issuebeamConfig = {
      appId: "YOUR_APP_ID",
      apiUrl: "http://localhost:5000",
      position: "left-middle",
      domain: "example.com",  // Optional
      userEmail: "user@example.com"  // Optional
    };
  `}
</Script>
<Script src="/js/feedback.js" strategy="lazyOnload" />
```

Or in vanilla JavaScript:

```html
<script>
  window.issuebeamConfig = {
    appId: "YOUR_APP_ID",
    apiUrl: "http://localhost:5000",
    position: "bottom-right",
    color: "#3b82f6",
    domain: "example.com",  // Optional
    userEmail: "user@example.com"  // Optional
  };
</script>
<script defer src="http://localhost:5000/js/feedback.js"></script>
```

### Configuration Options

| Attribute | Required | Default | Description |
|-----------|----------|---------|-------------|
| `data-app-id` | ✅ Yes | - | Your application ID for tracking feedback |
| `data-api-url` | ❌ No | Script origin | Backend API URL |
| `data-position` | ❌ No | `bottom-right` | Button position: `bottom-right`, `bottom-left`, `top-right`, `top-left` |
| `data-color` | ❌ No | `#ef4444` | Primary color for button and UI elements |
| `data-domain` | ❌ No | - | Domain name for tracking (sent as `DOMAIN` header) |
| `data-user-email` | ❌ No | - | User email for identifying feedback submitter (sent as `USER-EMAIL` header) |

### Examples

**Minimal Configuration:**
```html
<script defer data-app-id="abc-123" src="http://localhost:5000/js/feedback.js"></script>
```

**Custom Position:**
```html
<script
  defer
  data-app-id="abc-123"
  data-position="top-right"
  src="http://localhost:5000/js/feedback.js"
></script>
```

**Custom Color:**
```html
<script
  defer
  data-app-id="abc-123"
  data-color="#3b82f6"
  src="http://localhost:5000/js/feedback.js"
></script>
```

**Different API URL:**
```html
<script
  defer
  data-app-id="abc-123"
  data-api-url="https://api.yourdomain.com"
  src="http://localhost:5000/js/feedback.js"
></script>
```

**With User Email and Domain:**
```html
<script
  defer
  data-app-id="abc-123"
  data-domain="example.com"
  data-user-email="user@example.com"
  src="http://localhost:5000/js/feedback.js"
></script>
```

## How It Works

1. **Floating Button** - A feedback button appears on your page
2. **Click to Open** - Users click the button to open the feedback modal
3. **Auto Screenshot** - The page is automatically captured as a screenshot
4. **Annotate** - Users can draw on the screenshot to highlight issues
5. **Fill Form** - Users select feedback type and write description
6. **Submit** - Feedback is sent to your backend API

## API Endpoint

The widget sends feedback data to:

```
POST {apiUrl}/api/v1/feedbacks
```

### Request Headers

```
Content-Type: application/json
DOMAIN: example.com (optional, if data-domain is set)
USER-EMAIL: user@example.com (optional, if data-user-email is set)
```

### Payload Structure

```json
{
  "feedbackType": "bug|feature|other",
  "description": "User's feedback description",
  "image": "data:image/png;base64,...",
  "drawings": "{\"lines\":[...],\"width\":800,\"height\":600}",
  "current_url": "https://example.com/page",
  "material_ui_screensize": "desktop|tablet|mobile",
  "domain": "example.com",
  "user_email": "user@example.com",
  "meta": {
    "app_id": "YOUR_APP_ID"
  }
}
```

**Notes:**
- `domain` and `user_email` are sent both as headers (DOMAIN, USER-EMAIL) and in the payload body.
- `image` contains a composite screenshot with drawings already rendered on it (if user drew anything)
- `drawings` contains the raw drawing data (coordinates, paths) for reference/metadata purposes

## Browser Support

- ✅ Chrome/Edge (latest)
- ✅ Firefox (latest)
- ✅ Safari (latest)
- ✅ Mobile browsers

## Testing

A test page is included at `frontend/public/test-widget.html`.

To test locally:

1. Start your Next.js dev server:
   ```bash
   cd frontend
   npm run dev
   ```

2. Open in browser:
   ```
   http://localhost:3005/test-widget.html
   ```

3. Click the feedback button and test the functionality

## Development

### File Structure

```
frontend/public/
├── js/
│   └── feedback.js          # Main widget file
├── test-widget.html         # Test/demo page
└── WIDGET_README.md         # This file
```

### Customization

The widget is self-contained in a single file (`feedback.js`). You can:

- Modify styles by editing the `injectStyles()` function
- Change button SVG icon
- Adjust modal layout
- Customize form fields
- Add validation rules

### Dependencies

The widget dynamically loads:
- **html2canvas** (v1.4.1) - For screenshot capture (loaded from CDN on demand)

No other external dependencies required.

## Troubleshooting

### Feedback not submitting

1. Check browser console for errors
2. Verify `data-app-id` is set correctly
3. Ensure backend API is running and accessible
4. Check CORS settings on your backend

### Screenshot capture fails

1. Ensure page doesn't have CORS-restricted images
2. Check for CSP (Content Security Policy) restrictions
3. Try in a different browser

### Button not appearing

1. Check if script tag has `defer` attribute
2. Verify script URL is correct
3. Look for JavaScript errors in console
4. Ensure `data-app-id` is provided

## Production Deployment

### Serving the Widget

1. Build your Next.js app:
   ```bash
   npm run build
   ```

2. The widget will be available at:
   ```
   https://yourdomain.com/js/feedback.js
   ```

3. Update script tags on client sites to use production URL

### CDN Distribution (Optional)

For better performance, serve the widget from a CDN:

```html
<script
  defer
  data-app-id="abc-123"
  data-api-url="https://api.yourdomain.com"
  src="https://cdn.yourdomain.com/feedback.js"
></script>
```

## Security Considerations

- Widget sends data to your backend only
- Screenshots are base64 encoded
- No third-party tracking
- HTTPS recommended for production
- Validate and sanitize all inputs on backend

## License

© 2025 IssueBeam. All rights reserved.