bsign-chatbot-widget

v0.0.4

Published

2 days ago

Гайд для підключення Bsign chatbot widget на звичайний сайт без фреймворків, через plain HTML.

0High
0Medium
0Low

vladyslav_rasik

Bsign Chatbot Widget

Гайд для підключення Bsign chatbot widget на звичайний сайт без фреймворків, через plain HTML.

CDN-файли

Для стандартного підключення використовуйте loader:

https://cdn.jsdelivr.net/npm/bsign-chatbot-widget@latest/dist/chatbot-widget-loader.iife.js

Loader ліниво підвантажує основний bundle віджета з тієї ж CDN-папки:

https://cdn.jsdelivr.net/npm/bsign-chatbot-widget@latest/dist/chatbot-widget.iife.js

Для production краще фіксувати версію замість @latest:

https://cdn.jsdelivr.net/npm/[email protected]/dist/chatbot-widget-loader.iife.js

Швидкий старт

Додайте скрипт перед закривальним тегом </body>:

<script
  src="https://cdn.jsdelivr.net/npm/bsign-chatbot-widget@latest/dist/chatbot-widget-loader.iife.js"
  data-title="Bsign"
  data-greeting="Hi! Tell us what you need and the Bsign team will help you with the next step."
></script>

За замовчуванням loader чекає першої взаємодії користувача (pointerdown, keydown, scroll, wheel або touchstart) і тільки після цього монтує віджет. Так сторінка швидше відкривається під час першого завантаження.

Loader сам створює mount-елемент, тому додавати окремий <div> не потрібно, якщо ви не хочете явно контролювати місце монтування.

Повний Plain HTML Приклад

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Website with Bsign Chatbot</title>
  </head>
  <body>
    <main>
      <h1>Your page</h1>
      <p>Website content...</p>
    </main>

    <script
      src="https://cdn.jsdelivr.net/npm/bsign-chatbot-widget@latest/dist/chatbot-widget-loader.iife.js"
      data-title="Bsign"
      data-initial-open="false"
    ></script>
  </body>
</html>

Кастомна Кнопка Відкриття

Якщо чат має відкриватися з вашої кнопки, додайте елемент з id і передайте цей id у data-open-trigger-id.

<button id="open-chatbot-btn" type="button">
  Chat with us
</button>

<script
  src="https://cdn.jsdelivr.net/npm/bsign-chatbot-widget@latest/dist/chatbot-widget-loader.iife.js"
  data-open-trigger-id="open-chatbot-btn"
  data-title="Bsign"
></script>

Коли встановлено data-open-trigger-id, вбудована плаваюча кнопка віджета не показується, а ваша кнопка стає trigger-елементом для відкриття чату.

Data Attributes

Loader підтримує такі атрибути на <script>:

| Атрибут | Опис | | --- | --- | | data-title | Заголовок у віджеті. Default: Chat. | | data-greeting | Перше повідомлення, яке показується на message screen. | | data-image-url | URL логотипа/зображення в header віджета. | | data-image-width | Ширина header-зображення, наприклад 120px. | | data-initial-open | Відкрити віджет після монтування: true або false. | | data-open-trigger-id | id існуючого елемента, який має відкривати віджет. | | data-message-input-position | bottom або top. Default: bottom. | | data-target | CSS selector для кастомного mount-елемента. Optional. | | data-isolate-styles | true або false. Default: true. | | data-auto-start | true або false. Default: true. | | data-events | Список event names через кому для lazy loading. | | data-widget-src | Кастомний URL/path до chatbot-widget.iife.js. | | data-api-base-url | Optional chat/session endpoint, якщо сторінці він потрібен. |

Приклад:

<div id="chatbot-root"></div>

<script
  src="https://cdn.jsdelivr.net/npm/bsign-chatbot-widget@latest/dist/chatbot-widget-loader.iife.js"
  data-target="#chatbot-root"
  data-title="Bsign Support"
  data-image-width="110px"
  data-message-input-position="top"
  data-events="pointerdown,keydown"
></script>

Розширена Конфігурація

Використовуйте window.ChatbotWidgetConfig перед підключенням loader-скрипта, якщо потрібні масиви, обʼєкти, позиціювання, theme tokens або логіка для конкретних сторінок.

За замовчуванням віджет не додає Bsign-дані, діалоги, FAQ, prompts, message form або пошук замовлень. Передавайте їх кастомно через props: articles, faqs, menuItems, messageForm, skladUsaOrders, shopifyOrders та orderImages. orderTracking лишився deprecated alias для skladUsaOrders. Повний приклад старого Bsign-наповнення збережений у examples/bsign.html.

Shopify-пошук вмикається окремою опціональною кнопкою:

shopifyOrders: {
  enabled: true,
  showMenuButton: true,
  apiBaseUrl: "https://public-api-production-64b4.up.railway.app/v1/shopify",
  storeName: "alumproject",
  menuLabel: "Find online store order"
}

Також можна передати повний endpoint через endpointUrl, наприклад https://public-api-production-64b4.up.railway.app/v1/shopify/alumproject/order.

<button id="open-chatbot-btn" type="button">
  Chat with us
</button>

<script>
  window.ChatbotWidgetConfig = {
    autoStart: true,
    target: "#chatbot-root",
    props: {
      title: "Bsign",
      greeting:
        "Hi! Tell us what you need and the Bsign team will help you with the next step.",
      openTriggerId: "open-chatbot-btn",
      chatPrompts: [
        "I need help with a custom order",
        "How long does production take?",
        "Can I see a sample first?"
      ],
      position: {
        mode: "trigger",
        gap: 12
      },
      themeTokens: {
        panelBackground: "linear-gradient(145deg, #f0f1f3 0%, #ffffff 48%, #eceff2 100%)",
        panelTextColor: "#111111",
        cardBackground: "#ffffff",
        cardBorderColor: "rgba(15, 23, 42, 0.08)",
        accentColor: "#111111",
        launcherBackground: "#111111",
        launcherColor: "#ffffff"
      }
    },
    options: {
      isolateStyles: true
    }
  };
</script>

<div id="chatbot-root"></div>

<script src="https://cdn.jsdelivr.net/npm/bsign-chatbot-widget@latest/dist/chatbot-widget-loader.iife.js"></script>

Конфіг з window.ChatbotWidgetConfig перекриває однойменні data attributes зі script tag.

Ручне Завантаження

Якщо автоматичний lazy loading не потрібен, вимкніть autoStart і викликайте loader самостійно.

<button id="load-chatbot" type="button">
  Load chat
</button>

<script
  src="https://cdn.jsdelivr.net/npm/bsign-chatbot-widget@latest/dist/chatbot-widget-loader.iife.js"
  data-auto-start="false"
></script>

<script>
  document.getElementById("load-chatbot").addEventListener("click", function () {
    ChatbotWidgetLoader.loadChatbotWidget({
      props: {
        title: "Bsign",
        initialOpen: true
      }
    });
  });
</script>

Прямий Mount Віджета

Можна не використовувати loader і монтувати віджет напряму. Це підходить, якщо потрібно завантажити основний bundle одразу.

<div id="chatbot-root"></div>

<script src="https://cdn.jsdelivr.net/npm/bsign-chatbot-widget@latest/dist/chatbot-widget.iife.js"></script>

<script>
  ChatbotWidget.mountChatbotWidget(
    "#chatbot-root",
    {
      title: "Bsign",
      initialOpen: false,
      chatPrompts: [
        "I need help with a custom order",
        "How long does production take?",
        "Can I see a sample first?"
      ]
    },
    {
      isolateStyles: true
    }
  );
</script>

Позиціювання

Використовуйте prop position у розширеній конфігурації або прямому mount.

<script>
  window.ChatbotWidgetConfig = {
    props: {
      position: {
        mode: "preset",
        preset: "bottom-right"
      }
    }
  };
</script>

Доступні presets:

bottom-right
bottom-left
top-right
top-left
bottom-center
top-center
center-right
center-left
center

Приклад з координатами:

<script>
  window.ChatbotWidgetConfig = {
    props: {
      position: {
        mode: "coordinates",
        x: 40,
        y: 140
      }
    }
  };
</script>

Приклад відкриття біля trigger-елемента:

<button id="open-chatbot-btn" type="button">Chat</button>

<script>
  window.ChatbotWidgetConfig = {
    props: {
      openTriggerId: "open-chatbot-btn",
      position: {
        mode: "trigger",
        gap: 12,
        offsetX: 0,
        offsetY: -8
      }
    }
  };
</script>

Page Context

pageContext дозволяє виконувати дії з віджетом на конкретних шляхах сайту.

<script>
  window.ChatbotWidgetConfig = {
    props: {
      pageContext: {
        "/pages/contact-us": {
          timer: 1000,
          exec: function (context) {
            context.messageOptions.setMessages(function (messages) {
              return messages.concat([
                {
                  sender: "bot",
                  content: "Leave your email and message, and the Bsign team will get back to you."
                }
              ]);
            });

            context.open.setIsOpen(true);
          }
        }
      }
    }
  };
</script>

API Endpoint

Якщо передати apiBaseUrl, віджет робить:

GET з credentials: "include" для відновлення попередніх повідомлень.

Очікувана відповідь містить data.messages:

{
  "data": {
    "messages": [
      {
        "text": "Hello",
        "type": "OUTPUT"
      },
      {
        "text": "I need help",
        "type": "INPUT"
      }
    ]
  }
}

Для cross-origin endpoints потрібно увімкнути CORS для origin сайту та credentials.