@onionshack/ocpb-chatbox-sdk-prod

v0.2.3

Published

a month ago

A lightweight, embeddable chat widget powered by React 19, Vite, and Tailwind CSS. Easily integrate a floating chatbot into any website with Firebase backend support and WebSocket real-time messaging.

Downloads

0High
0Medium
0Low

kasempakdeepong.piyapoj

OCPB Chatbot Widget SDK

Features

🎯 Floating Widget: Unobtrusive bottom-right positioning with expandable interface
💬 Rich Messaging: Markdown support (GFM) for formatted bot and user messages
🔄 Real-time: WebSocket integration for instant message delivery
🎨 Customizable: Configure title, placeholder, suggestions, and styling
📦 Multiple Integration Options: Use as React component or vanilla JavaScript
🔥 Firebase Ready: Built-in Firebase authentication and storage support
⚡ Lightweight: Optimized bundle size with tree-shaking support

Quick Start

Local Development

Clone and install dependencies:
```
npm install
```
Start the development server:
```
npm run dev
```
Open your browser: Navigate to http://localhost:5173 to see the demo

Usage

Option 1: Vanilla JavaScript (HTML)

Perfect for integrating into existing websites, WordPress, static HTML pages, or any non-React application.

Step 1: Include the SDK

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Website</title>
</head>
<body>
    <!-- Your website content -->
    <h1>Welcome to my website</h1>

    <!-- Load the chat widget SDK -->
    <script src="https://cdn.example.com/chat-widget-sdk.umd.js"></script>

    <!-- Initialize the widget -->
    <script>
        ChatWidgetSDK.initChatWidget({
            firebaseConfig: {
                apiKey: "YOUR_API_KEY",
                authDomain: "YOUR_AUTH_DOMAIN",
                projectId: "YOUR_PROJECT_ID",
                storageBucket: "YOUR_STORAGE_BUCKET",
                messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
                appId: "YOUR_APP_ID"
            },
            title: 'Customer Support',
            placeholder: 'Type your message...',
            apiUrl: "https://your-api-endpoint.com"
        });
    </script>
</body>
</html>

Step 2: Programmatic Control (Optional)

// Initialize and store the widget instance
const widget = ChatWidgetSDK.initChatWidget({
    firebaseConfig: { /* ... */ },
    title: 'Help Center'
});

// Later, remove the widget if needed
widget.unmount();

Option 2: React Component

Ideal for React applications or Next.js projects.

Step 1: Install from GitHub Packages

First, configure npm to use GitHub Packages. Create or edit .npmrc in your project root:

@onionshack:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

Note: Generate a GitHub Personal Access Token with read:packages scope at https://github.com/settings/tokens

Then install the package:

npm install @onionshack/ocpb-chatbox-sdk

Step 2: Import and Use in Your React App

import ChatWidget from '@onionshack/ocpb-chatbox-sdk';
import '@onionshack/ocpb-chatbox-sdk/dist/style.css'; // Import styles

export default function App() {
  return (
    <div>
      {/* Your app content */}
      <h1>My React App</h1>

      {/* Chat widget will appear as a floating button */}
      <ChatWidget
        title="Support Chat"
        placeholder="Ask us anything..."
        firebaseConfig={{
          apiKey: process.env.REACT_APP_FIREBASE_API_KEY,
          authDomain: process.env.REACT_APP_FIREBASE_AUTH_DOMAIN,
          projectId: process.env.REACT_APP_FIREBASE_PROJECT_ID,
          storageBucket: process.env.REACT_APP_FIREBASE_STORAGE_BUCKET,
          messagingSenderId: process.env.REACT_APP_FIREBASE_MESSAGING_SENDER_ID,
          appId: process.env.REACT_APP_FIREBASE_APP_ID
        }}
        apiUrl="https://your-api-endpoint.com"
      />
    </div>
  );
}

Configuration

Required Parameters

| Parameter | Type | Description | |-----------|------|-------------| | firebaseConfig | object | Firebase configuration object (required) | | firebaseConfig.apiKey | string | Firebase API key | | firebaseConfig.authDomain | string | Firebase auth domain | | firebaseConfig.projectId | string | Firebase project ID | | firebaseConfig.storageBucket | string | Firebase storage bucket | | firebaseConfig.messagingSenderId | string | Firebase messaging sender ID | | firebaseConfig.appId | string | Firebase app ID |

Optional Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | title | string | 'Chat' | Chat widget header title | | placeholder | string | 'Type your message…' | Input field placeholder text | | apiUrl | string | 'http://localhost:3000' | REST API and WebSocket endpoint for chat backend | | fullScreen | boolean | false | Enable full-screen mode (no floating button, always open) | | containerId | string | 'chat-widget-root' | DOM element ID to mount into (JS only) |

Configuration Examples

ChatWidgetSDK.initChatWidget({
    firebaseConfig: {
        apiKey: "AIza...",
        authDomain: "myapp.firebaseapp.com",
        projectId: "myapp",
        storageBucket: "myapp.appspot.com",
        messagingSenderId: "123456",
        appId: "1:123456:web:abc123"
    },
    title: 'Customer Support',
    placeholder: 'How can we help you?',
    apiUrl: 'https://api.myapp.com',
    containerId: 'custom-chat-container',
    fullScreen: true  // No floating button, always visible
});

Installation

For Contributors / Development

# Clone the repository
git clone https://github.com/onionshack/ocpb-chatbot-widget-next.git
cd ocpb-chatbot-widget-next

# Install dependencies
npm install

# Start development server
npm run dev