@robylon/web-react-sdk 1.1.35-staging.3 → 1.1.35

package/README.md

@@ -6,20 +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
 
@@ -121,11 +118,150 @@ 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.
 
-There are several ways to add the Robylon chatbot to your website or no-code platform, depending on your needs:
+### Quick Embed (Easiest Method)
+
+This is the simplest way to add the Robylon chatbot to any website with a single line of code. Just copy and paste this script tag into your HTML:
+
+```
+<script>(function(k){window.R=window.R||function(){(window.R.q=window.R.q||[]).push(arguments)};window.R=new Proxy(window.R,{get:(t,p)=>p==="q"?t.q:(...a)=>t(p,...a)});function l(){var s=document.createElement("script");s.src="https://cdn.robylon.ai/sdk/latest/chatbot.js";s.onload=()=>k&&window.RobylonChatbot.create({api_key:k});document.body.appendChild(s)}document.readyState==="complete"?l():window.addEventListener("load",l)})("YOUR_API_KEY_HERE");</script>
+```
+
+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:
+
+```
+<script>(function(k,p,side,bottom){window.R=window.R||function(){(window.R.q=window.R.q||[]).push(arguments)};window.R=new Proxy(window.R,{get:(t,p)=>p==="q"?t.q:(...a)=>t(p,...a)});function l(){var s=document.createElement("script");s.src="https://cdn.robylon.ai/sdk/latest/chatbot.js";s.onload=()=>k&&window.RobylonChatbot.create({api_key:k,position:p,sideSpacing:side,bottomSpacing:bottom});document.body.appendChild(s)}document.readyState==="complete"?l():window.addEventListener("load",l)})("YOUR_API_KEY_HERE","Left",30,25);</script>
+```
+
+Just replace:
+
+- `YOUR_API_KEY_HERE` with your actual API key
+- `"Left"` with `"Left"` or `"Right"` for button position
+- `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
+- Or anywhere in your HTML code if you're using a website builder
+
+There are several other ways to add the Robylon chatbot to your website or no-code platform, depending on your needs:
 
 ### Option 1: Quick Setup - Load with Page
 
@@ -379,19 +515,59 @@ 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          |
+| show_launcher | boolean  | Show the floating launcher button (default: true) | Optional          |
+
+### Position and Spacing Configuration
+
+You can control the position and spacing of the chatbot button either through the API configuration or directly in the SDK. If both are provided, the SDK configuration takes precedence.
+
+#### React Example:
+
+```jsx
+<Chatbot
+  api_key="YOUR_API_KEY"
+  position="Left"
+  sideSpacing={30}
+  bottomSpacing={25}
+/>
+```
+
+#### 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`):
 
-| 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          |
+```jsx
+<Chatbot api_key="YOUR_API_KEY" show_launcher={false} />
+```
+
+#### Plain JavaScript Example:
+
+```javascript
+RobylonChatbot.create({
+  api_key: "YOUR_API_KEY",
+  position: "Left",
+  sideSpacing: 30,
+  bottomSpacing: 25,
+});
+```
 
 ## Event Handling
 
@@ -405,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             | -                                        |
@@ -418,243 +595,5 @@ The SDK emits the following events that you can listen for in both React and pla
 | `FILE_UPLOAD_STARTED`        | A file upload has started                       | `{ fileName: string, fileSize: number }` |
 | `FILE_UPLOAD_COMPLETED`      | A file upload has completed                     | `{ fileName: string, fileUrl: string }`  |
 | `FILE_UPLOAD_FAILED`         | A file upload has failed                        | `{ fileName: string, error: string }`    |
-| `CHATBOT_ERROR`              | An error occurred in the chatbot                | `{ code: string, message: string }`      |
-
-Events can be handled through the `onEvent` callback in both React and plain JavaScript implementations. Each event includes a `timestamp` field indicating when the event occurred.
-
-## Customization
-
-The Robylon SDK can be customized through the management console. Visit [app.robylon.ai](https://app.robylon.ai) to:
-
-- Customize the chatbot appearance
-- Set up chatbot behavior
-- Configure message flows
-- Manage AI capabilities
-
-## Troubleshooting
-
-If you encounter issues with the SDK:
-
-1. Ensure your API key is correct
-2. Check browser console for errors
-3. Verify that your domain is whitelisted in the Robylon console
-4. Make sure the script is loading correctly (no CORS or network issues)
-5. For vanilla JS implementation, ensure you're using `RobylonChatbot.create()` and not `new RobylonChatbot()`
-
-For further assistance, contact [support@robylon.com](mailto:support@robylon.com)
-
-## Platform-Specific Integration Guides
-
-### <a id="webflow-integration"></a>Webflow Integration
-
-Webflow is a popular no-code website builder that allows custom code injection. Here's how to add the Robylon chatbot to your Webflow site:
-
-1. Log in to your Webflow account and open your project
-2. Go to **Project Settings** (gear icon) in the left sidebar
-3. Click on **Custom Code** tab
-4. In the **Head Code** section, paste the following code:
-
-```html
-<script
-  src="https://cdn.robylon.ai/sdk/latest/robylon-chatbot.js"
-  defer
-></script>
-<script>
-  document.addEventListener("DOMContentLoaded", function () {
-    RobylonChatbot.create({
-      api_key: "YOUR_API_KEY", // Replace with your actual API key
-    });
-  });
-</script>
-```
-
-5. Click **Save Changes** at the bottom of the page
-6. Publish your site to apply the changes
-
-![Webflow Custom Code](https://cdn.robylon.ai/docs/webflow-integration.png)
-
-### <a id="wix-integration"></a>Wix Integration
-
-To add the Robylon chatbot to your Wix website:
-
-1. Log in to your Wix account and open your site in the Editor
-2. Click on the **+ Add** button on the left sidebar
-3. Search for and select **Dev Tools** > **Custom Code**
-4. Click **Add to Site**
-5. In the popup, select **Head** as the placement
-6. Paste the following code:
-
-```html
-<script
-  src="https://cdn.robylon.ai/sdk/latest/robylon-chatbot.js"
-  defer
-></script>
-<script>
-  document.addEventListener("DOMContentLoaded", function () {
-    RobylonChatbot.create({
-      api_key: "YOUR_API_KEY", // Replace with your actual API key
-    });
-  });
-</script>
-```
-
-7. Click **Apply** and then **Save**
-8. Publish your site to apply the changes
-
-### <a id="shopify-integration"></a>Shopify Integration
-
-To add the Robylon chatbot to your Shopify store:
-
-1. Log in to your Shopify admin dashboard
-2. Go to **Online Store** > **Themes**
-3. Find your current theme and click **Actions** > **Edit code**
-4. In the left sidebar, under the **Layout** section, click on `theme.liquid`
-5. Find the closing `</head>` tag
-6. Just before the `</head>` tag, paste the following code:
-
-```html
-<script
-  src="https://cdn.robylon.ai/sdk/latest/robylon-chatbot.js"
-  defer
-></script>
-<script>
-  document.addEventListener("DOMContentLoaded", function() {
-    RobylonChatbot.create({
-      api_key: "YOUR_API_KEY", // Replace with your actual API key
-      user_profile: {% if customer %}
-        {
-          name: {{ customer.name | json }},
-          email: {{ customer.email | json }},
-          id: {{ customer.id | json }}
-        }
-      {% else %}
-        {}
-      {% endif %}
-    });
-  });
-</script>
-```
-
-7. Click **Save**
-8. Your chatbot will now appear on all pages of your Shopify store
-
-### <a id="wordpress-integration"></a>WordPress Integration
-
-#### Option 1: Using a Header/Footer Plugin
-
-1. Install and activate a header/footer plugin like "Insert Headers and Footers" or "Header Footer Code Manager"
-2. Go to the plugin settings (usually under **Settings** or its own menu item)
-3. Add the following code to the **Header** section:
-
-```html
-<script
-  src="https://cdn.robylon.ai/sdk/latest/robylon-chatbot.js"
-  defer
-></script>
-<script>
-  document.addEventListener("DOMContentLoaded", function () {
-    RobylonChatbot.create({
-      api_key: "YOUR_API_KEY", // Replace with your actual API key
-    });
-  });
-</script>
-```
-
-4. Save the changes
-
-#### Option 2: Editing Theme Files
-
-If you're comfortable editing theme files:
-
-1. Go to **Appearance** > **Theme Editor**
-2. Select **Theme Header** (`header.php`)
-3. Find the closing `</head>` tag
-4. Just before the `</head>` tag, paste the following code:
-
-```php
-<script src="https://cdn.robylon.ai/sdk/latest/robylon-chatbot.js" defer></script>
-<script>
-  document.addEventListener("DOMContentLoaded", function() {
-    RobylonChatbot.create({
-      api_key: "YOUR_API_KEY", // Replace with your actual API key
-      <?php if (is_user_logged_in()): ?>
-      user_id: "<?php echo get_current_user_id(); ?>",
-      user_profile: {
-        name: "<?php echo esc_js(wp_get_current_user()->display_name); ?>",
-        email: "<?php echo esc_js(wp_get_current_user()->user_email); ?>"
-      }
-      <?php endif; ?>
-    });
-  });
-</script>
-```
-
-5. Save the changes
-
-> **Note:** For WordPress, if you're using a caching plugin, you may need to clear the cache after adding the code.
-
-## Using the SDK from CDN
-
-You can use the Robylon Chatbot SDK directly from our CDN without installing it via npm. This is useful for quick integration or when you're not using a build system.
-
-### Latest Version
-
-To use the latest version of the SDK, include the following script tag in your HTML:
-
-```html
-<script src="https://cdn.robylon.ai/sdk/latest/chatbot.js"></script>
-<script>
-  document.addEventListener("DOMContentLoaded", function () {
-    // Initialize the chatbot
-    const chatbot = RobylonChatbot.create({
-      api_key: "YOUR_API_KEY",
-      // Optional configuration
-      user_id: "user-123",
-      user_profile: {
-        name: "John Doe",
-        email: "john@example.com",
-      },
-      onEvent: function (event) {
-        console.log("Chatbot event:", event);
-      },
-    });
-
-    // Show the chatbot
-    chatbot.show();
-  });
-</script>
-```
-
-### Specific Version
-
-If you need to use a specific version of the SDK (recommended for production), use:
-
-```html
-<script src="https://cdn.robylon.ai/sdk/v1.1.30/chatbot.js"></script>
-```
-
-Replace `1.1.30` with the version you want to use.
-
-### Staging Version
-
-For testing with our staging environment:
-
-```html
-<script src="https://cdn.robylon.ai/sdk/staging/latest/chatbot.js"></script>
-```
-
-Or for a specific staging version:
-
-```html
-<script src="https://cdn.robylon.ai/sdk/staging/v1.1.30-staging.4/chatbot.js"></script>
-```
-
-### API Reference
-
-The CDN version provides the same API as the npm package:
 
-- `RobylonChatbot.create(config)`: Creates a new chatbot instance
-- `chatbot.show()`: Shows the chatbot
-- `chatbot.hide()`: Hides the chatbot
-- `chatbot.toggle()`: Toggles the chatbot visibility
-- `chatbot.destroy()`: Removes the chatbot from the DOM
+| `CHATBOT_ERROR`