> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 可嵌入式語音小工具

> 只需幾行程式碼，即可將語音人工智慧智慧體加入任何網站

ThunderPhone 可嵌入式語音小工具可讓你的網站訪客直接從瀏覽器與 AI 智慧體交談。不需要撥打電話——使用者只要點擊按鈕，即可開始由 ThunderPhone 驅動的即時語音對話。

此小工具會呈現為可適應淺色與深色主題的玻璃擬態橫條，並支援自訂強調色與位置。它以 `@thunderphone/widget` npm 套件形式發布，也可透過 CDN 用於未使用打包工具的環境。

<Frame>
  <img src="https://mintcdn.com/thunderphone/4XhPaCl4RGfyS7_M/images/widget-showcase.png?fit=max&auto=format&n=4XhPaCl4RGfyS7_M&q=85&s=17fea4fe853f3548b9b2628c9d4c4fc0" alt="淺色與深色主題中的 ThunderPhone 小工具，搭配各種強調色" width="1200" height="800" data-path="images/widget-showcase.png" />
</Frame>

## 先決條件

嵌入小工具前，請先在 [ThunderPhone 控制台](https://app.thunderphone.com)完成以下三個步驟：

<Steps>
  <Step title="建立可公開的 API 金鑰">
    前往控制台設定中的 **開發人員**，並建立可公開的金鑰。可公開金鑰以 `pk_live_` 開頭，可安全地包含在用戶端程式碼中。
  </Step>

  <Step title="設定允許的網域">
    在相同的開發人員設定中，新增要嵌入小工具的網域。開發時一律允許使用 `localhost`。支援萬用字元（例如 `*.example.com`）。
  </Step>

  <Step title="建立網頁小工具">
    前往控制台中的 **網頁小工具**，並建立一個小工具。選擇你要公開的智慧體及要使用的可公開金鑰。系統會根據你的可公開金鑰設定自動解析智慧體。
  </Step>
</Steps>

<Warning>
  可公開金鑰（`pk_live_...`）**不**等同於你的私密 API 權杖。可公開金鑰專為用戶端使用而設計，且僅適用於你允許網域上的小工具工作階段。切勿在用戶端程式碼中使用私密 API 權杖。
</Warning>

***

## 快速開始

安裝套件：

```bash theme={null}
npm install @thunderphone/widget
```

將小工具加入你的應用程式：

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}
```

完成。你的使用者將看到玻璃擬態通話橫條，只要點擊一下即可連線至你的 AI 智慧體。

***

## 自訂

此小工具提供四個外觀 prop：

| Prop           | 預設值                              | 說明                                                                |
| -------------- | -------------------------------- | ----------------------------------------------------------------- |
| `theme`        | `'light'`                        | 白色玻璃使用 `'light'`，深色玻璃使用 `'dark'`                                  |
| `primaryColor` | `'#000000'`（淺色）/ `'#ffffff'`（深色） | 開始按鈕、波形與連線指示器的強調色                                                 |
| `title`        | `'Voice assistant'`              | 顯示於小工具中的文字                                                        |
| `position`     | `'bottom-right'`                 | 檢視區角落：`'bottom-right'`、`'bottom-left'`、`'top-right'`、`'top-left'` |

<CodeGroup>
  ```tsx Light theme (default) theme={null}
  <ThunderPhoneWidget
    publishableKey="pk_live_your_publishable_key"
  />
  ```

  ```tsx Dark theme with custom color theme={null}
  <ThunderPhoneWidget
    publishableKey="pk_live_your_publishable_key"
    theme="dark"
    primaryColor="#8b5cf6"
    title="Ask our AI"
  />
  ```
</CodeGroup>

另外三個 prop 用於自訂工作階段，而非外觀——通話開始時都會轉送至工作階段請求：

| Prop       | 說明                                              |
| ---------- | ----------------------------------------------- |
| `language` | 每個工作階段的語言覆寫——使用如 `en`、`es` 或 `fr-FR` 的語言代碼或地區設定 |
| `voice`    | 每個工作階段的語音覆寫——使用如 `maria` 的語音名稱                  |
| `context`  | 傳遞給智慧體的頁面或網站事實背景資訊（伺服器端會截斷為 12,000 個字元）         |

請參閱 [React 元件參考資料](/zh-Hant/widget/react)，取得完整的 prop 表格。

若要建立完全自訂的 UI，請使用 [無介面 hook](/zh-Hant/widget/headless-hook) 管理語音工作階段，同時建構自己的介面。此 hook 會提供即時音訊音量，供你建立隨音訊反應的視覺效果。

***

## 整合選項

選擇適合你的技術堆疊的整合方式：

<CardGroup cols={3}>
  <Card title="React 元件" icon="react" href="/zh-Hant/widget/react">
    預先建置的 UI 元件，內建通話控制項與狀態顯示。匯入、傳入 props，即可完成。
  </Card>

  <Card title="無頭 Hook" icon="code" href="/zh-Hant/widget/headless-hook">
    完整掌控 UI。`useThunderPhone` Hook 會管理語音工作階段，同時讓你建立自己的介面。
  </Card>

  <Card title="CDN／指令碼標籤" icon="globe" href="/zh-Hant/widget/cdn-script-tag">
    不需要打包工具。透過指令碼標籤載入小工具，適用於靜態網站、WordPress 及其他非 React 環境。
  </Card>
</CardGroup>

***

## 樣式設定

小工具內建由 `theme` prop 控制的淺色與深色主題，以及由 `primaryColor` prop 控制的強調色。如需更深入的自訂，你可以覆寫 CSS 自訂屬性與類別。詳情請參閱[樣式設定指南](/zh-Hant/widget/styling)。

<Note>
  需要協助嗎？請透過 [support@thunderphone.com](mailto:support@thunderphone.com) 聯絡我們
</Note>