@wabbit-dashboard/embed

Wabbit Embed SDK - Unified widget library for embedding chat, forms, and email capture functionality into customer websites.

Installation

CDN (Recommended for Production)

<script src="https://unpkg.com/@wabbit-dashboard/embed@1/dist/wabbit-embed.umd.min.js"></script>

For local development:

<script src="http://localhost:3000/sdk/wabbit-embed.umd.js"></script>

Note: For local development, run make dev from the project root. The SDK will be automatically built and served at /sdk/wabbit-embed.umd.js.

NPM

npm install @wabbit-dashboard/embed

import { Wabbit } from '@wabbit-dashboard/embed';

Quick Start

📖 New to Wabbit? Check out the Getting Started Guide to integrate in 5 minutes.

Using CDN

Production (deployed website):

<script src="https://unpkg.com/@wabbit-dashboard/embed@1/dist/wabbit-embed.umd.min.js"></script>
<script>
  Wabbit.init({
    apiKey: 'pk_live_xxx',
    apiUrl: 'https://platform.insourcedata.ai',
    wsUrl: 'wss://chat.insourcedata.ai/ws/chat',
    chat: {
      enabled: true,
      collectionId: 'abc123',
      position: 'bottom-right'
    }
  });
</script>

Note: The apiUrl and wsUrl are required when your website runs on localhost but connects to production services. For fully deployed production websites, these can be omitted as the SDK auto-detects the correct URLs.

Local Development (local services):

<script src="http://localhost:3000/sdk/wabbit-embed.umd.js"></script>
<script>
  Wabbit.init({
    apiKey: 'pk_live_xxx',
    apiUrl: 'http://localhost:3000',
    chat: {
      enabled: true,
      collectionId: 'abc123',
      position: 'bottom-right'
    }
  });
</script>

Configuration

Chat Widget

Wabbit.init({
  apiKey: 'pk_live_xxx',
  chat: {
    enabled: true,
    collectionId: 'abc123',
    position: 'bottom-right',      // 'bottom-right' | 'bottom-left'
    triggerType: 'button',         // 'button' | 'auto' | 'scroll'
    triggerDelay: 5000,            // ms before auto-open
    theme: 'auto',                 // 'auto' | 'light' | 'dark'
    primaryColor: '#6366f1',
    welcomeMessage: 'Hi! How can I help?',
    placeholder: 'Type your message...'
  }
});

Form Widget

Wabbit.init({
  apiKey: 'pk_live_xxx',
  forms: {
    enabled: true,
    containerId: 'feedback-form',  // DOM element ID
    formId: 'form_xxx',
    theme: 'auto',
    onSubmit: (data) => {
      console.log('Form submitted:', data);
    },
    onError: (error) => {
      console.error('Form error:', error);
    }
  }
});

Email Capture

Wabbit.init({
  apiKey: 'pk_live_xxx',
  emailCapture: {
    enabled: true,
    triggerAfterMessages: 3,
    title: 'Stay in touch',
    description: 'Get notified about updates',
    fields: ['email'],             // 'email' | 'name' | 'company'
    onCapture: (data) => {
      console.log('Email captured:', data);
    }
  }
});

Session Persistence

Control whether chat sessions persist across browser sessions:

Wabbit.init({
  apiKey: 'pk_live_xxx',
  persistSession: true,  // Default: sessions persist (uses localStorage)
  chat: {
    enabled: true,
    collectionId: 'abc123'
  }
});

Options:

• persistSession: true (default) - Sessions persist across browser close/reopen using localStorage. Users can continue conversations after reopening the browser.
• persistSession: false - Sessions are cleared when browser closes using sessionStorage. Users start fresh each browser session, but conversations persist during page refreshes.

Use Cases:

• Persistent (true): Customer support, ongoing consultations, learning platforms
• Ephemeral (false): Sensitive data, temporary assistance, demo sites

Technical Details:

• true: Session ID stored in localStorage, survives browser restart
• false: Session ID stored in sessionStorage, cleared on browser close but survives page refresh
• Message history fetched from server on reconnect (not stored locally)

Testing

Option 1: Copy Embed Code from Dashboard (Recommended)

1. Start all services:

   make dev

2. Build the SDK (required for local development):

   cd packages/embed
   bun run build

3. Get embed code from Dashboard:

   • Open Dashboard: http://localhost:3000
   • Navigate to Collections → Select a collection → Click "Embed Chat" button
   • Or navigate to Forms → Select a form → Click "Embed" button
   • Copy the embed code from the modal

4. Paste into your HTML:

   • Create a test HTML file
   • Paste the copied embed code
   • Replace YOUR_API_KEY with your actual API key
   • Open the HTML file in a browser

Option 2: Use Example Files

1. Configure settings: Edit examples/config.js:

   window.WABBIT_CONFIG = {
     "apiKey": "pk_live_your_actual_api_key",
     "apiUrl": "http://localhost:3000",
     "collectionId": "your-collection-id",
     "formId": "your-form-id"
   };

2. Build the SDK:

   cd packages/embed
   bun run build

3. Start a local server:

   cd packages/embed
   python3 -m http.server 8080
   # or
   npx http-server -p 8080

4. Open example files:

   • Complete example (recommended): http://localhost:8080/examples/test-complete.html
   • Chat only: http://localhost:8080/examples/test-chat.html
   • Form only: http://localhost:8080/examples/test-form.html
   • Email capture: http://localhost:8080/examples/test-email-capture.html

See examples/README.md for more details.

Project Structure

packages/embed/
├── src/                          # Source code
│   ├── index.ts                  # Main entry point
│   ├── core/                     # Core SDK functionality
│   │   ├── wabbit.ts            # Main Wabbit class
│   │   ├── config.ts            # Configuration management
│   │   ├── api.ts               # API client
│   │   ├── types.ts             # TypeScript type definitions
│   │   └── events.ts            # Event emitter
│   ├── chat/                     # Chat widget
│   │   ├── ChatWidget.ts        # Main chat widget class
│   │   ├── ChatBubble.ts        # Floating chat bubble
│   │   ├── ChatPanel.ts         # Chat panel UI
│   │   ├── WebSocketClient.ts   # WebSocket connection
│   │   └── styles.ts            # Chat styles
│   ├── forms/                    # Form widget
│   │   ├── FormWidget.ts        # Main form widget class
│   │   ├── FormRenderer.ts     # Form HTML renderer
│   │   └── FormStyles.ts        # Form styles
│   ├── email-capture/            # Email capture widget
│   │   ├── EmailCaptureWidget.ts # Main email capture class
│   │   ├── EmailCaptureModal.ts  # Email capture modal UI
│   │   └── EmailCaptureStyles.ts # Email capture styles
│   └── utils/                    # Utility functions
│       ├── dom.ts               # DOM utilities
│       ├── storage.ts           # localStorage wrapper
│       └── theme.ts             # Theme detection
├── dist/                         # Build output (generated)
│   ├── wabbit-embed.umd.js       # UMD bundle (for CDN)
│   ├── wabbit-embed.esm.js      # ES module bundle
│   ├── wabbit-embed.cjs.js      # CommonJS bundle
│   └── wabbit-embed.d.ts        # TypeScript definitions
├── examples/                     # Example implementations
│   ├── test-complete.html       # Complete integration example
│   ├── test-chat.html           # Chat widget example
│   ├── test-form.html           # Form widget example
│   ├── test-email-capture.html # Email capture example
│   ├── config.js                # Example configuration
│   └── README.md                # Examples documentation
├── tests/                        # Test files
├── package.json                  # Package configuration
├── tsconfig.json                 # TypeScript configuration
├── rollup.config.js              # Rollup build configuration
└── README.md                     # This file

Development

# Install dependencies
bun install

# Build SDK (required before testing)
bun run build

# Development mode (watch)
bun run dev

# Production build
bun run build:prod

# Lint
bun run lint

API Reference

Wabbit.init(config)

Initialize the Wabbit SDK.

Parameters:

• config.apiKey (string, required): Your Wabbit API key
• config.apiUrl (string, optional): API base URL (default: auto-detected)
• config.persistSession (boolean, optional): Whether to persist sessions across browser sessions (default: true)
• config.chat (ChatConfig, optional): Chat widget configuration
• config.forms (FormConfig, optional): Form widget configuration
• config.emailCapture (EmailCaptureConfig, optional): Email capture configuration

Example:

Wabbit.init({
  apiKey: 'pk_live_xxx',
  persistSession: true, // Optional: default is true
  chat: { enabled: true, collectionId: 'abc123' }
});

Wabbit.getInstance()

Get the current Wabbit instance.

Returns: Wabbit instance or null if not initialized

Wabbit.destroy()

Destroy the SDK instance and cleanup all widgets.

Configuration Types

ChatConfig

{
  enabled: boolean;                  // Required
  collectionId: string;              // Required
  position?: 'bottom-right' | 'bottom-left';
  triggerType?: 'button' | 'auto' | 'scroll';
  triggerDelay?: number;
  theme?: 'auto' | 'light' | 'dark';
  primaryColor?: string;
  welcomeMessage?: string;
  placeholder?: string;
}

FormConfig

{
  enabled: boolean;                  // Required
  formId: string;                    // Required
  containerId?: string;
  theme?: 'auto' | 'light' | 'dark';
  primaryColor?: string;
  onSubmit?: (data, submissionId?) => void;
  onError?: (error) => void;
  onLoad?: () => void;
}

EmailCaptureConfig

{
  enabled: boolean;                  // Required
  triggerAfterMessages?: number;     // Default: 3
  title?: string;
  description?: string;
  fields?: ('email' | 'name' | 'company')[];
  onCapture?: (data) => void;
}

Programmatic Control

const wabbit = Wabbit.getInstance();

// Chat controls
wabbit.chat.open();
wabbit.chat.close();
wabbit.chat.sendMessage('Hello');

Troubleshooting

Chat widget not appearing

• Check browser console for errors
• Verify chat.enabled is true
• Verify API key and collection ID are correct
• Ensure WebSocket URL is accessible

Form not loading

• Check API URL is correct (should be dashboard service URL, e.g., http://localhost:3000)
• Verify form ID exists
• Check browser console for errors
• Verify CORS is configured correctly

Email capture not triggering

• Ensure emailCapture.enabled is true
• Check that chat widget is enabled (email capture requires chat)
• Verify triggerAfterMessages value
• Check localStorage for wabbit_email_captured or wabbit_email_capture_dismissed flags

Local development issues

• SDK not loading: Make sure you've run bun run build in packages/embed directory
• File not found: Ensure dist/wabbit-embed.umd.js exists after building
• CORS errors: Check that all services are running (make dev)

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Documentation

• 📖 Getting Started Guide - Integrate in 5 minutes
• 🌐 Example Code - Integration examples (React, Vue, Vanilla JS)
• 📚 API Reference - Coming soon
• 🔧 Troubleshooting Guide - Coming soon

Related Resources

• Browser Compatibility - Browser compatibility test results
• Testing Guide - Testing guide