Pattern 1: Hosted Embed

UI 由 Asgard 托管, 你只需嵌入一個 URL 就能上線。

適用場景

這個模式適合以下情境:

🚀 快速 POC 驗證: 想 5 分鐘讓 AI Agent 上線給朋友、客戶試用
🌐 公開 Agent: 不在意 API Key 暴露, 或這個 Agent 本身就是設計給不特定大眾使用
🧑‍💻 無前後端開發資源: 不會寫 JS / 不想寫程式, 只會貼 iframe 標籤的人也能完成整合
📋 行銷頁、知識庫頁、Demo 頁的客服小工具: 作為網站的附屬功能, 不需要客製化 UI

如果你需要客製化聊天介面、做 per-user 驗證、或記錄稽核紀錄, 請看其他 Pattern。

架構圖

此模式不需要寫任何程式碼。所有畫面與資料流都由 Asgard 托管的前端 (embed.asgard-ai.com) 處理, 你只需把 URL 嵌入到你的網頁。

能力邊界

✅ 你能做的

嵌入 iframe 到任何網頁、Notion、Slab 等支援 iframe 的平台
在 Odin Studio Share Settings 視覺編輯器調整預設外觀(標題、Avatar、顏色主題、功能開關)
在少數需要差異化的頁面用 URL 參數覆寫個別外觀設定
設定 Bot Provider API Key 鎖住存取(輸入框驗證)
提供連結讓使用者直接開啟對話視窗(不嵌入 iframe 也可以)

❌ 你不能做的

做不到的事	為什麼
自訂訊息渲染(Custom Renderer)	畫面層 (UI Plane) 不開放, 無程式碼控制權
訊息送出前攔截、改寫、驗證	瀏覽器層 (Client Plane) 不開放
Per-user 身份驗證 / ACL	伺服器層 (Server Plane) 不開放, 只能用單一 pre-shared API Key
跨裝置的持久化 History	沒有伺服器層可保存對話, 且每次進入是全新 Channel
從你的後端動態注入 Payload 影響 Workflow	沒有伺服器層
Audit Log	同上, 稽核需要伺服器層的事件攔截

想完整理解這些限制背後的「為什麼」? → 整合架構深入解析

快速起步

步驟 1: 在 Odin Studio 設定外觀並取得 Embed URL

在對應的 App 點擊右上角「⋯」更多選單，選擇 Share Settings：

Share Settings 入口

Share Settings 是設定外觀的主要入口, 本身就是一個即時預覽的視覺編輯器, 可以調整標題、Avatar、顏色主題、功能開關（檔案上傳、對話匯出等），以及 Auth 驗證。所有嵌入此 Bot 的 iframe 都會套用這裡的預設值, 無需在每個 URL 帶參數。完整欄位說明見下方客製化外觀。

設定完成後，點擊 Embed 複製 iframe 標記，或點擊 Copy 複製 URL：

Embed / Copy 按鈕

儲存設定

取得後 URL 格式如下:

https://embed.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderName}

步驟 2: 嵌入 iframe

把 iframe 標記貼到你的網頁 HTML 中即可:

<iframe
  src="https://embed.asgard-ai.com/ns/your-namespace/bot-provider/your-bot"
  width="400"
  height="600"
  style="border: 0; border-radius: 12px;"
></iframe>

完成。打開頁面就能看到聊天介面。

客製化外觀

Hosted Embed 的外觀客製化以 Odin Studio 的 Share Settings 為主, 它是一個即時預覽的視覺編輯器, 改動會立刻反映在右側預覽。在此儲存的欄位即為所有嵌入此 Bot 的 iframe 預設值, 不必每個頁面都帶 URL 參數。

編輯器介面

進入 Share Settings 後, 畫面分成兩欄: 左側列出所有可調整的外觀欄位, 右側是 iframe 即時預覽。

Share Settings 編輯器

可調整的欄位

常用的視覺欄位包含:

Bot Title: 聊天視窗標題
Typing Placeholder: Bot 思考中時顯示的提示文字
Avatar: Bot 頭像圖片
背景色 / 文字色 / Bot 訊息泡泡色: 用色碼或內建挑選器設定

文字類欄位:

文字欄位設定

色彩欄位可直接輸入 hex 色碼, 或用挑選器選色:

色彩設定

Avatar 圖片規格

Avatar 上傳

圖片要求

格式: JPG、PNG、JPEG
大小上限:3 MB
建議尺寸:640 × 640 px(正方形, 避免裁切變形)

別忘記儲存

修改完成後務必點擊右下角的儲存, 變更才會套用到實際 Embed URL。

進階: 用 URL 參數覆寫外觀

大多數情境下, 在 Share Settings 設定預設值就夠了。只有同一個 Bot 嵌入到不同頁面、且各頁要呈現不同外觀時(例如同一個客服 Bot 嵌入到行銷頁與支援頁, 標題、顏色不同), 才建議用 URL 參數覆寫。

URL 參數會覆寫 Share Settings 的預設值, 寫在 query string 中即可:

<iframe
  src="https://embed.asgard-ai.com/ns/your-namespace/bot-provider/your-bot?title=客服小幫手&bgColor=f8f9fa&botBgColor=ffffff&fullScreen=1"
  width="100%"
  height="100%"
></iframe>

常用 URL 參數

參數	說明	範例
`title`	聊天視窗標題	`?title=客服小幫手`
`avatar`	Bot 頭像 URL	`?avatar=https://...`
`inputPlaceholder`	輸入框提示文字	`?inputPlaceholder=請輸入問題`
`botTypingPlaceholder`	Bot 思考中提示文字	`?botTypingPlaceholder=思考中...`
`key`	Bot Provider API Key(如有設定 Auth)	`?key=xxx`
`fullScreen`	全螢幕版型,`0` 或 `1`	`?fullScreen=1`
`enableUpload`	啟用檔案上傳,`0` 或 `1`	`?enableUpload=1`
`enableExport`	啟用對話匯出,`0` 或 `1`	`?enableExport=1`
`enableDocumentUpload`	啟用文件上傳,`0` 或 `1`	`?enableDocumentUpload=1`
`maintainConnectionWhenClosed`	視窗關閉後保持連線	`?maintainConnectionWhenClosed=1`
`defaultLinkTarget`	連結開啟方式	`?defaultLinkTarget=_blank`
`bgColor`	聊天背景色(不含 `#`)	`?bgColor=f8f9fa`
`botBgColor`	Bot 訊息泡泡背景	`?botBgColor=ffffff`
`botTextColor`	Bot 訊息文字顏色	`?botTextColor=333333`
`userBgColor`	使用者訊息泡泡背景	`?userBgColor=0066cc`
`userTextColor`	使用者訊息文字顏色	`?userTextColor=ffffff`
`debug`	開啟 Debug Console	`?debug=1`

API Key 驗證行為

Hosted Embed 的驗證機制取決於 Bot Provider 端的設定:

情境 A: Bot Provider 未設定 API Key(公開模式)

任何人都可以開啟 URL 直接使用。適合公開的 Agent 或 Demo。

情境 B: Bot Provider 已設定 API Key

首次進入頁面會跳出密碼輸入框讓使用者輸入 API Key：

密碼驗證視窗

輸入正確後, 瀏覽器會在 localStorage 記住該 Key, 下次再開啟相同網址就不會再跳。

要調整驗證設定, 前往 Apps → Integration → 選擇你的 Integration 右上角更多選單 → Edit, 切換 Auth 開關與設定 API Key 即可：

Auth 設定

API Key 是 pre-shared 密碼

這個 API Key 是一個「共享密碼」概念 — 凡是知道這把 Key 的人都能存取這個 Bot, 無法區分個別使用者。若你需要 per-user 身份驗證(誰、哪個帳號、什麼權限), 請看 Workflow Auth 或 Backend Relay。

限制與注意事項

每次進入頁面 = 全新 Channel: Hosted Embed 為每次造訪產生一個新的 customChannelId(UUID 隨機生成), AI 不會記得使用者前次造訪的對話。如果你需要保留對話, 請看 Direct Connect 或 Backend Relay。
互動行為是「寫死」的: 你不能修改送出訊息時帶的 Payload、不能在訊息送出前/後注入邏輯、不能改寫 UI 元件。如果你需要這些彈性, 請看其他 Pattern。
API Key 對所有使用者相同: 無法區分使用者身份。
URL 參數有上限: 複雜的客製化(例如完整自訂訊息渲染)只能用 SDK 達成。

適用場景​

架構圖​

能力邊界​

✅ 你能做的​

❌ 你不能做的​

快速起步​

步驟 1: 在 Odin Studio 設定外觀並取得 Embed URL​

步驟 2: 嵌入 iframe​

客製化外觀​

編輯器介面​

可調整的欄位​

Avatar 圖片規格​

進階: 用 URL 參數覆寫外觀​

常用 URL 參數​

API Key 驗證行為​

情境 A: Bot Provider 未設定 API Key(公開模式)​

情境 B: Bot Provider 已設定 API Key​

限制與注意事項​

延伸閱讀​