跳至主要内容

REFERENCE

SDK 範例

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

快速開始

本頁帶你從零安裝、跑出第一個可以對話的 <Chatbot>。

還沒有 Bot Provider？

本頁假設你已經有一個 Bot Provider endpoint。如果還沒有，先看 整合總覽：了解完整開發流程、如何在 Odin 建立 Bot， 以及該選哪種整合模式（Direct Connect / Backend Relay / Hosted Embed）。

  1. 安裝套件​

    npm install @asgard-js/core @asgard-js/react

    兩個套件都必要：

    • @asgard-js/core — 底層 SSE client、channel、conversation 模型
    • @asgard-js/react — React 元件、hooks、與內建聊天室 UI

  2. 取得 Bot Provider Endpoint​

    Endpoint 格式固定為：

    https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderId}

    在 Odin Studio 建立並發佈 Bot Provider 後即可取得 endpoint 與憑證。延伸閱讀：

    SDK 會自動從這個 base URL 衍生出 SSE endpoint (${botProviderEndpoint}/message/sse) 與 blob upload endpoint。

  3. 引入 CSS​

    import "@asgard-js/react/style";

    這一行務必執行一次，否則 chatbot 會沒有樣式。CSS 對應到 @asgard-js/react/dist/index.css。

  4. 渲染 <Chatbot>​

    import { Chatbot } from "@asgard-js/react";
    import "@asgard-js/react/style";
     
    export function App() {
      return (
        <Chatbot
          title="我的聊天機器人"
          customChannelId="user-123"
          config={{
            botProviderEndpoint:
              "https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderId}",
          }}
        />
      );
    }

    兩個必填，加一個常用的：

    Prop必填說明
    config.botProviderEndpoint✓上一步取得的 URL
    customChannelId✓你這端唯一代表一個對話頻道的 ID，通常用 user id 或 session id
    title顯示在 header 的標題

    完整 props 表請見 Chatbot Props。

  5. SSR / Next.js / Docusaurus 注意事項​

    @asgard-js/react 依賴 window、MediaRecorder、ResizeObserver 等瀏覽器 API，不能在 server 上執行。所有 SSR 框架都要做 client-only 包裝：

    Next.js (App Router)​

    @asgard-js/react 依賴瀏覽器 API，即使在 "use client" 元件中仍需搭配 dynamic + ssr: false 避免 server-side pre-render 失敗。Style import 放在 dynamic 之外，讓 Next.js 靜態分析到 CSS：

    "use client";
     
    import dynamic from "next/dynamic";
    import "@asgard-js/react/style";
     
    const Chatbot = dynamic(
      () => import("@asgard-js/react").then((m) => m.Chatbot),
      { ssr: false },
    );
     
    export default function ChatPage() {
      return (
        <div style={{ height: "100vh" }}>
          <Chatbot
            title="我的聊天機器人"
            customChannelId="user-123"
            config={{
              botProviderEndpoint:
                "https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderId}",
            }}
          />
        </div>
      );
    }
    備註

    <Chatbot> 會填滿父容器高度，因此父元素需要有明確的高度（範例用 100vh）。

    Next.js (Pages Router)​

    import dynamic from "next/dynamic";
     
    const Chatbot = dynamic(
      () => import("@asgard-js/react").then((m) => m.Chatbot),
      { ssr: false },
    );

    Docusaurus / Gatsby​

    import BrowserOnly from "@docusaurus/BrowserOnly";
     
    export default function MyPage() {
      return (
        <BrowserOnly>
          {() => {
            const { Chatbot } = require("@asgard-js/react");
            require("@asgard-js/react/style");
            return <Chatbot title="..." customChannelId="..." config={{ botProviderEndpoint: "..." }} />;
          }}
        </BrowserOnly>
      );
    }

    Vite / CRA​

    純 SPA 沒有 SSR，可以直接 top-level import，不需要額外處理。

  6. 下一步​

準備好開始了嗎？

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

聯絡我們