@flowengage/react-chatbot 1.0.0 → 1.0.2

package/README.md

@@ -5,41 +5,178 @@ Add live chat, AI assistant, and agent handoff to any site in minutes. All you n
 
 ---
 
-## Installation
+## Choose how to integrate
+
+| Approach | Best for | What you add |
+|----------|-----------|--------------|
+| **npm package** | React, Next.js, Vite, Remix, etc. | Install the package, wrap your app with `FlowEngageProvider`, render `FlowEngageWidget`. |
+| **CDN (script tag)** | Plain HTML, PHP, WordPress, Drupal, non-React SPAs | One `<script>` tag; styles are bundled into the embed — no separate CSS file. |
+
+You need a **Site ID** from the [FlowEngage dashboard](https://app.flowengage.com) (Integration Guide or site settings).
+
+---
+
+## A. npm package (React / Next.js / Vite)
+
+### Prerequisites
+
+- **React 18+** and **react-dom 18+** in your project (peer dependencies).
+- Node 18+ recommended for local development.
+
+### 1. Install
 
 ```bash
 npm install @flowengage/react-chatbot
+```
+
+```bash
 # or
 yarn add @flowengage/react-chatbot
+pnpm add @flowengage/react-chatbot
 ```
 
-> **Peer dependencies**: React 18+ and ReactDOM 18+ must already be installed in your project.
+Pin a version in production if you prefer reproducible builds:
 
----
+```bash
+npm install @flowengage/react-chatbot@^1.0.0
+```
+
+### 2. Import the stylesheet once
+
+The widget ships its own CSS. Import it at your app entry (or a layout file):
+
+```js
+import '@flowengage/react-chatbot/styles.css';
+```
 
-## Quick Start — React / Next.js / Vite
+### 3. Wrap your app and mount the widget
 
-### 1. Wrap your app with the provider
+`FlowEngageProvider` must wrap any component that uses `FlowEngageWidget` or `useFlowEngage`.
 
 ```jsx
-// app.jsx  (or _app.tsx in Next.js, main.jsx in Vite, etc.)
+// e.g. App.jsx, main.jsx, or a root layout wrapper
 import { FlowEngageProvider, FlowEngageWidget } from '@flowengage/react-chatbot';
 import '@flowengage/react-chatbot/styles.css';
 
 export default function App() {
   return (
     <FlowEngageProvider siteId="YOUR_SITE_ID">
-      {/* your existing app content */}
-      <YourApp />
-
-      {/* drop the widget anywhere inside the provider */}
+      <YourExistingApp />
       <FlowEngageWidget />
     </FlowEngageProvider>
   );
 }
 ```
 
-That's it. The widget will bootstrap itself, connect to FlowEngage's backend, load chat history, and enable live agent handoff — all automatically.
+### Next.js App Router
+
+- Put the provider + widget in a **Client Component** (file with `"use client"` at the top), or a client wrapper imported from `layout.tsx`.
+- Keep a single provider tree so chat state is shared.
+
+### Yarn / monorepo
+
+Ensure the package resolves once at app level so you do not mount duplicate providers.
+
+---
+
+## B. CDN / script tag (no React project required)
+
+The embed build includes React and injects styles automatically. You do **not** import `styles.css` when using the script.
+
+### B1. FlowEngage CDN (recommended)
+
+Use the hosted script (kept in sync with FlowEngage infrastructure):
+
+```html
+<script
+  src="https://cdn.flowengage.com/flowengage-embed.js"
+  data-site-id="YOUR_SITE_ID"
+  defer>
+</script>
+```
+
+Place this **before `</body>`** on every page where the widget should appear, or in your global theme template.
+
+### B2. npm registry CDN (pin a version)
+
+If you prefer to load the same artifact published to npm (useful for pinning or offline mirrors):
+
+```html
+<!-- Replace 1.0.0 with the version you want -->
+<script
+  src="https://cdn.jsdelivr.net/npm/@flowengage/react-chatbot@1.0.0/dist/flowengage-embed.js"
+  data-site-id="YOUR_SITE_ID"
+  defer>
+</script>
+```
+
+Equivalent path on unpkg:
+
+`https://unpkg.com/@flowengage/react-chatbot@1.0.0/dist/flowengage-embed.js`
+
+### Auto-init attributes (`data-*`)
+
+On the `<script>` tag:
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `data-site-id` | ✅ for auto-init | Your Site ID from the dashboard. |
+| `data-api-url` | ❌ | Override API base URL (advanced; usually omit). |
+| `data-widget-settings` | ❌ | JSON string of runtime widget overrides (theme, branding). Example: `'{"theme":{"primaryColor":"#2563EB"}}'` |
+
+### Manual initialization
+
+If you cannot use `data-site-id` on the script tag:
+
+```html
+<script src="https://cdn.flowengage.com/flowengage-embed.js" defer></script>
+<script>
+  window.addEventListener('load', function () {
+    window.FlowEngage.init({
+      siteId: 'YOUR_SITE_ID',
+      widgetSettings: {
+        theme: { primaryColor: '#2563EB', position: 'bottom-right' },
+        branding: { headerName: 'Support', chatButtonText: 'Chat' },
+      },
+    });
+  });
+</script>
+```
+
+### CDN API (`window.FlowEngage`)
+
+| Method | Description |
+|--------|-------------|
+| `FlowEngage.init({ siteId, widgetSettings?, apiBaseUrl? })` | Mounts the widget. Safe to call after `DOMContentLoaded`. |
+| `FlowEngage.destroy()` | Unmounts the widget and removes injected styles/container. Call before `init` again if you need to reconfigure. |
+
+To open/close the panel from custom UI inside a **React** app, use the npm package and `useFlowEngage()` (`openWidget`, `closeWidget`, etc.). The standalone embed exposes `init` / `destroy` only.
+
+---
+
+## Optional: customization (npm)
+
+Pass runtime overrides via `config` on the provider (merged with dashboard defaults):
+
+```jsx
+<FlowEngageProvider
+  siteId="YOUR_SITE_ID"
+  config={{
+    widgetSettings: {
+      theme: {
+        primaryColor: '#FF5733',
+        position: 'bottom-left',
+      },
+      branding: {
+        headerName: 'Cool Support Assistant',
+        chatButtonText: 'Talk to us',
+      },
+    },
+  }}
+>
+  <FlowEngageWidget />
+</FlowEngageProvider>
+```
 
 ---
 
@@ -50,11 +187,11 @@ That's it. The widget will bootstrap itself, connect to FlowEngage's backend, lo
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
 | `siteId` | `string` | ✅ | Your Site ID from the FlowEngage dashboard |
-| `language` | `string` | ❌ | ISO 639-1 language code (default: `"en"`) |
+| `config` | `object` | ❌ | `{ widgetSettings?: … }` merged with server config |
 
 ### `<FlowEngageWidget>`
 
-No props required. It reads all state from the nearest `FlowEngageProvider`.
+No props required. It reads state from the nearest `FlowEngageProvider`.
 
 ---
 
@@ -69,7 +206,7 @@ function MyCustomButton() {
   const { openWidget, isOpen, chatHistory } = useFlowEngage();
 
   return (
-    <button onClick={openWidget}>
+    <button type="button" onClick={() => openWidget({ notifyChatInitiated: true })}>
       Chat ({chatHistory.length} messages)
     </button>
   );
@@ -90,7 +227,6 @@ function MyCustomButton() {
 | `isLoading` | `boolean` | Waiting for AI response |
 | `isVoiceMode` | `boolean` | Voice mode active |
 | `isRateLimited` | `boolean` | Rate limit hit |
-| `language` | `string` | Current language |
 | `openWidget()` | `function` | Open the chat panel |
 | `closeWidget()` | `function` | Close the chat panel |
 | `toggleWidget()` | `function` | Toggle the panel |
@@ -100,64 +236,9 @@ function MyCustomButton() {
 
 ---
 
-## Script Tag / CDN (No Framework Required)
-
-For plain HTML sites or any non-React app, use the self-contained embed script:
-
-### Option A — Auto-init via `data` attribute (recommended)
-
-```html
-<script
-  src="https://cdn.flowengage.com/flowengage-embed.js"
-  data-site-id="YOUR_SITE_ID">
-</script>
-```
-
-### Option B — Manual init
-
-```html
-<script src="https://cdn.flowengage.com/flowengage-embed.js"></script>
-<script>
-  FlowEngage.init({ siteId: 'YOUR_SITE_ID' });
-</script>
-```
-
-### Option C — With language
-
-```html
-<script>
-  FlowEngage.init({ siteId: 'YOUR_SITE_ID', language: 'ar' });
-</script>
-```
-
-### Programmatic control
-
-```js
-// Remove the widget at any time
-FlowEngage.destroy();
-
-// Re-initialize
-FlowEngage.init({ siteId: 'YOUR_SITE_ID' });
-```
-
----
-
-## Multi-language Support
-
-The widget UI and AI responses can be localized. Pass a language code to the provider or the embed script:
-
-```jsx
-<FlowEngageProvider siteId="YOUR_SITE_ID" language="fr">
-```
-
-Supported languages depend on your FlowEngage tenant configuration.
-
----
-
 ## SPA Route Tracking
 
-The widget automatically tracks page views and session duration.  
-For client-side routing (React Router, Next.js App Router, etc.), notify the tracker on route changes:
+For client-side routing (React Router, Next.js App Router, etc.):
 
 ```jsx
 import { useFlowEngage } from '@flowengage/react-chatbot';
@@ -190,14 +271,14 @@ Your App
           └── Track: Socket.IO events            → visitor session, page views
 ```
 
-All backend URLs are managed internally by FlowEngage. You never configure them.
+Backend URLs are resolved by FlowEngage; you normally do not set them unless using `apiBaseUrl` (advanced).
 
 ---
 
 ## Getting Your Site ID
 
 1. Log in to the [FlowEngage Dashboard](https://app.flowengage.com)
-2. Navigate to **Settings → Sites**
+2. Open **Integration Guide** or your site / workspace settings
 3. Copy the **Site ID** for your website
 
 ---