嵌入與整合

@asgard-js/react 只提供 <Chatbot> 核心元件，沒有內建浮動視窗或開關按鈕—— 這讓你能自由決定要怎麼把它放上自己的網站。本頁整理三種常見擺放方式。

提示

不論哪種方式，在 SSR 框架（Next.js、Docusaurus…）都要做 client-only 包裝， 詳見 快速開始的 SSR 章節。

1. Inline 內嵌（預設）

最簡單的方式：把 <Chatbot> 放進一個固定尺寸的容器，它會填滿父層。 尺寸建議交給 theme 控制，詳見 尺寸調整。

<div style={{ width: 420, height: 640 }}>
  <Chatbot
    config={{ botProviderEndpoint: BOT_PROVIDER_ENDPOINT }}
    customChannelId="user-123"
  />
</div>

2. 浮動 launcher widget

最常見的網站客服樣式：右下角一顆按鈕，點擊後彈出聊天視窗。 SDK 不提供這個外殼，但只要用一個 isOpen state 自己包就好—— 用 <Chatbot> 的 onClose callback 在使用者按關閉鈕時收合。

點右下角的按鈕開啟浮動聊天視窗；按視窗右上角的關閉鈕（或再按一次按鈕）即可收合。

import { useState } from "react";
import { Chatbot } from "@asgard-js/react";

export function FloatingChatbot() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      {isOpen && (
        <div style={{ position: "fixed", bottom: 96, right: 24 }}>
          <Chatbot
            config={{ botProviderEndpoint: BOT_PROVIDER_ENDPOINT }}
            customChannelId="user-123"
            theme={{ chatbot: { width: "360px", height: "520px" } }}
            onClose={() => setIsOpen(false)}
          />
        </div>
      )}
      <button
        style={{ position: "fixed", bottom: 24, right: 24 }}
        onClick={() => setIsOpen((open) => !open)}
      >
        {isOpen ? "關閉" : "聊聊"}
      </button>
    </>
  );
}

關閉時要不要保留連線？

按 header 的關閉鈕時，SDK 預設會斷開 SSE 連線，下次開啟即重新連線。 如果你希望關閉時仍在背景接收訊息（例如未讀提示），加上 maintainConnectionWhenClosed：

<Chatbot
  config={{ botProviderEndpoint: BOT_PROVIDER_ENDPOINT }}
  customChannelId="user-123"
  maintainConnectionWhenClosed
  onClose={() => setIsOpen(false)}
/>

Prop	行為
onClose	使用者按 header 關閉鈕時觸發；通常在這裡收合視窗
maintainConnectionWhenClosed	關閉時保留 SSE 連線（預設 false，會斷線）

3. fullScreen 全螢幕

手機或專屬聊天頁適合用 fullScreen，<Chatbot> 會改用 fixed 全視窗容器， 覆蓋整個 viewport，並處理 iOS 虛擬鍵盤與防止 scroll chaining。

<Chatbot
  config={{ botProviderEndpoint: BOT_PROVIDER_ENDPOINT }}
  customChannelId="user-123"
  fullScreen
/>

框架整合

各框架的 client-only 包裝寫法（Next.js App Router / Pages Router、Docusaurus、Vite） 已整理在 快速開始 的 SSR 章節。 上述三種擺放方式都套用同一套包裝原則。

也看看

• 尺寸調整 — 用 theme 控制寬高與 RWD
• 快速開始 — 安裝與 SSR 包裝
• Chatbot Props — fullScreen、onClose、maintainConnectionWhenClosed 等完整 props