# VoiceCommit Widget Integration Guide (AI-Optimized)

## Overview
VoiceCommit widgets allow users to leave voice feedback on any website. This documentation is optimized for AI assistants helping developers integrate widgets.

## Quick Integration (Copy-Paste Ready)

### Basic Widget Integration
```html
<!-- VoiceCommit Widget - Replace WIDGET_ID with your actual widget ID -->
<link rel="stylesheet" href="https://app.voicecommit.com/api/widget/WIDGET_ID/widget.css">
<script src="https://app.voicecommit.com/api/widget/WIDGET_ID/widget.js" data-widget-id="WIDGET_ID"></script>
```

### Manual Initialization (Advanced)
```html
<link rel="stylesheet" href="https://app.voicecommit.com/api/widget/WIDGET_ID/widget.css">
<script>
const script = document.createElement('script');
script.src = 'https://app.voicecommit.com/api/widget/WIDGET_ID/widget.js';
script.setAttribute('data-manual', 'true');
script.onload = function() {
  if (window.VoiceCommitWidget) {
    window.VoiceCommitWidget.init({
      widgetId: 'WIDGET_ID'
    });
  }
};
document.head.appendChild(script);
</script>
```

## Widget Configuration Options

### Available Widget Types
1. **feedback-dashboard** - Collects feedback in VoiceCommit dashboard
2. **github-issue** - Creates GitHub issues from voice input
3. **github-pr** - Creates GitHub pull requests from voice input

### Widget Positioning
- `bottom-right` (default)
- `bottom-left` 
- `top-right`
- `top-left`

### Theme Options
- `auto` - Follows system theme (default)
- `light` - Light theme
- `dark` - Dark theme

## Framework-Specific Integration

### React/Next.js
```jsx
import { useEffect } from 'react';

export default function VoiceCommitWidget({ widgetId }) {
  useEffect(() => {
    // Add CSS
    const link = document.createElement('link');
    link.rel = 'stylesheet';
    link.href = `https://app.voicecommit.com/api/widget/${widgetId}/widget.css`;
    document.head.appendChild(link);

    // Add script
    const script = document.createElement('script');
    script.src = `https://app.voicecommit.com/api/widget/${widgetId}/widget.js`;
    script.setAttribute('data-widget-id', widgetId);
    document.head.appendChild(script);

    return () => {
      // Cleanup
      document.head.removeChild(link);
      document.head.removeChild(script);
    };
  }, [widgetId]);

  return null;
}
```

### Vue.js
```vue
<template>
  <div></div>
</template>

<script>
export default {
  props: ['widgetId'],
  mounted() {
    this.loadWidget();
  },
  methods: {
    loadWidget() {
      // Add CSS
      const link = document.createElement('link');
      link.rel = 'stylesheet';
      link.href = `https://app.voicecommit.com/api/widget/${this.widgetId}/widget.css`;
      document.head.appendChild(link);

      // Add script
      const script = document.createElement('script');
      script.src = `https://app.voicecommit.com/api/widget/${this.widgetId}/widget.js`;
      script.setAttribute('data-widget-id', this.widgetId);
      document.head.appendChild(script);
    }
  }
}
</script>
```

### Angular
```typescript
import { Component, Input, OnInit } from '@angular/core';

@Component({
  selector: 'app-voicecommit-widget',
  template: ''
})
export class VoiceCommitWidgetComponent implements OnInit {
  @Input() widgetId!: string;

  ngOnInit() {
    this.loadWidget();
  }

  private loadWidget() {
    // Add CSS
    const link = document.createElement('link');
    link.rel = 'stylesheet';
    link.href = `https://app.voicecommit.com/api/widget/${this.widgetId}/widget.css`;
    document.head.appendChild(link);

    // Add script
    const script = document.createElement('script');
    script.src = `https://app.voicecommit.com/api/widget/${this.widgetId}/widget.js`;
    script.setAttribute('data-widget-id', this.widgetId);
    document.head.appendChild(script);
  }
}
```

## Content Security Policy (CSP) Requirements

Add these directives to your CSP header:
```
script-src 'self' https://app.voicecommit.com;
style-src 'self' https://app.voicecommit.com;
connect-src 'self' https://app.voicecommit.com;
media-src 'self' blob:;
```

## Common Integration Issues & Solutions

### Issue: Widget not appearing
**Solutions:**
1. Verify widget ID is correct
2. Check domain is authorized for widget
3. Ensure both CSS and JS files are loading
4. Check browser console for errors

### Issue: Voice recording not working
**Solutions:**
1. Ensure HTTPS (required for microphone access)
2. Check microphone permissions
3. Test on supported browsers (Chrome, Firefox, Safari)

### Issue: CSP blocking resources
**Solution:** Add VoiceCommit domains to CSP whitelist (see CSP section above)

## Browser Support
- ✅ Chrome 60+
- ✅ Firefox 55+  
- ✅ Safari 11+
- ✅ Edge 79+
- ❌ Internet Explorer

## HTTPS Requirement
Voice recording requires HTTPS in production. HTTP only works on localhost for development.

## Rate Limiting
Default: 10 submissions per hour per domain. Configurable in widget settings.

## Widget Customization

### Custom Branding (Enterprise)
Contact support for custom branding options including:
- Custom colors
- Custom icons
- White-label options

## Testing Your Integration

### Development Checklist
- [ ] Widget appears on page
- [ ] Voice recording works (requires HTTPS)
- [ ] Feedback submission succeeds
- [ ] No console errors
- [ ] CSP allows all resources
- [ ] Rate limiting respected

### Production Checklist  
- [ ] Domain added to widget's allowed domains
- [ ] HTTPS certificate valid
- [ ] Widget positioned correctly
- [ ] Mobile responsive
- [ ] Performance impact acceptable

## API Endpoints (for advanced integration)

### Widget Configuration
```
GET https://app.voicecommit.com/api/widget/{widgetId}/config
```

### Submit Feedback
```
POST https://app.voicecommit.com/api/widget/{widgetId}/submit
Content-Type: application/json

{
  "transcript": "string",
  "domain": "string", 
  "user_agent": "string"
}
```

## Getting Started

1. **Create Widget**: Visit https://app.voicecommit.com/widgets/new
2. **Get Widget ID**: Copy from widget settings page  
3. **Add Domain**: Configure allowed domains
4. **Integrate Code**: Use examples above
5. **Test**: Verify voice recording and submission

## Support

- Documentation: https://app.voicecommit.com/docs
- Support: support@voicecommit.com
- GitHub: https://github.com/voicecommit/widgets (examples)

---

*This documentation is optimized for AI assistants. For human developers, visit the full documentation at https://app.voicecommit.com/docs*