--- title: "CDN／Script Tag" description: "無需使用打包工具，即可將 ThunderPhone 語音小工具加入任何網站" --- CDN 版本已內置 React，因此你可在靜態網站、WordPress、Webflow，或任何可加入 HTML 的頁面上使用小工具。無需 npm、打包工具或框架。 ## CDN 網址 ```html Latest (recommended) ``` ```html Pinned version ``` `latest` 網址由控制台的嵌入程式碼產生器建立。它們會快取 5 分鐘，並自動套用新的穩定版本。固定版本的 `/widget/vX.Y.Z/` 路徑不可變更，並會長期快取——如使用固定版本，請確保版本與你開發時使用的 `@thunderphone/widget` npm 發布版本一致。 --- ## 基本用法 ```html

``` 小工具會掛載至目標元素，並以檢視區角落的**固定位置列**方式顯示（預設為 `bottom-right`，可透過 `position` 選項控制）。掛載元素只用作 React 根節點——它在頁面中的位置不會影響小工具的顯示位置。 --- ## 掛載選項 `ThunderPhone.mount()` 接受與 React 元件相同的選項，另加 `element` 屬性： | 選項 | 類型 | 必填 | 預設值 | 說明 | |--------|------|----------|---------|-------------| | `element` | `string \| HTMLElement` | 是 | -- | CSS 選擇器（例如 `'#thunderphone'`）或 DOM 元素參照。 | | `publishableKey` | `string` | 是 | -- | 可公開 API 金鑰（`pk_live_...`）。系統會根據金鑰的小工具設定自動識別智能體。 | | `theme` | `'light' \| 'dark'` | 否 | `'light'` | 色彩配置。 | | `primaryColor` | `string` | 否 | `'#000000'` (light) / `'#ffffff'` (dark) | 用作強調色的 CSS 色彩字串。 | | `title` | `string` | 否 | `'Voice assistant'` | 顯示於小工具列的文字。 | | `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | 否 | `'bottom-right'` | 固定於檢視區的位置。 | | `apiBase` | `string` | 否 | `'https://api.thunderphone.com/v1'` | 覆寫 API 基礎網址。 | | `language` | `string` | 否 | -- | 按工作階段覆寫語言——可使用語言代碼或地區設定，例如 `en`、`es` 或 `fr-FR`。如未設定，將使用智能體已設定的語言。 | | `voice` | `string` | 否 | -- | 按工作階段覆寫語音——可使用語音名稱，例如 `maria`。如未設定，將使用智能體已設定的語音。 | | `context` | `string` | 否 | -- | 按工作階段將頁面或網站的事實內容傳送至智能體。伺服器端會截斷至 12,000 個字元。 | | `onConnect` | `() => void` | 否 | -- | 語音工作階段連線時呼叫。 | | `onDisconnect` | `() => void` | 否 | -- | 工作階段結束時呼叫。 | | `onError` | `(error) => void` | 否 | -- | 發生錯誤時呼叫。錯誤包含 `error`（代碼）及 `message` 欄位。 | | `ringtone` | `boolean \| string` | 否 | `false` | 連線期間播放鈴聲。`true` 使用預設鈴聲，或使用 URL 字串指定自訂音訊。 | --- ## 清理 `ThunderPhone.mount()` 會傳回一個具備清理方法的小工具執行個體： ```html ``` `unmount()` 與 `destroy()` 的作用相同——兩者均會中斷任何進行中的語音工作階段，並從 DOM 移除小工具。請按你的程式碼可讀性選用。在單頁應用程式中離開頁面時，或移除包含元素時，請務必清理小工具。這可確保進行中的語音工作階段已正確中斷。 --- ## 範例 ### 深色主題及自訂顏色 ```html

``` ### 自訂位置 ```html

``` ### 使用事件回調 ```html

``` ### 使用鈴聲 ```html

``` ### 使用 DOM 元素參照 ```html

``` ### WordPress / CMS 整合將以下內容加入自訂 HTML 區塊或你的主題頁尾： ```html ``` `

` 可放置於任何位置——它僅作為掛載點。小工具本身會以固定覆蓋層形式顯示於視窗角落（由 `position` 選項設定），不會隨周邊內容排列。 --- ## 疑難排解確保 CSS 及 JS 檔案均已載入。在瀏覽器主控台檢查網絡錯誤。呼叫 `ThunderPhone.mount()` 前，確認目標元素已存在於 DOM 中。指令碼尚未載入。確保 `widget.js` 的 `