---
title: "Reactコンポーネント"
description: "ThunderPhone音声ウィジェットをReactアプリケーションに埋め込む"
---

`ThunderPhoneWidget` コンポーネントは、ミュート、通話終了、接続ステータス表示の組み込みコントロールを備えたガラスモーフィックな通話バーをレンダリングします。React アプリに音声AIを追加する最も迅速な方法です。

## インストール

```bash
npm install @thunderphone/widget
```

## 基本的な使用方法

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

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}
```

<Warning>
  ウィジェットを正しくレンダリングするには、CSS ファイルをインポートする**必要があります**。インポートしない場合、ウィジェットはスタイルなしで表示されます。
</Warning>

---

## Props

コンポーネントは `ThunderPhoneWidgetProps` を介して以下の props を受け取ります。

| プロパティ | 型 | 必須 | デフォルト | 説明 |
|------|------|----------|---------|-------------|
| `publishableKey` | `string` | はい | -- | ダッシュボードの **Web Widgets** にある公開可能 API キー（`pk_live_...`）。エージェントはキーのウィジェット設定から自動的に解決されます。 |
| `theme` | `'light' \| 'dark'` | いいえ | `'light'` | カラースキーム。ウィジェットのルートに `tp--light` または `tp--dark` クラスを適用します。 |
| `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 ベース URL のオーバーライド。 |
| `language` | `string` | いいえ | -- | セッションごとの言語オーバーライド。`en`、`es`、`fr-FR` などの言語コードまたはロケールを指定します。未設定の場合は、エージェントに設定された言語が適用されます。キーの [ブラウザーオーバーライド](/ja/guides/embed-web-widget) で `language` を設定する必要があります。 |
| `voice` | `string` | いいえ | -- | セッションごとの音声オーバーライド。`maria` などの音声名を指定します。未設定の場合は、エージェントに設定された音声が適用されます。キーの [ブラウザーオーバーライド](/ja/guides/embed-web-widget) で `voice` を設定する必要があります。 |
| `context` | `string` | いいえ | -- | エージェントに渡すセッションごとの事実に基づくページまたはサイトのコンテキスト（例: 訪問者が閲覧しているページの詳細）。サーバー側で 12,000 文字に切り詰められます。キーの [ブラウザーオーバーライド](/ja/guides/embed-web-widget) で `context` を設定する必要があります。 |
| `onConnect` | `() => void` | いいえ | -- | 音声セッションが正常に接続されたときに呼び出されます。 |
| `onDisconnect` | `() => void` | いいえ | -- | セッションが終了したときに呼び出されます。 |
| `onError` | `(error) => void` | いいえ | -- | エラー発生時に呼び出されます。`error` オブジェクトには `error`（コード）フィールドと `message` フィールドがあります。 |
| `className` | `string` | いいえ | -- | ウィジェットコンテナに適用する追加の CSS クラス名。 |
| `ringtone` | `boolean \| string` | いいえ | `false` | 接続中に着信音を再生します。デフォルトの着信音には `true`、カスタム音声には URL 文字列を指定します。 |

---

## 例

### カスタムカラーを使用したダークテーマ

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

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

### カスタム位置

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

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}
```

### セッションごとの言語、音声、コンテキスト

通話の開始時に、`language`、`voice`、`context` プロパティはセッションリクエスト（`POST /widget/session`）に転送され、そのセッションにおけるエージェントの設定済みデフォルトを上書きします。使用する各プロパティを、ダッシュボードのウィジェットの **ブラウザオーバーライド**（またはキーの `allowed_overrides`）で有効にします。新しいウィジェットではいずれも許可されておらず、無効なオーバーライドを含むセッションリクエストは `400 override_not_allowed` で失敗します。[ブラウザオーバーライド](/ja/guides/embed-web-widget)を参照してください。

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

function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}
```

`context` を使用して、訪問者が表示しているページに関する事実情報（製品の詳細、価格、ページ固有のよくある質問など）をエージェントに提供します。エージェントはこれを指示ではなくページコンテンツとして扱います。サーバー側で12,000文字に切り詰められます。

### イベントコールバックを使用

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

function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}
```

### カスタムスタイルを使用

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

function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}
```

```css
.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}
```

利用可能なすべてのCSSクラスとカスタムプロパティについては、[スタイリングガイド](/ja/widget/styling)を参照してください。

### 着信音を使用

接続の確立中に電話の着信音を再生します。

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

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}
```

音声ファイルのURLを渡してカスタム着信音を使用します。

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>
```

ウィジェットが`connecting`状態の間は着信音がループし、エージェントが接続するとスムーズにフェードアウトします。

### カスタムAPIベースを使用

<Tip>
  セルフホスト型またはプロキシAPIエンドポイントを使用している場合にのみ、`apiBase`を設定する必要があります。デフォルトでは`https://api.thunderphone.com/v1`が指定されています。
</Tip>

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>
```

---

## エラー処理

`onError`コールバックが実行されると、次の2つのフィールドを持つエラーオブジェクトを受け取ります。

| フィールド | 型 | 説明 |
|-------|------|-------------|
| `error` | `string` | 機械可読なエラーコード |
| `message` | `string` | 人間が読めるエラー説明 |

一般的なエラーコードには、許可されていないドメイン、エージェントが見つからない、無効なAPIキーなどがあります。

---

## 次のステップ

<CardGroup cols={2}>
  <Card title="ヘッドレスフック" icon="code" href="/ja/widget/headless-hook">
    UIを完全に制御するには、代わりに `useThunderPhone` フックを使用します。
  </Card>
  <Card title="スタイリング" icon="palette" href="/ja/widget/styling">
    CSSカスタムプロパティで色、サイズ、レイアウトをカスタマイズします。
  </Card>
</CardGroup>