bettercx-widget/FAQ.md

Professional AI-powered chat widget for BetterCX platform. Seamlessly integrate intelligent customer support into any website.

# Frequently Asked Questions

> Common questions and answers about the BetterCX Widget integration.

## 🚀 Getting Started

### Q: How do I get started with the BetterCX Widget?

A: Getting started is easy! Follow these steps:

1. **Get your widget key** from the BetterCX dashboard
2. **Install the widget** using npm or include the script
3. **Add the component** to your application
4. **Customize** the styling to match your brand

```tsx
// React
import { BetterCXWidgetReact } from 'bettercx-widget/react';
<BetterCXWidgetReact publicKey="pk_your_widget_key_here" />
```

```html
<!-- HTML -->
<script type="module" src="https://unpkg.com/bettercx-widget@latest/dist/bettercx-widget/bettercx-widget.esm.js"></script>
<bettercx-widget public-key="pk_your_widget_key_here"></bettercx-widget>
```

### Q: What do I need to integrate the widget?

A: You only need:

- A BetterCX account with an active widget key
- Your widget public key (starts with `pk_`)
- A modern web browser (Chrome 60+, Firefox 55+, Safari 12+, Edge 79+)

### Q: Is the widget free to use?

A: The widget itself is free to integrate. BetterCX offers various pricing plans for the AI-powered customer support features. Check the [BetterCX pricing page](https://bettercx.ai/pricing) for details.

## 🔧 Integration

### Q: Which frameworks are supported?

A: The BetterCX Widget works with:

- **React** (recommended with React wrapper)
- **Vue.js** (using web component)
- **Angular** (using web component)
- **Vanilla JavaScript** (using web component)
- **WordPress** (with shortcode)
- **Shopify** (with theme integration)
- **Webflow** (with custom embed)
- **Any HTML page** (using script tag)

### Q: Can I use the widget without React?

A: Yes! The widget is built as a web component, so it works with any framework or vanilla HTML. The React wrapper just provides a more convenient integration experience.

### Q: How do I integrate with WordPress?

A: Add this to your theme's `functions.php`:

```php
function bettercx_widget_shortcode($atts) {
    $atts = shortcode_atts(array(
        'public_key' => '',
        'theme' => 'auto'
    ), $atts);

    if (empty($atts['public_key'])) {
        return '<!-- BetterCX Widget: public_key required -->';
    }

    return sprintf(
        '<script type="module" src="https://unpkg.com/bettercx-widget@latest/dist/bettercx-widget/bettercx-widget.esm.js"></script>
        <bettercx-widget public-key="%s" theme="%s"></bettercx-widget>',
        esc_attr($atts['public_key']),
        esc_attr($atts['theme'])
    );
}
add_shortcode('bettercx_widget', 'bettercx_widget_shortcode');
```

Then use: `[bettercx_widget public_key="pk_your_key"]`

### Q: How do I integrate with Shopify?

A: Add this to your theme's `theme.liquid` before `</body>`:

```liquid
<script type="module" src="https://unpkg.com/bettercx-widget@latest/dist/bettercx-widget/bettercx-widget.esm.js"></script>
<bettercx-widget
  public-key="{{ settings.bettercx_public_key }}"
  theme="{{ settings.bettercx_theme | default: 'auto' }}">
</bettercx-widget>
```

## 🎨 Customization

### Q: Can I customize the widget's appearance?

A: Yes! You can customize the widget using:

- **CSS Custom Properties** for colors and styling
- **Custom CSS classes** for additional styling
- **Inline styles** for dynamic styling
- **Theme selection** (light, dark, auto)

```css
bettercx-widget {
  --bcx-primary: #your-brand-color;
  --bcx-background: #ffffff;
  --bcx-text: #333333;
}
```

### Q: How do I change the widget's position?

A: Use the `position` prop:

```tsx
// Right side (default)
<BetterCXWidgetReact position="right" />

// Left side
<BetterCXWidgetReact position="left" />
```

### Q: Can I control the widget programmatically?

A: Yes! Use refs to control the widget:

```tsx
const widgetRef = useRef<BetterCXWidgetReactRef>(null);

// Open chat
await widgetRef.current?.open();

// Close chat
await widgetRef.current?.close();

// Send message
await widgetRef.current?.sendMessage('Hello!');
```

## 🔒 Security

### Q: Is the widget secure?

A: Yes! The widget includes several security features:

- **JWT Authentication** with short-lived tokens
- **Origin Validation** - only works on authorized domains
- **HTTPS Only** - all communications are encrypted
- **No Local Storage** - no sensitive data stored locally
- **CORS Protection** - backend validates all requests

### Q: What data does the widget collect?

A: The widget collects minimal data:

- **Message content** (for AI responses)
- **Timestamp** (for message ordering)
- **Session ID** (for authentication)
- **No personal information** is stored

### Q: Is the widget GDPR compliant?

A: Yes! The widget is designed with privacy in mind:

- **No tracking** or analytics collection
- **Minimal data** collection
- **User control** - users can close the widget anytime
- **Transparent** data handling

## 📱 Responsive Design

### Q: Does the widget work on mobile?

A: Yes! The widget is fully responsive:

- **Desktop**: Floating widget in corner
- **Tablet**: Optimized for touch interaction
- **Mobile**: Full-screen chat experience
- **Touch-friendly** controls and interactions

### Q: How does the widget behave on different screen sizes?

A: The widget automatically adapts:

- **≥1024px**: Floating widget in corner
- **768px-1023px**: Touch-optimized interface
- **<768px**: Full-screen mobile experience

## 🚀 Performance

### Q: Does the widget affect my website's performance?

A: The widget is optimized for performance:

- **Lightweight** - minimal bundle size impact
- **Lazy loading** - loads only when needed
- **Optimized assets** - compressed and minified
- **Fast rendering** - 60fps animations

### Q: How much does the widget increase my bundle size?

A: The widget adds approximately:

- **React wrapper**: ~15KB gzipped
- **Web component**: ~25KB gzipped
- **Total impact**: <30KB gzipped

## 🛠️ Troubleshooting

### Q: The widget is not appearing. What should I check?

A: Check these common issues:

1. **Verify your public key** is correct
2. **Check browser console** for errors
3. **Ensure your domain** is authorized in BetterCX dashboard
4. **Verify HTTPS** is enabled on your website
5. **Check for JavaScript errors** that might prevent loading

### Q: The widget appears but doesn't work. What's wrong?

A: Common issues include:

1. **Invalid public key** - check your BetterCX dashboard
2. **Network issues** - check your internet connection
3. **CORS errors** - ensure your domain is authorized
4. **JavaScript errors** - check browser console

### Q: The styling looks wrong. How do I fix it?

A: Try these solutions:

1. **Check for CSS conflicts** with your existing styles
2. **Verify custom properties** are set correctly
3. **Test with different themes** (light, dark, auto)
4. **Clear browser cache** and reload
5. **Check for CSS specificity** issues

### Q: I'm getting TypeScript errors. What should I do?

A: Ensure you have:

1. **Correct imports** from 'bettercx-widget/react'
2. **Proper types** for props and refs
3. **Compatible React version** (≥16.8.0)
4. **Updated TypeScript** definitions

## 📊 Analytics

### Q: Can I track widget interactions?

A: Yes! The widget emits events you can track:

```tsx
<BetterCXWidgetReact
  publicKey="pk_your_widget_key_here"
  onWidgetEvent={(event) => {
    // Track with your analytics
    analytics.track('widget_event', {
      type: event.type,
      timestamp: event.timestamp
    });
  }}
/>
```

### Q: What events can I track?

A: Available events:

- `opened` - Widget was opened
- `closed` - Widget was closed
- `message-sent` - User sent a message
- `message-received` - AI responded
- `error` - An error occurred
- `session-created` - Authentication session created

## 🌍 Multi-language

### Q: Does the widget support multiple languages?

A: Yes! The widget automatically detects your website's language:

- **English** (default)
- **Polish** (auto-detected)

Additional languages can be added based on demand.

### Q: How does language detection work?

A: The widget detects language using:

1. **HTML lang attribute** (`<html lang="pl">`)
2. **Meta tags** (`<meta name="language" content="pl">`)
3. **Content analysis** (Polish words/characters)
4. **Browser language** (fallback)

## 🤝 Support

### Q: Where can I get help?

A: We provide multiple support channels:

- **Documentation**: [Full API Reference](./API.md)
- **Examples**: [Integration Examples](./examples/)
- **Support Portal**: [BetterCX Support](https://support.bettercx.ai)
- **Email**: support@bettercx.ai

### Q: How quickly do you respond to support requests?

A: Our response times:

- **Critical issues**: Within 4 hours
- **General support**: Within 24 hours
- **Feature requests**: Within 48 hours

### Q: Do you offer custom integrations?

A: Yes! We offer custom integration services for enterprise customers. Contact us at enterprise@bettercx.ai for more information.

---

**Still have questions?** Contact our support team at support@bettercx.ai! 🚀