CDN／Script Tag

CDN 版本會在內部打包 React，因此你可以在靜態網站、WordPress、Webflow，或任何可加入 HTML 的頁面上使用小工具。不需要 npm、打包工具或框架。

CDN 網址

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>

<!-- Each stable release also publishes an immutable /widget/vX.Y.Z/ path
     matching the @thunderphone/widget npm version (v1.1.2 at the time of
     writing). If you pin, you own updating the URL for new releases. -->
<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/v1.1.2/style.css" />
<script src="https://cdn.thunderphone.com/widget/v1.1.2/widget.js"></script>

latest 網址是控制台嵌入程式碼產生器所產生的網址。這些網址會快取 5 分鐘，並自動取得新的穩定版本。固定的 /widget/vX.Y.Z/ 路徑不可變更，且會長期快取——若使用固定版本，請將版本與你開發時使用的 @thunderphone/widget npm 發行版本保持一致。

基本用法

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
</head>
<body>

  <div id="thunderphone"></div>

  <script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
  <script>
    ThunderPhone.mount({
      element: '#thunderphone',
      publishableKey: 'pk_live_your_publishable_key',
    })
  </script>

</body>
</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'`（淺色）/ `'#ffffff'`（深色）	用作強調色的 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() 會傳回具有清理方法的小工具執行個體：

<script>
  var widget = ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
  })

  // Later, when you want to remove the widget:
  widget.unmount()

  // Or equivalently:
  widget.destroy()
</script>

unmount() 和 destroy() 的作用相同——兩者都會中斷任何進行中的語音工作階段，並從 DOM 中移除小工具。請依照最適合你程式碼可讀性的方式使用。

在單頁式應用程式中離開頁面，或移除包含元素時，請務必清理小工具。這可確保進行中的語音工作階段會正確中斷。

範例

深色主題搭配自訂顏色

<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    theme: 'dark',
    primaryColor: '#8b5cf6',
    title: 'Talk to our AI',
  })
</script>

自訂位置

<div id="thunderphone"></div>

<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    position: 'bottom-left',
  })
</script>

搭配事件回呼

<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    onConnect: function () {
      console.log('Call started')
    },
    onDisconnect: function () {
      console.log('Call ended')
    },
    onError: function (error) {
      console.error('Widget error:', error.error, error.message)
    },
  })
</script>

搭配鈴聲

<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    ringtone: true, // or a custom URL: 'https://example.com/ringtone.mp3'
  })
</script>

使用 DOM 元素參照

<div id="thunderphone"></div>

<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  var container = document.getElementById('thunderphone')

  ThunderPhone.mount({
    element: container,
    publishableKey: 'pk_live_your_publishable_key',
  })
</script>

WordPress／CMS 整合

將以下內容加入自訂 HTML 區塊或佈景主題的頁尾：

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>

<div id="thunderphone-widget"></div>
<script>
  ThunderPhone.mount({
    element: '#thunderphone-widget',
    publishableKey: 'pk_live_your_publishable_key',
  })
</script>

<div> 可放在任何位置——它僅作為掛載點。小工具本身會以固定覆蓋層的形式顯示在檢視區角落（由 position 選項設定），不會隨周圍內容排列。

疑難排解

小工具未顯示

確認 CSS 和 JS 檔案都已載入。檢查瀏覽器主控台是否有網路錯誤。確認在呼叫 ThunderPhone.mount() 前，目標元素已存在於 DOM 中。

ThunderPhone 未定義

指令碼尚未載入。確認 widget.js 的 <script> 標籤位於掛載呼叫之前，或將掛載呼叫包裝在 DOMContentLoaded 監聽器中。

不允許網域錯誤

在 app.thunderphone.com 的 開發人員 設定中，將你的網域新增至允許的網域清單。請記得，localhost 一律允許。

Widget

CDN 網址

基本用法

掛載選項

清理

範例

深色主題搭配自訂顏色

自訂位置

搭配事件回呼

搭配鈴聲

使用 DOM 元素參照

WordPress／CMS 整合

疑難排解

後續步驟

樣式設定

React 元件

​CDN 網址

​基本用法

​掛載選項

​清理

​範例

​深色主題搭配自訂顏色

​自訂位置

​搭配事件回呼

​搭配鈴聲

​使用 DOM 元素參照

​WordPress／CMS 整合

​疑難排解

​後續步驟

樣式設定

React 元件

CDN 網址

基本用法

掛載選項

清理

範例

深色主題搭配自訂顏色

自訂位置

搭配事件回呼

搭配鈴聲

使用 DOM 元素參照

WordPress／CMS 整合

疑難排解

後續步驟