@robylon/web-react-sdk 1.1.41-staging.2 → 1.1.41-staging.20

package/README.md

@@ -6,21 +6,17 @@ The Robylon SDK provides an easy way to integrate a customizable chatbot into yo
 
 - [Installation](#installation)
 - [React SDK Usage](#react-sdk-usage)
+  - [Basic Implementation](#react-basic-implementation)
+  - [External Triggers](#react-external-triggers)
+  - [Event Handling](#react-event-handling)
 - [Plain JavaScript & No-Code Integration](#plain-javascript--no-code-integration)
   - [Quick Embed (Easiest Method)](#quick-embed-easiest-method)
+  - [ES5/Google Tag Manager](#es5google-tag-manager)
   - [Option 1: Quick Setup - Load with Page](#option-1-quick-setup---load-with-page)
   - [Option 2: Reliable Loading - After DOM is Ready](#option-2-reliable-loading---after-dom-is-ready)
   - [Option 3: User Context - Initialize After User Data](#option-3-user-context---initialize-after-user-data)
 - [Configuration Options](#configuration-options)
 - [Event Handling](#event-handling)
-- [Customization](#customization)
-- [Troubleshooting](#troubleshooting)
-- [Platform-Specific Integration Guides](#platform-specific-integration-guides)
-  - [Webflow](#webflow-integration)
-  - [Wix](#wix-integration)
-  - [Shopify](#shopify-integration)
-  - [WordPress](#wordpress-integration)
-- [Using the SDK from CDN](#using-the-sdk-from-cdn)
 
 ## Installation
 
@@ -122,6 +118,93 @@ The React component accepts an `onEvent` prop for handling chatbot events:
 
 The `Chatbot` component renders a floating button that opens a chat interface when clicked. It handles all the communication with the Robylon backend services.
 
+### React: External Triggers
+
+You can control the chatbot iframe from outside the component using a ref. This allows you to trigger open, close, or toggle actions from anywhere in your application:
+
+```jsx
+import React, { useRef, useState, useEffect } from "react";
+import { Chatbot, ChatbotRef } from "@robylon/web-react-sdk";
+
+function App() {
+  const chatbotRef = useRef < ChatbotRef > null;
+  const [isChatbotReady, setIsChatbotReady] = useState(false);
+
+  // Method 1: Check readiness state before calling methods
+  const showChatbot = () => {
+    if (chatbotRef.current?.isReady) {
+      chatbotRef.current.show();
+    } else {
+      console.log("Chatbot not ready yet");
+    }
+  };
+
+  const hideChatbot = () => {
+    chatbotRef.current?.hide();
+  };
+
+  const toggleChatbot = () => {
+    chatbotRef.current?.toggle();
+  };
+
+  // Method 2: Listen for ready event
+  const handleChatbotEvent = (event) => {
+    if (event.type === "CHATBOT_READY") {
+      setIsChatbotReady(true);
+    }
+  };
+
+  return (
+    <div className="App">
+      <h1>My Website</h1>
+
+      {/* External control buttons with readiness state */}
+      <button onClick={showChatbot} disabled={!isChatbotReady}>
+        Show Chatbot
+      </button>
+      <button onClick={hideChatbot}>Hide Chatbot</button>
+      <button onClick={toggleChatbot}>Toggle Chatbot</button>
+
+      <Chatbot
+        ref={chatbotRef}
+        api_key="YOUR_API_KEY"
+        user_id="optional-user-id"
+        onEvent={handleChatbotEvent}
+      />
+    </div>
+  );
+}
+```
+
+#### Available External Methods & Properties
+
+| Method/Property | Type     | Description                                            |
+| --------------- | -------- | ------------------------------------------------------ |
+| `show()`        | function | Opens the chatbot iframe if it's currently closed      |
+| `hide()`        | function | Closes the chatbot iframe if it's currently open       |
+| `toggle()`      | function | Toggles the chatbot iframe visibility                  |
+| `isReady`       | boolean  | Indicates if the chatbot is ready for external control |
+
+#### Event Handling with External Triggers
+
+External trigger methods emit the same events as internal triggers:
+
+- `CHATBOT_BUTTON_CLICKED` - When `show()` or `toggle()` opens the chatbot
+- `CHATBOT_CLOSED` - When `hide()` or `toggle()` closes the chatbot
+- `CHATBOT_READY` - When the chatbot is ready for external control (emitted once after initialization)
+
+This ensures consistent event handling regardless of how the chatbot is triggered.
+
+#### Readiness Handling
+
+The SDK provides multiple ways to handle chatbot readiness:
+
+1. **Check `isReady` property** - Synchronous check before calling methods
+2. **Listen for `CHATBOT_READY` event** - Event-based notification when ready
+3. **Guard clauses** - Methods safely handle early calls with console warnings
+
+This prevents race conditions and provides a smooth user experience.
+
 ## Plain JavaScript & No-Code Integration
 
 > **IMPORTANT:** You will need an API key from Robylon for any integration to work.
@@ -136,6 +219,18 @@ This is the simplest way to add the Robylon chatbot to any website with a single
 
 Just replace `YOUR_API_KEY_HERE` with your actual Robylon API key, and you're done! No additional code is needed.
 
+### ES5/Google Tag Manager
+
+#### ES5 Compatible Version
+
+For older browsers that don't support ES6 features, use this ES5 compatible version:
+
+```
+<script>(function(a){window.R=window.R||function(){(window.R.q=window.R.q||[]).push(Array.prototype.slice.call(arguments))};window.R.show=function(){window.R('show')};window.R.hide=function(){window.R('hide')};window.R.toggle=function(){window.R('toggle')};window.R.track=function(){window.R('track',Array.prototype.slice.call(arguments))};var o=function(){var s=document.createElement("script");s.src="https://cdn.robylon.ai/sdk/latest/chatbot.js";s.id="robylon-chatbot-sdk";s.onload=function(){if(a){window.RobylonChatbot.create({api_key:a})}};document.body.appendChild(s)};if(document.readyState==="complete"){o()}else{window.addEventListener("load",o)}})("YOUR_API_KEY_HERE");</script>
+```
+
+This version is compatible with Internet Explorer 11 and other older browsers that don't support ES6 features like arrow functions, `const`/`let`, and Proxy objects.
+
 #### Quick Embed with Custom Position and Spacing
 
 If you want to customize the position and spacing of the chatbot button, you can use this alternative version:
@@ -151,6 +246,16 @@ Just replace:
 - `30` with your desired side spacing in pixels
 - `25` with your desired bottom spacing in pixels
 
+##### ES5 Compatible Version with Custom Position and Spacing
+
+For older browsers, use this ES5 compatible version with custom positioning:
+
+```
+<script>(function(a,p,s,b){window.R=window.R||function(){(window.R.q=window.R.q||[]).push(Array.prototype.slice.call(arguments))};window.R.show=function(){window.R('show')};window.R.hide=function(){window.R('hide')};window.R.toggle=function(){window.R('toggle')};window.R.track=function(){window.R('track',Array.prototype.slice.call(arguments))};var o=function(){var s=document.createElement("script");s.src="https://cdn.robylon.ai/sdk/latest/chatbot.js";s.id="robylon-chatbot-sdk";s.onload=function(){if(a){window.RobylonChatbot.create({api_key:a,position:p,sideSpacing:s,bottomSpacing:b})}};document.body.appendChild(s)};if(document.readyState==="complete"){o()}else{window.addEventListener("load",o)}})("YOUR_API_KEY_HERE","Left",30,25);</script>
+```
+
+Replace the same parameters as above for the ES5 compatible version.
+
 #### Where to place the script:
 
 - At the end of your HTML `<body>` section for best performance
@@ -410,22 +515,25 @@ const chatbot = RobylonChatbot.create({
 // chatbot.hide();    // Hide the chatbot
 // chatbot.toggle();  // Toggle visibility
 // chatbot.destroy(); // Remove the chatbot from the page
+
+> **Note:** The plain JavaScript SDK provides direct instance methods for external control. The React SDK provides similar functionality through refs (see [React External Triggers](#react-external-triggers) section above).
 ```
 
 ## Configuration Options
 
-The SDK supports the following configuration options for both React and plain JavaScript implementations:
+The SDK supports the following configuration options for both React and plain JavaScript implementations. **Note:** The React SDK also supports external triggers via refs for programmatic control of the chatbot iframe.
 
-| Option        | Type     | Description                                     | Required/Optional |
-| ------------- | -------- | ----------------------------------------------- | ----------------- |
-| api_key       | string   | Your Robylon API key                            | Required          |
-| user_id       | string   | User identifier for conversation tracking       | Optional          |
-| user_token    | string   | Authentication token                            | Optional          |
-| user_profile  | object   | Additional user information                     | Optional          |
-| onEvent       | function | Event handler for chatbot interactions          | Optional          |
-| position      | string   | Position of the chatbot button ("Left"/"Right") | Optional          |
-| sideSpacing   | number   | Distance from the side of the screen (in px)    | Optional          |
-| bottomSpacing | number   | Distance from the bottom of the screen (in px)  | Optional          |
+| Option        | Type     | Description                                       | Required/Optional |
+| ------------- | -------- | ------------------------------------------------- | ----------------- |
+| api_key       | string   | Your Robylon API key                              | Required          |
+| user_id       | string   | User identifier for conversation tracking         | Optional          |
+| user_token    | string   | Authentication token                              | Optional          |
+| user_profile  | object   | Additional user information                       | Optional          |
+| onEvent       | function | Event handler for chatbot interactions            | Optional          |
+| position      | string   | Position of the chatbot button ("Left"/"Right")   | Optional          |
+| sideSpacing   | number   | Distance from the side of the screen (in px)      | Optional          |
+| bottomSpacing | number   | Distance from the bottom of the screen (in px)    | Optional          |
+| show_launcher | boolean  | Show the floating launcher button (default: true) | Optional          |
 
 ### Position and Spacing Configuration
 
@@ -442,6 +550,14 @@ You can control the position and spacing of the chatbot button either through th
 />
 ```
 
+#### React: Hide Floating Launcher Button
+
+To hide the floating launcher and manage visibility via external triggers or custom UI, set `show_launcher` to `false` (defaults to `true`):
+
+```jsx
+<Chatbot api_key="YOUR_API_KEY" show_launcher={false} />
+```
+
 #### Plain JavaScript Example:
 
 ```javascript
@@ -465,6 +581,7 @@ The SDK emits the following events that you can listen for in both React and pla
 | `CHATBOT_LOADED`             | The chatbot iframe has been loaded              | -                                        |
 | `CHATBOT_OPENED`             | The chatbot has been opened                     | -                                        |
 | `CHATBOT_CLOSED`             | The chatbot has been closed                     | -                                        |
+| `CHATBOT_READY`              | The chatbot is ready for external control       | -                                        |
 | `CHAT_INITIALIZED`           | The chat session has been initialized           | -                                        |
 | `CHAT_INITIALIZATION_FAILED` | The chat session failed to initialize           | `{ error: string }`                      |
 | `SESSION_REFRESHED`          | The chat session has been refreshed             | -                                        |