Evolve Chat Widget

Embeddable chat widget for the Evolve e-commerce platform. Allows customers to interact with an AI shopping assistant directly on your website.

Features

• Floating button or inline embed mode
• Product cards with images, prices, and quantities
• Shopping cart and wishlist integration
• Configurable branding and labels
• Automatic user name extraction from JWT
• Cross-origin support with shared cookies

Installation

Script Tag (easiest)

Add the widget script to your HTML:

<script src="https://chat.evolve-platform.com/widget.js"></script>
<script>
  EvolveChat.init({
    tenantId: 'evolve',
    mode: 'floating',
    position: { horizontal: 'right', vertical: 'bottom' },
  });
</script>

pnpm Package

pnpm install @evolve-packages/chat-widget

import { EvolveChatWidget } from '@evolve-platform/chat-widget';

function App() {
  return (
    <EvolveChatWidget
      tenantId="evolve"
      mode="floating"
      branding={{ primaryColor: '#f97316' }}
    />
  );
}

Configuration

Required Options

| Option | Type | Description | |--------|------|-------------| | tenantId | string | Tenant identifier for multi-tenant support |

Display Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | mode | 'floating' \| 'inline' | 'floating' | Display mode | | container | string | - | CSS selector for inline mode container | | position | WidgetPosition | See below | Position for floating mode | | zIndex | number | 9999 | z-index for floating widget |

Position Configuration

interface WidgetPosition {
  horizontal: 'left' | 'right';  // default: 'right'
  vertical: 'top' | 'bottom';    // default: 'bottom'
  offsetX?: number;              // default: 20
  offsetY?: number;              // default: 20
}

Branding Options

interface WidgetBranding {
  primaryColor?: string;      // Primary color (default: '#f97316')
  primaryTextColor?: string;  // Text on primary (default: '#ffffff')
  headerTitle?: string;       // Widget header title
  logoUrl?: string;           // Custom logo URL
  avatarUrl?: string;         // Avatar for assistant messages
}

Label Options

interface WidgetLabels {
  placeholder?: string;  // Input placeholder text
  greeting?: string;     // Greeting message (use {name} for user name)
  thinking?: string;     // "Thinking" indicator text
  close?: string;        // Close button label
}

Context Options

| Option | Type | Description | |--------|------|-------------| | apiBaseUrl | string | API base URL (default: current origin) | | cartId | string | Shopping cart ID for cart operations | | firstName | string | User's first name for personalized greeting | | modelId | string | AI model ID to use |

Callbacks

interface WidgetCallbacks {
  onOpen?: () => void;              // Called when widget opens
  onClose?: () => void;             // Called when widget closes
  onMessage?: (message: string) => void;  // Called when user sends message
  onError?: (error: Error) => void; // Called on error
}

Examples

Floating Widget (bottom-right)

EvolveChat.init({
  tenantId: 'evolve',
  mode: 'floating',
  position: {
    horizontal: 'right',
    vertical: 'bottom',
    offsetX: 20,
    offsetY: 20,
  },
  branding: {
    primaryColor: '#f97316',
  },
});

Floating Widget (bottom-left)

EvolveChat.init({
  tenantId: 'evolve',
  mode: 'floating',
  position: {
    horizontal: 'left',
    vertical: 'bottom',
  },
});

Inline Embed

<div id="chat-container" style="width: 400px; height: 600px;"></div>

<script>
  EvolveChat.init({
    tenantId: 'evolve',
    mode: 'inline',
    container: '#chat-container',
  });
</script>

With Cart Integration

EvolveChat.init({
  tenantId: 'evolve',
  mode: 'floating',
  cartId: 'abc123-cart-id',
  firstName: 'Jan',
});

Custom Branding

EvolveChat.init({
  tenantId: 'evolve',
  mode: 'floating',
  branding: {
    primaryColor: '#1e40af',
    primaryTextColor: '#ffffff',
    headerTitle: 'Shop Assistant',
  },
  labels: {
    placeholder: 'Stel je vraag...',
    greeting: 'Hoi {name}! Hoe kan ik je helpen?',
    thinking: 'Even denken...',
  },
});

Development

Build

pnpm run build

Outputs:

• dist/widget.js - UMD bundle (for script tag, includes React)
• dist/widget.css - Extracted styles
• dist/index.esm.js - ESM bundle (for pnpm, React as peer dep)
• dist/index.js - CJS bundle (for pnpm, React as peer dep)

Development Mode

pnpm run dev     # Watch mode with auto-rebuild
pnpm run serve   # Serve dist folder for testing

Type Check

pnpm run typecheck

Architecture

widget/
├── src/
│   ├── index.ts              # pnpm package entry
│   ├── init.ts               # Script tag entry (EvolveChat.init)
│   ├── components/
│   │   ├── ChatWidget.tsx    # Main wrapper
│   │   ├── FloatingButton.tsx
│   │   ├── ChatPanel.tsx
│   │   ├── WidgetChat.tsx    # Chat UI (no Next.js deps)
│   │   ├── WidgetProductCard.tsx
│   │   └── WidgetToolQuery.tsx
│   ├── context/
│   │   └── WidgetProvider.tsx
│   ├── styles/
│   │   └── widget.css
│   ├── types/
│   │   └── config.ts
│   └── utils/
│       ├── api.ts
│       └── graphql-product-mapper.ts
├── dist/                     # Build output
├── package.json
├── rollup.config.js
└── tsconfig.json

Cookie Requirements

For authentication to work across domains, cookies must be configured:

1. Cookie domain: .evolve-platform.com (with leading dot for subdomains)
2. SameSite: Lax or None (with Secure flag)
3. CORS: Server must send Access-Control-Allow-Credentials: true

Browser Support

• Chrome 80+
• Firefox 75+
• Safari 13+
• Edge 80+

License

MIT