跳至主要内容

REFERENCE

SDK 範例

@asgard-js/core 與 @asgard-js/react 的用法與可以直接操作的範例。

嵌入與整合

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

提示

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

  1. 1. Inline 內嵌（預設）​

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

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

  2. 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. 3. fullScreen 全螢幕​

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

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

  4. 框架整合​

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

  5. 也看看​

準備好開始了嗎？

想知道 Asgard 怎麼用在你的團隊？跟我們聊聊。

聯絡我們