npm package: @intentai/vanilla-widget
Description: Intent AI embeddable feedback widget with frustration detection and proactive help
Latest version: 1.0.0

# FeedbackIQ Widget

Embeddable JavaScript widget for collecting voice and text feedback from your users.

## Features

- **Voice Feedback**: Record audio feedback with one click
- **Text Feedback**: Traditional text feedback form
- **Session Tracking**: Automatic tracking of user sessions and navigation
- **Shadow DOM**: Isolated styles, won't conflict with your site
- **Lightweight**: < 50KB gzipped
- **Framework Agnostic**: Works with any JavaScript framework or vanilla sites

## Installation

### Option 1: CDN (Recommended)

Add this script tag to your HTML:

```html
<script src="https://cdn.feedbackiq.com/widget/v1/feedbackiq.js"></script>
<script>
  new FeedbackIQ({
    apiKey: 'YOUR_API_KEY',
  });
</script>
```

### Option 2: NPM

```bash
npm install @feedbackiq/widget
```

```javascript
import FeedbackIQ from '@feedbackiq/widget';

new FeedbackIQ({
  apiKey: 'YOUR_API_KEY',
});
```

## Configuration

```javascript
new FeedbackIQ({
  // Required
  apiKey: 'YOUR_API_KEY', // Get this from your dashboard

  // Optional
  apiUrl: 'https://api.feedbackiq.com', // Custom API URL
  position: 'bottom-right', // Widget position: bottom-right, bottom-left, top-right, top-left
  theme: 'light', // Theme: light or dark
  allowVoice: true, // Enable voice feedback
  allowText: true, // Enable text feedback
  allowScreenshot: false, // Enable screenshot capture (coming soon)
  customMetadata: {
    // Add custom data to all feedback
    userId: 'user123',
    plan: 'pro',
  },
});
```

## Usage

Once initialized, the widget will appear as a floating button on your site. Users can click it to:

1. **Submit Text Feedback**:
   - Select a category (Bug, Feature, Improvement, Praise, Other)
   - Type their feedback
   - Submit

2. **Submit Voice Feedback**:
   - Select a category
   - Click the microphone button to start recording
   - Speak their feedback (up to 3 minutes)
   - Click again to stop
   - Submit

## Browser Support

- Chrome/Edge: Full support
- Firefox: Full support
- Safari: Full support
- Mobile browsers: Full support

Voice recording requires HTTPS (or localhost for development).

## Development

### Setup

```bash
pnpm install
```

### Development Server

```bash
pnpm dev
```

Open http://localhost:5173 to test the widget.

### Build

```bash
pnpm build
```

Output: `dist/feedbackiq.js`

## API

### Constructor

```typescript
new FeedbackIQ(config: FeedbackIQConfig)
```

### Config Interface

```typescript
interface FeedbackIQConfig {
  apiKey: string;
  apiUrl?: string;
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  theme?: 'light' | 'dark';
  allowVoice?: boolean;
  allowText?: boolean;
  allowScreenshot?: boolean;
  customMetadata?: Record<string, any>;
}
```

## Session Tracking

The widget automatically tracks:
- Current URL
- Navigation path (as users move through your site)
- Browser and device information
- Viewport size
- Console errors (if enabled)
- Custom metadata

This context helps you understand user feedback better.

## Privacy

- No personally identifiable information is collected by default
- Audio recordings are stored securely on S3
- Users can submit feedback anonymously
- GDPR compliant

## Examples

### React

```jsx
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    new window.FeedbackIQ({
      apiKey: 'YOUR_API_KEY',
    });
  }, []);

  return <div>Your app</div>;
}
```

### Vue

```vue
<script>
export default {
  mounted() {
    new window.FeedbackIQ({
      apiKey: 'YOUR_API_KEY',
    });
  },
};
</script>
```

### Next.js

```jsx
// pages/_app.js
import { useEffect } from 'react';

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    if (typeof window !== 'undefined') {
      new window.FeedbackIQ({
        apiKey: process.env.NEXT_PUBLIC_FEEDBACKIQ_API_KEY,
      });
    }
  }, []);

  return <Component {...pageProps} />;
}
```

### HTML

```html
<!DOCTYPE html>
<html>
  <head>
    <title>My Site</title>
  </head>
  <body>
    <h1>Welcome</h1>

    <script src="https://cdn.feedbackiq.com/widget/v1/feedbackiq.js"></script>
    <script>
      new FeedbackIQ({
        apiKey: 'YOUR_API_KEY',
        position: 'bottom-left',
        customMetadata: {
          page: 'homepage',
        },
      });
    </script>
  </body>
</html>
```

## Troubleshooting

### Widget doesn't appear
- Check that your API key is correct
- Check browser console for errors
- Verify the script is loading

### Voice recording doesn't work
- Ensure you're on HTTPS (or localhost)
- Check microphone permissions
- Try a different browser

### Feedback not showing in dashboard
- Verify API key matches your product
- Check network tab for failed requests
- Ensure API is reachable from your domain

## Support

- Documentation: https://docs.feedbackiq.com
- Email: support@feedbackiq.com
- GitHub: https://github.com/feedbackiq/widget

## License

MIT