bettercx-widget/readme.md

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

# BetterCX Widget

[![npm version](https://badge.fury.io/js/bettercx-widget.svg)](https://badge.fury.io/js/bettercx-widget)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

The BetterCX Widget is a production-ready, embeddable chat widget that provides AI-powered customer support capabilities. Built for modern web applications, it offers seamless integration across all major platforms and frameworks.

## ✨ Features

- **🤖 AI-Powered Support** - Intelligent responses powered by advanced AI
- **🎨 Brand Customization** - Match your website's design with custom themes
- **📱 Universal Compatibility** - Works with React, Vue, Angular, WordPress, Shopify, and more
- **🌙 Smart Theming** - Automatic light/dark mode detection
- **♿ Accessibility First** - WCAG compliant with keyboard navigation
- **📊 Analytics Ready** - Built-in event tracking for insights
- **🔒 Enterprise Security** - JWT authentication and origin validation
- **⚡ Performance Optimized** - Lightweight and fast loading

## 🚀 Quick Start

### React (Recommended)

```bash
npm install bettercx-widget
```

```tsx
import React from 'react';
import { BetterCXWidgetReact } from 'bettercx-widget/react';

function App() {
  return <BetterCXWidgetReact publicKey="pk_your_widget_key_here" theme="auto" />;
}
```

### HTML/JavaScript

```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" theme="auto"> </bettercx-widget>
```

## 📋 Prerequisites

- 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+)

## 🎯 Integration Methods

### React Integration

The React wrapper provides the most seamless integration experience:

```tsx
import { BetterCXWidgetReact } from 'bettercx-widget/react';

// Basic usage
<BetterCXWidgetReact publicKey="pk_your_key" />;

// Advanced usage with controls
const widgetRef = useRef<BetterCXWidgetReactRef>(null);

<BetterCXWidgetReact ref={widgetRef} publicKey="pk_your_key" theme="dark" position="left" onWidgetEvent={event => console.log(event)} />;
```

**Available Props:**

- `publicKey` (required) - Your widget public key
- `theme` - `'light' | 'dark' | 'auto'` (default: `'auto'`)
- `position` - `'left' | 'right'` (default: `'right'`)
- `onWidgetEvent` - Event handler function
- `className` - Custom CSS class
- `style` - Inline styles object

### Web Component

For vanilla JavaScript or other frameworks:

```html
<bettercx-widget public-key="pk_your_key" theme="auto" position="right"> </bettercx-widget>
```

### WordPress Integration

Add 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');
```

Usage: `[bettercx_widget public_key="pk_your_key"]`

### Shopify Integration

Add 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

### Themes

The widget automatically detects your website's theme, but you can override it:

```tsx
// Light theme
<BetterCXWidgetReact theme="light" />

// Dark theme
<BetterCXWidgetReact theme="dark" />

// Auto-detect (recommended)
<BetterCXWidgetReact theme="auto" />
```

### Custom Styling

Override CSS custom properties to match your brand:

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

### Positioning

Control widget placement:

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

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

## 📊 Event Tracking

Monitor widget interactions for analytics:

```tsx
<BetterCXWidgetReact
  publicKey="pk_your_key"
  onWidgetEvent={event => {
    switch (event.type) {
      case 'opened':
        // Track chat opened
        analytics.track('chat_opened');
        break;
      case 'message-sent':
        // Track message sent
        analytics.track('message_sent', { content: event.data.content });
        break;
      case 'message-received':
        // Track AI response
        analytics.track('ai_response_received');
        break;
    }
  }}
/>
```

## 🔧 Programmatic Control

Control the widget programmatically:

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

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

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

// Toggle chat
await widgetRef.current?.toggle();

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

## 🌍 Multi-language Support

The widget automatically detects your website's language and provides localized text:

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

## 📱 Responsive Design

The widget adapts to all screen sizes:

- **Desktop**: Floating widget in corner
- **Tablet**: Optimized for touch interaction
- **Mobile**: Full-screen chat experience

## 🔒 Security & Privacy

- **JWT Authentication** - Secure token-based authentication
- **Origin Validation** - Only works on authorized domains
- **No Data Storage** - No sensitive data stored locally
- **HTTPS Required** - Secure communication only
- **GDPR Compliant** - Privacy-first design

## 🚀 Performance

- **Lightweight** - Minimal bundle size impact
- **Lazy Loading** - Loads only when needed
- **Optimized Assets** - Compressed and minified
- **Fast Rendering** - 60fps animations

## 🛠️ Troubleshooting

### Widget Not Appearing

1. Verify your public key is correct
2. Check browser console for errors
3. Ensure your domain is authorized
4. Verify HTTPS is enabled

### Styling Issues

1. Check for CSS conflicts
2. Verify custom properties are set correctly
3. Test with different themes
4. Clear browser cache

### Integration Problems

1. Ensure proper script loading
2. Check for JavaScript errors
3. Verify framework compatibility
4. Test in different browsers

## 📚 Examples

Check out our comprehensive examples:

- [React Examples](./examples/) - Complete React applications
- [WordPress Plugin](./wordpress/) - WordPress integration
- [Live Demo](./example-usage.html) - Interactive demonstration

## 🤝 Support

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

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

**Ready to enhance your customer support?** Get started with the BetterCX Widget today! 🚀