JSPM – bettercx-widget@1.0.7

Package Exports

bettercx-widget
bettercx-widget/bettercx-widget
bettercx-widget/loader
bettercx-widget/react

Readme

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)

npm install bettercx-widget

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

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

HTML/JavaScript

<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:

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:

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

WordPress Integration

Add to your theme's functions.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>:

<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:

// 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:

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

Positioning

Control widget placement:

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

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

📊 Event Tracking

Monitor widget interactions for analytics:

<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:

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

Verify your public key is correct
Check browser console for errors
Ensure your domain is authorized
Verify HTTPS is enabled

Styling Issues

Check for CSS conflicts
Verify custom properties are set correctly
Test with different themes
Clear browser cache

Integration Problems

Ensure proper script loading
Check for JavaScript errors
Verify framework compatibility
Test in different browsers

📚 Examples

Check out our comprehensive examples:

React Examples - Complete React applications
WordPress Plugin - WordPress integration
Live Demo - Interactive demonstration

🤝 Support

Documentation: Full API Reference
Examples: Integration Examples
Support: BetterCX Support Portal
Email: office@appwave.dev

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

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

bettercx-widget